How the `kimi mcp` Command Integrates and Manages External MCP Servers

The kimi mcp command persists server definitions to ~/.kimi/mcp.json, negotiates OAuth tokens when required, and dynamically loads remote tools into Kimi’s agent runtime via an asynchronous fastmcp.Client connection.

The kimi mcp command in the MoonshotAI/kimi-cli repository is the central interface for integrating external Model Context Protocol (MCP) servers into the Kimi CLI. It handles everything from configuration persistence to runtime tool registration, allowing the agent to discover and invoke remote capabilities as first-class tools.

Persisting MCP Server Definitions to ~/.kimi/mcp.json

When you run kimi mcp add, the CLI writes a JSON object to the global share directory at ~/.kimi/mcp.json.

Configuration Schema and Validation

In src/kimi_cli/cli/mcp.py, the helper functions _load_mcp_config, _save_mcp_config, and _get_mcp_server read and validate this file against the fastmcp.mcp_config.MCPConfig schema. The stored shape supports both HTTP and stdio transports:

{
  "mcpServers": {
    "my-http": {
      "url": "https://example.com/mcp",
      "transport": "http",
      "headers": {},
      "auth": "oauth"
    },
    "my-stdio": {
      "command": "npx",
      "args": ["chrome-devtools-mcp@latest"],
      "env": {}
    }
  }
}

Adding and Managing Server Entries

The sub-commands add, remove, list, auth, reset-auth, and test are all implemented in src/kimi_cli/cli/mcp.py. Each operation parses CLI options, validates them against the MCP config schema, and mutates the global JSON file accordingly.

Authenticating Remote MCP Servers with OAuth

If a server is declared with --auth oauth, the auth sub-command triggers an OAuth flow to establish trust with remote endpoints.

The OAuth Flow and Token Storage

The helper module src/kimi_cli/mcp_oauth.py manages the full token lifecycle. It caches tokens under ~/.kimi/mcp-oauth/ and exposes the helpers has_mcp_oauth_tokens, create_mcp_oauth, and prepare_mcp_server_config. During authorization, the CLI opens a browser, exchanges the authorization code for a token, stores it on disk, and patches the server config with a fastmcp.client.auth.oauth.OAuth object.

Authorization Status Checks

The list command surfaces a warning when a cached token is missing, prompting the user to run kimi mcp auth <name>. This early validation prevents runtime connection failures by surfacing authorization gaps before the agent attempts to invoke tools.

Loading Remote Tools into Kimi’s Agent Runtime

Once servers are configured and authorized, Kimi must convert them into callable tools inside the agent loop.

Asynchronous Connection via load_mcp_tools

During startup, KimiToolset.load_mcp_tools in src/kimi_cli/soul/toolset.py reads the global MCP config and asynchronously builds a fastmcp.Client for each entry. For OAuth-protected servers, it checks the token store first; if tokens are absent, it marks the server as unauthorized rather than crashing the loop.

Wrapping Tools with MCPTool

Once a connection succeeds, the toolset iterates over client.list_tools() and wraps each remote tool in an MCPTool object. These wrappers are then added directly to the agent’s tool registry, making remote functions indistinguishable from native capabilities during planning and execution.

Runtime Execution and UI Feedback

Routing Calls Through MCPTool

When a user request references a remote tool, the call is routed through the MCPTool wrapper inside src/kimi_cli/soul/kimisoul.py via the toolset. The wrapper forwards the request to the remote MCP server over the chosen transport, whether stdio or http.

Live Connection Status in the Shell

The UI module src/kimi_cli/ui/shell/mcp_status.py provides real-time toast messages such as “connecting to mcp servers…”, “mcp servers connected”, or “mcp authorization needed”. This gives users immediate visibility into background connection health without blocking the interactive shell.

Practical kimi mcp Command Examples

# Add an HTTP-based MCP server with OAuth

kimi mcp add \
  --transport http \
  --auth oauth \
  --header "Authorization: Bearer $TOKEN" \
  linear https://mcp.linear.app/mcp

# Add a stdio-based MCP server (local command)

kimi mcp add \
  --transport stdio \
  chrome-devtools -- npx chrome-devtools-mcp@latest

# List all configured servers and auth status

kimi mcp list

# Authorize an OAuth-enabled server

kimi mcp auth linear

# Reset cached OAuth tokens after revoking access

kimi mcp reset-auth linear

# Test connectivity and list remote tools

kimi mcp test linear

Summary

• Configuration persistence: Server definitions are stored in ~/.kimi/mcp.json and validated via fastmcp.mcp_config.MCPConfig through src/kimi_cli/cli/mcp.py.
• OAuth management: Tokens are cached in ~/.kimi/mcp-oauth/ by src/kimi_cli/mcp_oauth.py and injected into clients at runtime.
• Runtime loading: KimiToolset.load_mcp_tools in src/kimi_cli/soul/toolset.py creates fastmcp.Client instances and registers remote tools as MCPTool objects.
• User feedback: Connection status is surfaced in the interactive shell by src/kimi_cli/ui/shell/mcp_status.py.

Frequently Asked Questions

Where does kimi mcp store server configurations?

The CLI writes server definitions to ~/.kimi/mcp.json in the global share directory. Functions such as _load_mcp_config and _save_mcp_config in src/kimi_cli/cli/mcp.py handle read and write operations, and they validate the file against the fastmcp.mcp_config.MCPConfig schema before persisting changes.

How does Kimi CLI handle OAuth authentication for MCP servers?

When a server is added with --auth oauth, the kimi mcp auth <name> command triggers a browser-based OAuth flow implemented in src/kimi_cli/mcp_oauth.py. The resulting tokens are cached under ~/.kimi/mcp-oauth/ and later injected into the client connection via helpers like create_mcp_oauth when load_mcp_tools initializes the session.

What happens if an MCP server is missing authorization?

If KimiToolset.load_mcp_tools cannot locate valid OAuth tokens for a protected server, it marks the server as unauthorized instead of failing silently. The UI module src/kimi_cli/ui/shell/mcp_status.py then displays a toast message prompting the user to run kimi mcp auth <name>.

Can I use both HTTP and stdio transports with kimi mcp?

Yes. The configuration schema supports both transports natively. HTTP servers declare a url field, while stdio servers specify a command and args array. The fastmcp.Client abstracts the underlying protocol, and Kimi routes tool calls through the appropriate transport at runtime.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}