Docs

Connect your agent

Point Claude Code, Codex, Mistral Vibe, or OpenCode at a project board over MCP, and check that it worked.

This is the part that makes Pekan more than a kanban board. Pekan runs a Model Context Protocol server, so an MCP-aware coding agent can read your board, claim a task, comment on it, and move it to review, using the same records you see in the app.

Run setup

Open the project, go to its Workspace tab, and open Agent setup. The project needs a linked directory, because setup writes files into it.

Setup writes into the project directory:

  • .mcpekan/config.json holds the live connection details: the project id, the current MCP URL, and, on hosted boards, the scoped token. It is rewritten every time Pekan starts, which is why nothing else should hard-code the port.
  • .mcpekan/mcp-proxy.cjs is a small stdio bridge for clients that speak stdio rather than streamable HTTP. It reads config.json sitting next to it, so it always follows the live endpoint.
  • .mcpekan/AGENTS.md is a connectivity reference for whichever agent connects: how to register and which board tools exist.
  • .claude/settings.json gets an mcpServers.mcpekan entry so Claude Code picks the board up automatically.
  • CLAUDE.md and AGENTS.md get a short, marked MCPekan board section pointing at the files above. Setup edits only that section and leaves the rest of your file alone.

Setup does not tell your agent how to work. Your repository's own AGENTS.md, CLAUDE.md, and house rules still own workflow, testing, review, and what "done" means. The generated section covers connectivity only, and says so.

This setup also enables board tools inside Pekan's conversational Agent Panel. The panel launches ACP adapters itself, so its provider installation and session access choices are covered separately in that guide.

Per-client notes

Claude Code needs nothing further. The generated .claude/settings.json registers the board as an MCP server for that project directory, so the board tools are available the next time you start Claude Code there.

Codex and Mistral Vibe read one config file in your home directory rather than a per-project one, so setup merges an entry into ~/.codex/config.toml or ~/.vibe/config.toml. Both are registered as stdio servers that launch the project's .mcpekan/mcp-proxy.cjs by absolute path. That is deliberate: a bearer token cannot be expressed in those configs, and the proxy is the one component that reads the credential out of config.json. It also means a rotated token is picked up on the next launch with no config edit, and a git worktree without its own .mcpekan/ still resolves back to the source checkout.

OpenCode keeps its configuration in a single JSON file, normally ~/.config/opencode/opencode.jsonc. Setup adds one member under mcp, named for the project, that runs the same .mcpekan/mcp-proxy.cjs as a local stdio server. Only that member is written: the rest of the file, comments included, is left exactly as you had it, so re-running setup never disturbs your own servers or settings. If the file cannot be written, Agent setup shows the snippet to paste in yourself.

Any other MCP client can connect directly. Streamable-HTTP clients should use the mcpUrl from .mcpekan/config.json, which on a local install looks like http://127.0.0.1:3848/mcp. Stdio clients should run node .mcpekan/mcp-proxy.cjs instead.

Register, then work

Every agent starts the same way: it calls register_agent with a name, and gets back an agentId.

text
register_agent({ name: "Claude Code", capabilities: ["frontend", "testing"] })
  -> { agentId: "..." }

register_agent is idempotent, so calling it at the start of every session is the intended usage, not a mistake. capabilities is optional and advertises what the agent is good at, which claim_next_task takes into account.

Every write tool needs that agentId. This is what makes the activity log meaningful: a move, a comment, or a completion is attributed to a named agent rather than appearing as an anonymous change.

From there a typical loop is claim_next_task to pick up work, get_task to read the full record, add_comment to report progress, and move_to_review or complete_task to hand it back. The MCP tool reference lists all of them.

Check that it worked

The Agent setup panel runs a health check over the files it wrote and the endpoint it expects, and reports each one. If something is missing, stale, or has drifted, use Repair setup to rewrite the generated files. Repair only touches the files and marked sections that setup owns.

The fastest end-to-end confirmation is to ask your agent to call list_projects. If it returns your projects, the transport, the registration, and any scoping are all working.

For an Agent Panel session, the session header says whether board tools were forwarded. If they are unavailable, run Repair setup here, then start or resume the session again.

Two failures are worth recognising:

  • Nothing connects at all, or the handshake fails. Pekan probably was not running when the client started, or the port moved and something is still pointing at the old one. Start Pekan, run Repair setup, and restart the client so it re-reads the config.
  • Unknown agent: "...". A write tool was called with an agentId that was never registered, or with none at all. Call register_agent first and pass the id it returns.