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

> Easily configure MCP servers conversationally with Kimi Code using the /mcp-config command. Add edit authenticate and list servers interactively eliminating manual JSON edits.

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

---

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

```bash
/mcp-config add my-http-server

```

The skill prompts for required fields from [`McpServerHttpConfigSchema`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/src/config/schema.ts):

```

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

```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:

```bash
/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`:

```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)](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:

```bash
/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:

```bash
/mcp-config list

```

The skill reads all three [`mcp.json`](https://github.com/MoonshotAI/kimi-code/blob/main/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)](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`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/src/services/mcp/mcpService.ts). 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)](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`](https://github.com/MoonshotAI/kimi-code/blob/main/mcp.json) file.

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

Kimi Code loads and merges [`mcp.json`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/.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.