Getting started: agents & MCP

This is the full path from nothing to an agent that can act through Okashic: create the agent, configure its MCP client, give it access to one service, and run a prompt that proves the connection works. It takes a few minutes.

You need a running broker. The broker ships inside the macOS and Android apps; if your agent runs on a server, see Run the headless broker first. The commands below use the okashic command-line client, which talks to whatever broker is running — a headless one or the serving desktop.

1. Create the agent and get its key

An agent identifies itself to Okashic with its own API key. Create one:

terminal

okashic agent create claude-code

The command prints the key once and the exact MCP config to paste next:

output

created agent agt_7f3a… (claude-code)

API key (shown once — store it now):
  okk_live_9c2b…

This key is how you link the agent: point its MCP client at this broker with it.

Copy the key now — it is shown once. If you lose it, create a new agent and revoke the old one.

The key is a bearer token

Anyone holding the key can act as this agent. Store it the way you’d store a password, and revoke it (okashic agent create issues a fresh one; revoke from the app) the moment a key leaks.

2. Point the agent’s MCP client at the broker

The broker serves a local MCP endpoint over HTTP at http://127.0.0.1:8765/mcp. The agent authenticates with the key as a bearer token. For a client that reads an MCP JSON config — such as Claude Code or Claude Desktop — add the broker as a server:

mcp config

{
  "mcpServers": {
    "okashic": {
      "type": "http",
      "url": "http://127.0.0.1:8765/mcp",
      "headers": { "Authorization": "Bearer okk_live_9c2b…" }
    }
  }
}

Use the real key in place of okk_live_9c2b…. The endpoint is loopback-only: the agent must run on the same machine as the broker, or reach it over a private tunnel. See Run the headless broker for widening the bind when an agent runs in a container.

Restart the agent so it reads the new config. It should now list okashic among its tools.

3. Give the agent a connection

With the key in place, the agent can read your vault context. To act on an outside service it needs a connection, and only you create one. Connect a service in the app, or from the CLI. For a token-based API like GitHub:

terminal

okashic connection add --manifest github --label "Work GitHub" --token ghp_…

connection add prints the connection id and syncs to your other devices on its own, so the connection appears in the app within seconds. Once it exists, any agent with a valid key can use it.

To narrow that, open the connection’s access in the app. Keep it open to all your agents, or limit it to the ones you choose. On an API connection you can also pick which operations each agent may call.

4. Confirm the whole path works

Ask the agent to do one small, read-only thing through Okashic and report back. A good first prompt:

Using the okashic MCP server, list my connections and tell me what you can reach.

The agent calls Okashic, gets the connections it can use, and names them. If it can see the connection from step 3, the path is live: key, MCP, connection, and broker all working together.

Then confirm it reads real data:

Through okashic, list the files in my vault and summarize what’s there.

What you just set up

• An agent with its own key, which you can revoke any time to cut it off immediately.
• Its MCP client pointed at your broker, authenticating with that key.
• One connection the agent can use, open to your agents by default and narrowable to the ones you choose.
• An audit log entry for every call the agent just made. Open it in the app to see the run.

To go deeper on the access model, see Connections. To understand where the broker sits between your devices and the cloud, see Devices, broker, cloud.