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

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, 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. This Zod schema validates transport types and server-specific parameters:

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:

{
  "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 in your working directory. This overrides global definitions and executes with the project as the working directory:

{
  "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:

{
  "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. The system prefixes each MCP tool with mcp__<serverId>__<toolName>, allowing direct invocation via the REST API or SDK.

Using the TypeScript SDK

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:

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, 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 provides additional guidance for editing configuration files, and 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), and project-local (.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 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
• MCP tools are invoked using the mcp__<serverId>__<toolName> convention as implemented in 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 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, and the project-local directory at .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, 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 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 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. Only enable MCP for repositories you trust, as the system does not sandbox these executions.

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