Model Context Protocol

Model Context Protocol (MCP) is an open protocol that lets models safely call tools exposed by external processes or services: reading GitHub issues, querying databases, or operating the local file system. Kimi Code CLI acts as an MCP client to connect these external tools and exposes them to the Agent alongside built-in tools (Read, Bash, Grep, etc.) with no behavioral difference.

MCP tool results can include text (content) and structured data (structuredContent). Kimi Code CLI makes both available to the agent and omits the structured copy only when it can confirm that a text block already contains the same complete JSON value. Text summaries and media do not replace structured records.

Kimi Code CLI preserves embedded MCP attachments that cannot be delivered directly because of format or size limits. Embedded images, audio, and video are saved even when they can be delivered unchanged, because provider conversion or later history reduction may omit them. Session-attachment readers remain available without workspace filesystem access when the model supports the corresponding content. Originals are retained in the session's media storage instead of an evictable image cache. Saved originals, including images preserved during compression, have absolute paths and stable kimi-file:// references. Pass a reference as the path to Read or ReadMediaFile; bytes are read from the current session's storage even when the workspace runtime cannot access it. Pagination keeps the reference, including after a fork. For binary formats that Read cannot open, its error includes a server-local path when available; an external converter must have access to that filesystem. Text attachments such as CSV, HTML, JSON, and plain SVG use readable extensions.

Attachment paths and compression details share the tool-output budget. Large lists are saved to a text file, with a short pointer that remains visible when accompanying text is shortened; the agent can pass the list’s kimi-file:// reference to Read and page through it. Canceling the tool stops subsequent attachment processing and signals active writes. If decoding or saving fails, the result explicitly reports that the original could not be preserved while retaining other usable output. Resource links are not automatically downloaded.

Connection Methods

Kimi Code CLI supports three MCP server connection methods:

• stdio: The CLI starts the local MCP server as a child process and communicates via standard input/output. Suitable for local command-line tools.
• HTTP: The CLI connects to an already-running HTTP endpoint. Suitable for remote services or processes that need to run persistently.
• SSE: The CLI connects to a legacy HTTP+SSE endpoint (Server-Sent Events, a streaming HTTP mechanism). Prefer HTTP for new MCP servers, but use transport: "sse" when a service still exposes only the older SSE transport.

Configuration

MCP server configuration is written in mcp.json, at two levels:

• User level: ~/.kimi-code/mcp.json (or $KIMI_CODE_HOME/mcp.json), shared across projects
• Project level: .kimi-code/mcp.json in the working directory, effective only for the current repository

Entries with the same name: the project-level entry takes precedence and overrides the user-level entry.

Run /mcp-config in the TUI to interactively add, edit, or delete servers without manually editing the JSON file. Run /mcp to view the connection status of all current servers.

Deleting a server from the configuration does not interrupt open sessions: the server stays listed in /mcp as removed, its tools remain visible there, and calls to them fail with a removal notice, while new sessions do not register the tools at all. Conversely, a server added mid-session by editing mcp.json or installing a plugin is not registered in already-open sessions; it only joins sessions created later.

When Kimi Code finds project-level MCP servers in an untrusted folder, it shows each server's transport and launch target in the workspace trust prompt. The prompt defaults to Trust this folder; review the listed command and arguments or remote URL before confirming. Trusting the folder enables the project-level MCP servers for that workspace.

Structure of mcp.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    },
    "linear": {
      "url": "https://mcp.linear.app/mcp"
    },
    "legacy-events": {
      "transport": "sse",
      "url": "https://mcp.example.com/sse"
    }
  }
}

Entries with a command field are stdio servers; entries with a url field and no transport are HTTP servers. For legacy SSE servers, set transport to "sse" explicitly.

Optional fields:

