Connect over MCP

Yokka’s MCP server is stateless JSON over Streamable HTTP. It runs at https://api.yokka.ai. For the steps in each app (Claude Code, Codex, the Claude app, ChatGPT, Cursor, VS Code), see the Quickstart.

Endpoints

Endpoint	Authentication	Use it when
`POST /mcp/c/<token>`	The token is in the path	Your client takes a URL and nothing else.
`POST /mcp`	`Authorization: Bearer <token>` header	Your client can send headers, or links are off.

Both endpoints serve the same tools. Only authentication differs.

Try it with curl

tools/list needs no handshake, so this is a quick way to check a token:

curl -s https://api.yokka.ai/mcp \
  -H "Authorization: Bearer $YOKKA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

And a tool call:

curl -s https://api.yokka.ai/mcp \
  -H "Authorization: Bearer $YOKKA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_next_card","arguments":{}}}'

Every tool result is text for the agent to read, usually ending with the next step to take. Every successful call also returns the same facts as structuredContent, matching the tool’s outputSchema.

Protocol versions

The server speaks both generations of the protocol:

2026-07-28: clients discover the server with server/discover and send MCP-Protocol-Version (plus Mcp-Method and Mcp-Name, which must match the request body) on each request. No session is needed.
2025 releases: the initialize handshake, with the server returning an Mcp-Session-Id header. Requests without a version header are treated as this generation.

An unsupported version gets a 400 listing the versions the server supports. Clients on 2025-03-26 may send JSON-RPC batches of up to 20 messages; each request in the batch is answered and notifications are dropped. Every message counts against the token’s rate limit. Batching was removed from the protocol in 2025-06-18, so a batch from a client speaking that version or later gets a 400.

Each initialize starts an agent session of its own, which the client names with Mcp-Session-Id from then on, so two Claude Code windows on one token are two agents that hold their own cards. A 2026-07-28 client keeps no session: its calls, like REST calls, act as the latest session of their token and client name, if it was active in the last 30 minutes. After a restart, a new session picks up the cards its earlier one held once that one has been quiet for 2 minutes (Claims).

A token keeps at most 20 sessions that were active in the last day. Past that, a new connection shares the latest session of the same client instead of starting another.

Read-only tokens

A read-only token’s tools/list only returns list_projects, get_board, get_card, get_card_activity, find_cards and get_next_card (get_flow_rules needs the board.manage permission, which only write tokens have). See Agent access.

One project per repo

With more than one project, an agent has to know which one a repo belongs to. Tools that change the board, and get_next_card, refuse to guess when you leave out project: they list the projects and ask the agent to name one. The repo’s AGENTS.md section names it, and you can go further and give the repo a connection that reaches only its project.

In Project settings → Prompts → Repo instructions (or on the connect screen), open Or connect this repo to … only and create a connection. It makes a token limited to that project (a Pro feature) and gives you a Claude Code command to run in the repo’s folder:

claude mcp add --transport http --scope local yokka https://…/mcp/c/<token>

--scope local keeps the server for that folder alone, outside any file you commit, and under the usual name it takes the place of your everyday connection there. Agents in the repo then can’t reach another project at all. For other agents, add the link in the repo’s own MCP settings, never in a committed file.

Errors and limits

Status	Meaning
`202`	The request held only notifications (or responses), so there’s nothing to answer. No body.
`400`	The body isn’t valid JSON-RPC, the protocol version isn’t supported, or a batch is too big or not allowed.
`401`	Missing, invalid, revoked or expired token, or a private link used while links are turned off for the workspace.
`204`	A `DELETE` with `Mcp-Session-Id` ended that session. Cards it still held are released, except any waiting on you.
`404`	A `DELETE` naming a session that isn’t this token’s, or that already ended.
`405`	A `GET` on `/mcp`. The server has no event stream: send `POST`.
`413`	The request body is over 1 MB.
`429`	Too many calls for this token, or too many failed sign-ins from your address. Wait `Retry-After` seconds.

Invalid tool arguments come back as a JSON-RPC error with a readable message, like Invalid arguments for claim_card: "card" is required.

Everything else a tool refuses (a card another agent holds, a plan limit, a sandbox out of calls, an archived project) comes back as the tool’s result with isError: true and a sentence to act on. A failed call changes nothing: its writes are undone together.

Archived projects are read-only for agents, as in the app. Tools leave them out of listings (list_projects takes include_archived), read them when you name them, and refuse any change.

Archived cards work the same way: they’re off the board, get_card still reads them, find_cards lists them only with archived, and every change is refused until unarchive_card puts the card back.