# How to Configure MCP Servers Conversationally in Kimi Code CLI

> Easily configure MCP servers conversationally with Kimi Code CLI. Run kimi mcp configure to add servers, handle authentication, and automatically update mcp.json without manual editing.

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

---

**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`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/node-sdk/src/kimi-harness.ts), the configuration loader specifically targets this file for user-global entries:

```ts
/** 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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/node-sdk/src/cli/mcp.ts).

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

```bash
$ 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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/node-sdk/src/kimi-harness.ts) handles the authorization handshake:

```ts
// 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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/kap-server/src/routes/tools.ts), MCP tools use a specific prefix and separator:

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

```bash
$ 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:**

```bash
$ 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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/kimi-harness.ts)
- **Tool availability**: Servers expose tools via the `mcp__` prefix convention defined in [`packages/kap-server/src/routes/tools.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/kap-server/src/routes/tools.ts) and parsed by [`packages/agent-core/src/mcp/tool-naming.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/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.