# How to Configure MCP Servers in Kimi Code: A Complete Guide

> Learn to configure MCP servers in Kimi Code by merging JSON files and using the mcp naming convention. This complete guide provides clear steps for seamless integration.

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

---

**Kimi Code discovers Model Context Protocol (MCP) servers by merging three JSON configuration files—user-global, project-root, and project-local—applying a cascading override strategy where later definitions replace earlier ones, and exposes registered tools via the `mcp__<serverId>__<toolName>` naming convention.**

Kimi Code, developed by MoonshotAI, extends its AI capabilities through the Model Context Protocol, enabling seamless integration of external tools and services. To configure MCP servers in Kimi Code, developers create JSON-based configuration files that specify transport protocols, executable commands, and runtime parameters. The system automatically discovers these configurations from multiple locations according to a defined precedence hierarchy, merging them into a unified runtime environment.

## MCP Configuration File Locations and Precedence

Kimi Code loads MCP server definitions from three distinct locations, merging them in a specific order where subsequent files override earlier entries. This cascading strategy allows you to define global defaults while enabling project-specific customizations.

The configuration loader, implemented in [`packages/agent-core/src/mcp/config-loader.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/src/mcp/config-loader.ts), searches for these files in the following order:

1. **User-global**: `<KIMI_CODE_HOME>/mcp.json` (typically `~/.kimi-code/mcp.json`)
2. **Project-root**: `<project-root>/.mcp.json`
3. **Project-local**: `<cwd>/.kimi-code/mcp.json`

The `loadMcpServers` function orchestrates this process by calling `resolveMcpJsonPaths` to locate the three files, then `readMcpJson` to parse each file while gracefully handling missing or invalid JSON. Finally, `normalizeMcpServers` processes `stdio` transports to inject proper working directories. The merging logic returns a combined object `{ …user, …projectRoot, …project }` where collisions are resolved in favor of the last definition encountered.

## Configuration Schema and Validation

Each MCP server entry must conform to the `McpServerConfigSchema` defined in [`packages/agent-core/src/config/schema.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/src/config/schema.ts). This Zod schema validates transport types and server-specific parameters:

```typescript
export const McpServerConfigSchema = z.object({
  transport: z.enum(['stdio', 'http', 'stream']).default('stdio'),
  command: z.string().optional(),
  cwd: z.string().optional(),
  url: z.string().url().optional(),
  // …other transport‑specific fields
});

```

The **transport** field determines how Kimi Code communicates with the server:

- **`stdio`**: Spawns a local process and communicates via standard input/output
- **`http`**: Connects to a remote JSON-RPC endpoint
- **`stream`**: Uses streaming communication protocols

## Step-by-Step Configuration Examples

### User-Global stdio Server

Create a global configuration at `~/.kimi-code/mcp.json` to register a Python-based tool available across all projects:

```json
{
  "mcpServers": {
    "hello-py": {
      "transport": "stdio",
      "command": "python3 -u hello.py",
      "cwd": "~/.kimi-code/mcp"
    }
  }
}

```

### Project-Local stdio Server

