MCP servers

ka is an MCP client. Every server you configure contributes its tools to ka’s Hands registry as <server>.<tool> at exec-tier clearance: the permission gate, rules, snapshots, and decomposition treat them exactly like any external execution. There is no separate trust path.

Configuration

# stdio server (spawned process)
[[mcp]]
name = "filesystem"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/srv/data"]
# env = { SOME_TOKEN = "…" }

# streamable HTTP server (legacy SSE is detected as a fallback)
[[mcp]]
name = "docs"
url = "https://mcp.example.com/mcp"
# headers = { Authorization = "Bearer …" }

Probing and using

ka mcp        # probe every configured server, list its tools

In the TUI, /mcp shows server status and /prompt runs MCP prompts. Handshake, tools/list, and tools/call are the only RPCs used; server noise is ignored, and a failing server degrades to a per-server note, never a crash.

Tool lists are cached: after a server’s first successful handshake, its tools are remembered under $XDG_STATE_HOME/ka/mcp-tools.json, keyed by a hash of the server’s config. The next startup registers them from cache instantly, so a slow or dead server never blocks startup and the tool list stays byte-stable across runs (which keeps provider prompt caches stable too). A background verify re-checks the live server, swaps the list with a transcript note if it changed, then chains into the supervision watchdog, so two connects are never in flight. Reconnects and manual refreshes update the cache as well.

Notes

• Both transports are implemented in-crate with no new dependencies.
• Because MCP tools are exec-tier, they ask under guarded mode like bash would; allowlist them with a [[rules]] entry or [permissions] allow if you trust one.
• ka doctor --net includes MCP reachability probes.