MCP servers.

An MCP server adds tools to Kaitoi Code. This guide covers Code acting as the client in CLI 0.9.0; connecting another AI client to Kaitoi's own MCP server is a different setup.

#Add and inspect a server

The terminal command is top-level kaitoi mcp. For a remote server, replace the example URL with the server you actually intend to use:

kaitoi mcp list --workspace .
kaitoi mcp add docs --url https://example.com/mcp
kaitoi mcp approve docs

Inspect the launch and access before approving it. If the remote server supports and requires OAuth, use kaitoi mcp login docs; not every server has a login flow. For a local stdio server, add accepts a command after --, or pinned --npm PACKAGE@EXACT_VERSION / --pypi PACKAGE==EXACT_VERSION installation specifications. Use actual package versions, not those placeholder words.

Inside Code, /mcp shows status. /mcp tools docs inspects the tools; /mcp reload restarts the configured servers. Terminal and slash subcommands are not identical: use kaitoi mcp --help and the /mcp help for their own surface.

#Understand which configuration wins

User mcp.json lives beside Code's user config.json. Trusted projects can provide .mcp.json and .kaitoi/mcp.json; the latter wins between those two. A user server overrides a project server of the same name. Project entries require a trusted workspace.

For a server name, the user mcp.json entry wins over project .kaitoi/mcp.json, which wins over project .mcp.json. The selected effective server configuration must have valid launch approval. A tool call then follows its own allow, ask, or deny grant. Changing the effective server invalidates approval rather than silently carrying the old authority to the new launch.

Same-name examples A, B and C compete; the user-level entry wins. Changing that effective entry to D breaks the previous launch binding. Even an allow tool grant cannot resolve a missing launch approval.

The built-in server is named kaitoi. /mcp disable kaitoi and /mcp enable kaitoi control its switch. A fully defined user server with that name shadows the built-in, so use a different name for unrelated integrations.

#Approve tools deliberately

Launching a server and permitting a tool are different decisions. Unknown tool calls ask. Save an allow, ask, or deny decision only for the intended server and tool; a saved allow can also permit headless calls.

kaitoi mcp grant docs resources/read --allow
kaitoi mcp grants docs

This example permits resource reads for the chosen server. Tool names come from its actual catalog. Add --read-only only when the tool is genuinely read-only and should be offered in Plan/Crew. That classification is your assertion about the external tool, not proof of its implementation. Wildcard grants cover more than one tool and can include resource reads.

Effective launch changes invalidate approval and the grants bound to it. Use kaitoi mcp revoke docs to revoke launch approval. Review the current listing before changing a grant rather than assuming an old server definition is active.

#Configure transport and credentials

Remote HTTP/streamable-HTTP and SSE endpoints require HTTPS except for loopback addresses. A remote server's machine is not inside Code's local stdio sandbox. Local stdio launches default to sandboxing, network off, and no extra read/write folder grants; explicit network and folder options expand that launch scope.

Configuration supports ${env:NAME}, ${secret:NAME}, and ${workspace}. Use kaitoi mcp secret set NAME for an interactive secret prompt and keep only the placeholder in configuration. Literal credentials in URLs or secret-looking header/environment values are rejected. Single-quote placeholders in shell examples so your shell does not expand them first.

If a tool is missing, check configuration precedence, workspace trust, launch approval, login, and the tool grant in that order. Headless sessions refuse requests needing an interactive decision; they do not turn a missing approval into permission.