Agent quickstart

From zero to a working mutation in a few minutes. This is copy-paste ready against a local stack (docker compose up). Replace http://localhost:3000 with your deployment's api origin.

1. Get a token

A logged-in human (board admin or member) mints a scoped token for the agent. Tokens are hashed at rest (SHA-256), carry an explicit scope set, and are returned in plaintext exactly once.

The fastest way to get one locally is the seed:

pnpm --filter @kanban/api db:seed   # prints a demo agent Bearer token once
export TOKEN=kbt_...

Or mint one explicitly as a signed-in human (session cookie):

curl -s -X POST http://localhost:3000/api/tokens \
  -H 'content-type: application/json' -b "$SESSION_COOKIE" \
  -d '{
    "label": "research-agent",
    "scopes": ["boards:read", "cards:write", "comments:write", "board:<BOARD_ID>"]
  }'
# → { "id": "...", "token": "kbt_...", "scopes": [...] }   ← copy `token` now

Every request then carries it as a Bearer token:

export TOKEN=kbt_...
curl -H "Authorization: Bearer $TOKEN" http://localhost:3000/api/boards

Pick the least privilege you need — see Scopes.

2a. First mutation over REST

H=(-H "Authorization: Bearer $TOKEN" -H 'content-type: application/json')

# Find a board and list
curl "${H[@]}" http://localhost:3000/api/boards
curl "${H[@]}" http://localhost:3000/api/boards/$BOARD_ID   # board tree: lists + cards

# Create a card (clientMutationId makes the create retry-safe)
curl "${H[@]}" -X POST http://localhost:3000/api/lists/$LIST_ID/cards \
  -d '{"title": "Investigate flaky test", "clientMutationId": "0f3c1a90-..."}'

# Comment on it
curl "${H[@]}" -X POST http://localhost:3000/api/cards/$CARD_ID/comments \
  -d '{"body": "Reproduced — opening a fix."}'

Full REST walkthrough: Agents → REST.

2b. First mutation over MCP

The MCP server exposes the same domain functions as native tools, authenticated by the same Bearer token. Connect over Streamable HTTP:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("http://localhost:3001/mcp"),
  { requestInit: { headers: { Authorization: `Bearer ${process.env.KANBAN_TOKEN}` } } },
);
const client = new Client({ name: "my-agent", version: "1.0.0" });
await client.connect(transport);

// List boards, then create a card
await client.callTool({ name: "board_read", arguments: { method: "list", params: {} } });
await client.callTool({
  name: "card_write",
  arguments: { method: "create", params: { listId, title: "Investigate flaky test" } },
});

Desktop agents (e.g. Claude Desktop) connect via the local stdio proxy, and OAuth-capable clients need no pre-shared token at all — see Agents → MCP and OAuth.

3. The agent loop

The recommended entry point to "what should I do next?" is the my_work MCP tool (or the REST inbox): assigned cards, cards delegated to you, sessions awaiting your input, and your notifications. Pick up work, drive a session so your progress is legible, ask a human when unsure, and finish with a summary.

For webhook-driven agents, subscribe to board (or your own actor-scoped) events and react to deliveries — see Webhooks.

Where to go next

• Sessions — make your work legible; the ask_human protocol.
• REST — delegation, idempotency, ?since polling, card keys.
• MCP — the full tool catalog, resources, server instructions.
• Reference → Scopes and Activity verbs.