Native MCP server (kata mcp serve) — design choices to confirm before implementing

[hughdbrown]

Background

Expose kata's API as a Model Context Protocol server so agents in Claude Code, Cursor, Codex, etc. can call tools like kata.search, kata.create, kata.comment directly instead of shelling out. The agent-ergonomics goal already implies this, kata has stable JSON contracts at the internal/api boundary that are easy to wrap, and Beads has had this for a while — kata's smaller surface would actually be easier to expose cleanly.

I would like to implement this and file a PR, but several design choices compound, so I'd like to confirm them before writing the code.

Proposed surface

kata mcp serve [--workspace PATH] — a long-running subprocess that speaks MCP. The daemon is auto-started exactly like the CLI does via ensureDaemon, and the MCP handler is a thin wrapper that translates MCP tool calls into existing HTTP API requests.

Choices that need a call

1. Transport

• (a) stdio only (proposed) — what Claude Code / Cursor / Codex launch via subprocess. Simplest, no auth needed, matches kata's local-only model.
• (b) stdio + HTTP/SSE — broader compatibility, but HTTP raises the "should the MCP server be reachable on the LAN" question, which the README explicitly defers (The local daemon should not be exposed directly to a LAN or public network).

2. Go MCP SDK

• (a) github.com/mark3labs/mcp-go (proposed) — mature, Go-native, no codegen, idiomatic.
• (b) github.com/modelcontextprotocol/go-sdk — the official SDK, but newer and lower-traffic. Worth picking for long-term alignment if you'd rather follow upstream.

3. Tool surface

Proposed (read + safe-write only):

kata.search, kata.list, kata.show, kata.ready, kata.digest,
kata.create, kata.comment, kata.edit, kata.close, kata.reopen,
kata.label_add, kata.label_remove, kata.assign, kata.unassign,
kata.link, kata.unlink.

Deliberately excluded: delete, purge, restore. The README treats destructive ops as explicit confirm-required CLI actions, and an agent invoking them through MCP would not have the --confirm \"DELETE #N\" gate that the human-facing path does. Easy to add later behind a flag if the policy is "trust the agent."

4. Workspace / project scope

• (a) Bind once on server startup (proposed): kata mcp serve --workspace PATH resolves the project at boot and every tool call operates inside it. Multi-project means launching multiple MCP servers (one per agent context, which is how Claude Code wires servers anyway).
• (b) Per-call workspace argument: every tool takes a workspace field, server is project-agnostic. More flexible but harder to make safe (an agent can accidentally write to the wrong project).

5. Actor identity

Proposed: --as NAME flag at server startup binds an actor for the session, falling back to the same precedence the CLI uses (--as > KATA_AUTHOR > git > anonymous). Tool calls do not accept an actor field — that would let one agent forge another's identity. The agent that launched kata mcp serve is the actor for the lifetime of the process.

What I'd like from you

A 👍/👎 on each numbered item, or just "go with the proposals" / "change X to Y." Once the design is settled I'll open the PR against main from a feat/mcp-server branch.

[mariusvniekerk]

Looks like generally good plan. One question, do you think we just have the daemon expose a localhost one by default or would you say stdio only in order to make the repo detection simpler

[wesm]

With the overall decline of MCP I'm wondering whether it's better or worse than simply teaching the agent to use the CLI (maybe lower context load compared with the MCP tool definitions)?

[hughdbrown]

With the overall decline of MCP ...

Totally understandable. One reason I did not code it first.

[obra]

It all depends on the design of the mcp tools. And there are still places where having the tool preloaded will get you better output. (It also makes it easier for folks who don't run in yolo mode to allow kata actions without allowing shell actions)