How to Configure MCP Servers Conversationally Using `/mcp-config` in Kimi Code

The /mcp-config command in Kimi Code lets you add, edit, authenticate, and list Model Context Protocol (MCP) servers through an interactive TUI dialog without manually editing JSON files.

Kimi Code (MoonshotAI/kimi-code) includes a built-in skill that transforms MCP server management from manual configuration file editing into a conversational interface. Instead of memorizing JSON schemas or file paths, you use natural language prompts within the terminal UI to define servers, handle OAuth flows, and manage credentials securely.

Understanding the /mcp-config Skill

The skill is registered in the builtin catalog as builtin://mcp-config and defined 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). You invoke it by typing /mcp-config or /skill:mcp-config in the TUI.

The skill operates in three distinct modes:

• Configuration editing – Adds, modifies, or removes server entries in the appropriate mcp.json file based on your specified scope.
• Authentication handling – Manages OAuth flows for servers in a needs-auth state by calling generated authentication tools.
• Configuration inspection – Merges and displays all active server definitions from the three possible configuration layers.

Configuration Scopes and Precedence

Kimi Code supports three hierarchical scopes for MCP server definitions. Later entries override earlier ones when keys collide.

Scope	File Path	Description
User-global	$KIMI_CODE_HOME/mcp.json (fallback: ~/.kimi-code/mcp.json)	Applies to every project on the machine.
Project-root	<project-root>/.mcp.json	Discovered by walking up to the nearest .git directory; shared across repo clones.
Project-local	<cwd>/.kimi-code/mcp.json	Overrides specific to your current working directory only.

When you run /mcp-config add, the skill prompts you to select which scope to target, then writes the JSON while preserving existing entries and the top-level "mcpServers" wrapper.

Managing MCP Servers Conversationally

Adding HTTP MCP Servers

To add an HTTP-based server interactively, type:

/mcp-config add my-http-server

The skill prompts for required fields from McpServerHttpConfigSchema:

Enter URL: https://api.example.com/mcp
Use static token? (y/N) y
Enter env var name for token: EXAMPLE_TOKEN

The resulting entry in ./.kimi-code/mcp.json:

{
  "mcpServers": {
    "my-http-server": {
      "url": "https://api.example.com/mcp",
      "bearerTokenEnvVar": "EXAMPLE_TOKEN"
    }
  }
}

Adding stdio MCP Servers

For local subprocess-based servers, specify the scope if you want global availability:

/mcp-config add my-stdio-server --scope global

The skill collects fields defined in McpServerStdioConfigSchema:

Enter command: ./run-mcp.sh
Enter args (optional): --mode server
Enter cwd (optional): /usr/local/mcp

This writes to $KIMI_CODE_HOME/mcp.json:

{
  "mcpServers": {
    "my-stdio-server": {
      "command": "./run-mcp.sh",
      "args": ["--mode", "server"],
      "cwd": "/usr/local/mcp"
    }
  }
}

OAuth Authentication Flow

When a server requires authentication, the TUI status panel (rendered in [apps/kimi-code/src/tui/components/messages/mcp-status-panel.ts](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/src/tui/components/messages/mcp-status-panel.ts)) displays:

MCP server "my-oauth-server" needs OAuth — run /mcp-config login my-oauth-server

Execute the login command:

/mcp-config login my-oauth-server

The skill invokes the dynamically generated tool mcp__my-oauth-server__authenticate, prints the authorization URL with PKCE parameters, and waits for the callback:

Open this URL in your browser to authorize:
https://auth.example.com/authorize?...
Waiting for callback...
✅ Authentication successful for server "my-oauth-server"

Listing Merged Configurations

To view all active servers across all scopes:

/mcp-config list

The skill reads all three mcp.json locations, merges them according to precedence rules, and renders:

Global ( $HOME/.kimi-code/mcp.json )
  my-global-server – http – https://global.example.com/mcp

Project-root ( /repo/.mcp.json )
  shared-server – stdio – command: ./run-shared.sh

Project-local ( ./.kimi-code/mcp.json )
  dev-server – http – https://dev.local/mcp (bearer token from DEV_TOKEN)

Schema Validation and Security

Every configuration entry is validated against Zod schemas defined in [packages/agent-core/src/config/schema.ts](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/src/config/schema.ts). The skill rejects malformed JSON immediately, preventing runtime errors.

Security best practices are enforced conversationally:

• Never store secrets inline. The skill warns if you attempt to paste a bearer token directly into a field.
• Use environment variables. Reference secrets via bearerTokenEnvVar (HTTP) or env (stdio) to keep credentials out of version control.
• Scope isolation. Project-local configurations prevent accidental credential leakage across repositories.

Runtime Behavior and Session Management

MCP servers are loaded once per session start by the McpService. After editing configurations with /mcp-config, you must start a new session (/new) or restart the CLI for changes to take effect.

The runtime merges configurations at startup using the precedence chain: global → project-root → project-local. OAuth state transitions are handled by per-server authenticate tools generated in [packages/agent-core/src/services/mcp/mcp.ts](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/src/services/mcp/mcp.ts).

Summary

• /mcp-config is a builtin skill that eliminates manual JSON editing for MCP server management in Kimi Code.
• Three scopes (global, project-root, project-local) allow flexible configuration with clear override precedence.
• Interactive prompts collect fields validated against McpServerStdioConfigSchema and McpServerHttpConfigSchema.
• OAuth flows are handled via generated mcp__<server>__authenticate tools surfaced through the TUI status panel.
• Session restart required after configuration changes; servers load once at startup via McpService.
• Security enforced through environment variable references and inline secret warnings.

Frequently Asked Questions

How do I change the scope when adding an MCP server?

When you run /mcp-config add <server-name>, the skill interactively prompts you to select the configuration scope. Alternatively, pass the --scope flag with values global, project-root, or project-local to skip the prompt and write directly to the corresponding mcp.json file.

Why aren't my MCP server changes showing up immediately?

Kimi Code loads and merges mcp.json configurations only once when the session starts. After using /mcp-config to add or modify servers, you must run /new to start a fresh session or completely restart the CLI for the new definitions to become active in the runtime.

Can I store bearer tokens directly in the configuration file?

No, and the /mcp-config skill will warn you if you attempt to do so. For HTTP servers, use the bearerTokenEnvVar field to reference an environment variable name. For stdio servers, use the env object to inject variables. This keeps credentials out of JSON files and version control.

What happens if two scopes define the same server name?

Later scopes override earlier ones following the precedence chain: user-global → project-root → project-local. If your project-local .kimi-code/mcp.json defines a server named "dev-api", it completely replaces any "dev-api" definition found in the global or project-root configurations for that working directory.

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