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

> Learn how the `kimi mcp` command integrates and manages external MCP servers by persisting definitions, negotiating tokens, and dynamically loading tools via an async client.

- Repository: [Moonshot AI/kimi-cli](https://github.com/MoonshotAI/kimi-cli)
- Tags: how-to-guide
- Published: 2026-07-21

---

**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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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:

```json
{
  "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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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

```bash

# 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`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/cli/mcp.py).
- **OAuth management**: Tokens are cached in `~/.kimi/mcp-oauth/` by [`src/kimi_cli/mcp_oauth.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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.