Field	Type	Applies to	Description
env	Record<string, string>	stdio	Environment variables injected into the child process
cwd	string	stdio	Working directory for the child process
headers	Record<string, string>	HTTP, SSE	Static request headers appended to every request
bearerTokenEnvVar	string	HTTP, SSE	Name of an environment variable that contains a bearer token
enabled	boolean	All	Set to false to disable this server
deferred	boolean	All	Experimental: set to true to let the model load this server's tools on demand. Defaults to false (always exposed inline). Prerequisites and behavior: Loading tools on demand
startupTimeoutMs	number	All	Connection timeout from 1 to 2147483647 milliseconds; default 30000
toolTimeoutMs	number	All	Timeout from 1 to 2147483647 milliseconds for a single tool call
enabledTools	string[]	All	Tool allowlist
disabledTools	string[]	All	Tool blocklist

You do not have to set the connection timeout or the single tool-call timeout per server: [mcp] startup_timeout_ms / [mcp] tool_timeout_ms in config.toml or the KIMI_MCP_STARTUP_TIMEOUT_MS / KIMI_MCP_TOOL_TIMEOUT_MS environment variables change the global defaults. Precedence is: per-server field > environment variable > config.toml > built-in default. See Configuration files.

HTTP and SSE servers support providing static credentials via headers or bearerTokenEnvVar. When OAuth is needed, run /mcp-config login <server-name> to complete browser-based authorization.

Plugins can also declare MCP servers in their manifest. Servers declared by a plugin are enabled by default and can be disabled or re-enabled in /plugins: disabling or removing one makes calls from open sessions fail with a removal notice, and adding or enabling a server connects it in open sessions right away. See Plugins for details.

Note

stdio entries in a project-level .kimi-code/mcp.json execute local commands when a session starts. Only enable these in repositories you trust.

Loading tools on demand

By default, every tool of a server goes straight into the model's top-level tool list; with many connected servers — or a single server that exposes many tools — those definitions occupy context for the whole session. Marking a server as deferred keeps its tools out of the top-level list: the model first sees a manifest of loadable tools, loads full definitions on demand through the built-in select_tools tool, and can call them in the same turn once loaded.

Loading tools on demand is experimental and takes effect only when both prerequisites are met:

• The tool-select experimental flag is on: set KIMI_CODE_EXPERIMENTAL_TOOL_SELECT=1, or write tool-select = true under [experimental] in config.toml; the master switch KIMI_CODE_EXPERIMENTAL_FLAG=1 enables it too.
• The current model declares the dynamically_loaded_tools capability: official models declare it automatically; for other models, add it to capabilities in config.toml — see Configuration files.

With both prerequisites met, set deferred: true on the server entry in mcp.json:

{
  "mcpServers": {
    "github": {
      "url": "https://mcp.example.com/mcp",
      "deferred": true
    }
  }
}

Servers without deferred are unaffected and always exposed inline; when a prerequisite is missing, the field is ignored with the same result. The authentication tool exposed by an OAuth server before authorization completes follows the same field.

Tool Naming and Permissions

MCP tools are named in the format mcp__<server>__<tool>, for example mcp__github__create_issue. Permission rules support * and ** wildcards, for example mcp__github__* matches all tools under that server. MCP tool parameters are not included in permission matching.

Calls that do not match any permission rule trigger an approval request. Selecting "Approve for this session" in the approval dialog automatically allows subsequent calls of the same kind within the current session.

You can also pre-configure permanent rules in [[permission.rules]] in config.toml:

[[permission.rules]]
decision = "allow"
pattern = "mcp__github__*"

[[permission.rules]]
decision = "deny"
pattern = "mcp__filesystem__write_file"

For the full permission rule syntax, see Configuration files.

Security

When connecting to external MCP servers, be aware of:

• Only connect to servers from trusted sources
• Verify that tool names and parameters look reasonable in approval requests
• Keep manual approval for high-risk tools (file writes, command execution, etc.); avoid using mcp__* wildcards to allow all tools at once

Note

In Ask When Needed mode, MCP tool calls are automatically approved. Only use this mode when you fully trust the MCP servers you have connected.

Next steps

• Plugins — Declare MCP servers in a plugin manifest to package and distribute them together
• Configuration files — Full field reference for permission rules