How to Configure MCP Servers Conversationally in Kimi Code CLI

Run kimi mcp configure to interactively add Model Context Protocol (MCP) servers through a conversational prompt sequence that collects server details, handles OAuth or API-key authentication, and atomically writes the configuration to $KIMI_CODE_HOME/mcp.json without manual JSON editing.

Kimi Code integrates with external MCP (Model Context Protocol) servers to expose external tools and services to the AI model. The CLI eliminates manual configuration by providing a conversational interface that guides you through server registration. This workflow is implemented in the MoonshotAI/kimi-code repository and persists settings directly to your local environment.

Where MCP Configuration is Stored

User-wide MCP entries persist in the Kimi Code home directory. The CLI reads from $KIMI_CODE_HOME/mcp.json (defaulting to ~/.kimi-code/mcp.json) during initialization.

In packages/node-sdk/src/kimi-harness.ts, the configuration loader specifically targets this file for user-global entries:

/** User-global MCP entries from `<KIMI_CODE_HOME>/mcp.json` only. */
// Line 281: https://github.com/MoonshotAI/kimi-code/blob/main/packages/node-sdk/src/kimi-harness.ts#L281

The schema for these entries is defined in packages/klient/src/contract/mcp.ts, which validates the structure before persistence at line 2.

Starting the Conversational Configuration Workflow

All MCP management commands live under the kimi mcp namespace. The interactive logic resides in packages/node-sdk/src/cli/mcp.ts.

When you invoke the configure command without arguments, the CLI initiates a conversational prompt sequence:

$ kimi mcp configure

This triggers a series of questions—one per line—mirroring a natural conversation to collect server metadata.

Step-by-Step Interactive Prompts

The conversational workflow collects four key pieces of information:

1. Server name – A short identifier (e.g., xcode-mcp) used for tool namespacing
2. Base URL – The HTTP endpoint (e.g., https://xcode-mcp.example.com)
3. Authentication method – Choose between OAuth (browser-based) or API-key (token paste)
4. Optional description – Free-form text displayed in kimi mcp list output

After the final prompt, the CLI atomically writes the entry to mcp.json.

Handling Authentication Flows

The CLI supports two authentication mechanisms during configuration.

OAuth Flow: If you select OAuth, the CLI prints a browser URL and waits for the verification code. The implementation in packages/node-sdk/src/kimi-harness.ts handles the authorization handshake:

// Line 307: https://github.com/MoonshotAI/kimi-code/blob/main/packages/node-sdk/src/kimi-harness.ts#L307
throw new KimiError(ErrorCodes.REQUEST_INVALID, 'MCP OAuth authorization was cancelled');

After authorizing in your browser, paste the returned code into the terminal to complete the registration.

API-Key Flow: For server-to-server authentication, select the API-key option and paste the token directly into the prompt. The CLI securely stores this credential in the configuration file.

How MCP Servers Become Available to the Model

Once configured, the Kimi Code engine discovers available tools by reading the persisted entries. The Tool Manager (packages/agent-core/src/mcp/tool-manager-mcp.test.ts) connects to each server and registers tools under a qualified naming convention.

According to packages/kap-server/src/routes/tools.ts, MCP tools use a specific prefix and separator:

/** v2 MCP tool-name prefix / separator (see `mcp/tool-naming.ts`). */
const MCP_NAME_PREFIX = 'mcp__';
const MCP_NAME_SEPARATOR = '__';
// Lines 76-78: https://github.com/MoonshotAI/kimi-code/blob/main/packages/kap-server/src/routes/tools.ts#L76-L78

This results in tool names like mcp__xcode__search, making them available to the model as native functions. Helper functions in packages/agent-core/src/mcp/tool-naming.ts parse these qualified names during execution.

Managing Existing MCP Servers

The CLI provides full lifecycle management beyond initial configuration.

Listing configured servers:

$ kimi mcp list

This command reads $KIMI_CODE_HOME/mcp.json and displays entries in a formatted table showing name, URL, authentication type, and description.

Removing a server:

$ kimi mcp remove xcode-mcp

The CLI prompts for confirmation, then deletes the entry from the configuration file. Subsequent sessions will no longer attempt to connect to the removed server.

Summary

• Storage location: MCP configurations live in $KIMI_CODE_HOME/mcp.json, loaded by packages/node-sdk/src/kimi-harness.ts
• Interactive setup: Run kimi mcp configure to answer conversational prompts for server name, URL, authentication, and description
• Authentication: Choose between OAuth (browser flow) or API-key (token paste), handled in kimi-harness.ts
• Tool availability: Servers expose tools via the mcp__ prefix convention defined in packages/kap-server/src/routes/tools.ts
• Lifecycle commands: Use kimi mcp list to inspect and kimi mcp remove to delete servers

Frequently Asked Questions

What file format does Kimi Code use for MCP configuration?

Kimi Code stores MCP configurations as JSON in $KIMI_CODE_HOME/mcp.json. The schema is defined in packages/klient/src/contract/mcp.ts, ensuring each entry contains valid server metadata, authentication credentials, and optional descriptions.

Can I configure MCP servers without using the interactive prompts?

While the conversational kimi mcp configure command is the recommended approach, you can manually edit $KIMI_CODE_HOME/mcp.json following the schema in packages/klient/src/contract/mcp.ts. However, manual edits bypass validation checks that the CLI performs during the interactive workflow.

How does Kimi Code handle OAuth authentication for MCP servers?

When you select OAuth during configuration, the CLI opens your browser to the authorization endpoint. After you grant access, you paste the verification code back into the terminal. The implementation in packages/node-sdk/src/kimi-harness.ts validates this code and stores the resulting credentials securely in the configuration file.

Why do MCP tool names start with "mcp__" in Kimi Code?

The mcp__ prefix prevents naming collisions between native tools and external MCP server tools. As implemented in packages/kap-server/src/routes/tools.ts and parsed by packages/agent-core/src/mcp/tool-naming.ts, the double-underscore separator creates qualified names like mcp__servername__toolname, allowing the engine to route calls correctly.

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