For project-specific tools, create [`.kimi-code/mcp.json`](https://github.com/MoonshotAI/kimi-code/blob/main/.kimi-code/mcp.json) in your working directory. This overrides global definitions and executes with the project as the working directory:

```json
{
  "mcpServers": {
    "my-tool": {
      "transport": "stdio",
      "command": "./my-tool.sh",
      "cwd": "."
    }
  }
}

```

### HTTP-Based Remote Server

To connect to a remote MCP service exposing a JSON-RPC endpoint:

```json
{
  "mcpServers": {
    "remote-search": {
      "transport": "http",
      "url": "https://api.example.com/mcp"
    }
  }
}

```

## Invoking MCP Tools in Kimi Code

Once configured, MCP tools become available through Kimi Code's tool system using a specific naming 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). The system prefixes each MCP tool with `mcp__<serverId>__<toolName>`, allowing direct invocation via the REST API or SDK.

### Using the TypeScript SDK

```typescript
import { Kimi } from '@moonshot-ai/kimi-code-sdk';

async function demo() {
  const kimi = await Kimi.start();
  const result = await kimi.runTool(
    'mcp__hello-py__greet',
    { name: 'World' }
  );
  console.log(result);
}
demo();

```

### Using the REST API

Query available MCP tools and invoke them via the local server endpoint:

```bash
curl -s http://localhost:58627/api/v1/tools \
  | jq '.filter(.name|startsWith("mcp__"))'

```

## Safety Considerations and Runtime Behavior

**Security Warning**: Project-local `stdio` entries execute when a session opens in that directory. As noted in the source code comments within [`packages/agent-core/src/mcp/config-loader.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/src/mcp/config-loader.ts), enable MCP only for trusted repositories to prevent arbitrary code execution.

The MCP manager supports dynamic updates, allowing you to add, remove, or restart servers at runtime without restarting Kimi Code. The UI reflects current states through `tools` and `status` events, while new models can request MCP capabilities via the built-in `select_tools` functionality. The user-facing documentation in [`packages/agent-core/src/skill/builtin/mcp-config.md`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/src/skill/builtin/mcp-config.md) provides additional guidance for editing configuration files, and [`packages/node-sdk/src/kimi-harness.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/node-sdk/src/kimi-harness.ts) exposes user-global MCP entries to the SDK.

## Summary

- Kimi Code loads MCP configurations from three locations: user-global (`~/.kimi-code/mcp.json`), project-root ([`.mcp.json`](https://github.com/MoonshotAI/kimi-code/blob/main/.mcp.json)), and project-local ([`.kimi-code/mcp.json`](https://github.com/MoonshotAI/kimi-code/blob/main/.kimi-code/mcp.json)), merging them in that order with later entries overriding earlier ones
- The `loadMcpServers` function in [`packages/agent-core/src/mcp/config-loader.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/src/mcp/config-loader.ts) handles path resolution, JSON parsing via `readMcpJson`, and normalization of working directories via `normalizeMcpServers`
- Valid transports include `stdio`, `http`, and `stream`, validated against `McpServerConfigSchema` in [`packages/agent-core/src/config/schema.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/src/config/schema.ts)
- MCP tools are invoked using the `mcp__<serverId>__<toolName>` convention 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)
- Only enable `stdio` transports for trusted repositories, as project-local configurations execute code automatically when opening sessions in those directories

## Frequently Asked Questions

### Where does Kimi Code look for MCP configuration files?

Kimi Code searches for [`mcp.json`](https://github.com/MoonshotAI/kimi-code/blob/main/mcp.json) files in three locations: the user-global directory at `<KIMI_CODE_HOME>/mcp.json` (usually `~/.kimi-code/mcp.json`), the project-root at [`.mcp.json`](https://github.com/MoonshotAI/kimi-code/blob/main/.mcp.json), and the project-local directory at [`.kimi-code/mcp.json`](https://github.com/MoonshotAI/kimi-code/blob/main/.kimi-code/mcp.json). The system loads these in sequence and merges them, allowing project-specific configurations to override global defaults.

### How are MCP tools named when invoked in Kimi Code?

According to the implementation in [`packages/kap-server/src/routes/tools.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/kap-server/src/routes/tools.ts), MCP tools follow the naming pattern `mcp__<serverId>__<toolName>`. For example, a tool named `greet` from a server configured with the ID `hello-py` would be invoked as `mcp__hello-py__greet` through the Kimi Code SDK or API.

### Can I use HTTP endpoints instead of local executables for MCP servers?

Yes, the `McpServerConfigSchema` in [`packages/agent-core/src/config/schema.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/src/config/schema.ts) supports `http` transport, allowing you to connect to remote JSON-RPC endpoints by specifying a `url` field instead of a `command`. This is useful for integrating cloud-based services or microservices architectures without requiring local installations.

### Is it safe to clone repositories containing [`.mcp.json`](https://github.com/MoonshotAI/kimi-code/blob/main/.mcp.json) files?

Exercise caution when opening untrusted repositories that contain MCP configurations. The configuration loader executes `stdio` transport commands automatically when a session starts in a directory containing a project-local [`mcp.json`](https://github.com/MoonshotAI/kimi-code/blob/main/mcp.json). Only enable MCP for repositories you trust, as the system does not sandbox these executions.