cc-switch/docs/user-manual/en/3-extensions/3.1-mcp.md

# 3.1 MCP Server Management

## What is MCP

MCP (Model Context Protocol) is a protocol that allows AI tools to access external data sources and tools. Through MCP servers, you can enable AI to:

- Access file systems
- Make network requests
- Query databases
- Call external APIs

## Open the MCP Panel

Click the **MCP** button in the top navigation bar.

## Panel Overview

![image-20260108005723522](../../assets/image-20260108005723522.png)

## Add MCP Server

### Using Preset Templates

1. Click the **+** button in the top-right corner
2. Select a template from the "Preset" dropdown
3. Modify the configuration as needed
4. Click "Save"

![image-20260108005739731](../../assets/image-20260108005739731.png)

### Common Presets

| Preset | Package Name | Description |
|--------|-------------|-------------|
| fetch | mcp-server-fetch | HTTP request tool that enables AI to fetch web content |
| time | @modelcontextprotocol/server-time | Time tool that provides current time information |
| memory | @modelcontextprotocol/server-memory | Memory tool that enables AI to store and retrieve information |
| sequential-thinking | @modelcontextprotocol/server-sequential-thinking | Chain-of-thought tool that enhances AI reasoning |
| context7 | @upstash/context7-mcp | Documentation search tool for querying technical docs |

### Custom Configuration

After selecting "Custom", fill in:

| Field | Required | Description |
|-------|----------|-------------|
| Server ID | Yes | Unique identifier |
| Name | No | Display name |
| Description | No | Function description |
| Transport Type | Yes | stdio / http / sse |
| Command | Yes* | Required for stdio type |
| Arguments | No | Command-line arguments |
| URL | Yes* | Required for http/sse type |
| Headers | No | Request headers for http/sse type |
| Environment Variables | No | Environment variables passed to the server |

## Transport Types

### stdio (Standard I/O)

The most common type, communicating by launching a local process.

```json
{
  "command": "uvx",
  "args": ["mcp-server-fetch"],
  "env": {}
}
```

**Requirements**:
- The corresponding command must be installed (e.g., `uvx`, `npx`)
- The server program must be in PATH

### http

Communicates with a remote server via HTTP protocol.

```json
{
  "url": "http://localhost:8080/mcp"
}
```

### sse (Server-Sent Events)

Communicates with a server via SSE protocol, supporting real-time push.

```json
{
  "url": "http://localhost:8080/sse"
}
```

## App Binding

Each MCP server can independently control which apps it is enabled for.

### Toggle Description

| Toggle | Effect | Configuration File Path |
|--------|--------|------------------------|
| Claude | Sync to Claude Code | `~/.claude.json`'s `mcpServers` |
| Codex | Sync to Codex | `~/.codex/config.toml`'s `[mcp_servers]` |
| Gemini | Sync to Gemini CLI | `~/.gemini/settings.json`'s `mcpServers` |
| OpenCode | Sync to OpenCode | `~/.opencode/config.json`'s `mcpServers` |

> **Note**: OpenClaw does not currently support MCP server management. MCP functionality is currently only supported for Claude, Codex, Gemini, and OpenCode.

### Toggle Implementation

When enabling an app's toggle, CC Switch will:

1. **Update database**: Set the server's `apps.claude/codex/gemini/opencode` status to `true`
2. **Sync to live configuration**: Write the server configuration to the corresponding app's configuration file
3. **Take effect immediately**: The new MCP server is automatically loaded the next time the CLI tool starts

When disabling an app's toggle, CC Switch will:

1. **Update database**: Set the corresponding app status to `false`
2. **Remove from live configuration**: Delete the server from the app's configuration file
3. **Take effect immediately**: The MCP server is no longer loaded the next time the CLI tool starts

### Sync Conditions

MCP server sync only executes when the corresponding app is installed:

- **Claude**: Requires `~/.claude/` directory or `~/.claude.json` file to exist
- **Codex**: Requires `~/.codex/` directory to exist
- **Gemini**: Requires `~/.gemini/` directory to exist
- **OpenCode**: Requires `~/.opencode/` directory to exist

> **Tip**: If a CLI tool is not installed, enabling its toggle will not cause an error, but the configuration will not be written.

When the toggle is disabled, the configuration is removed from the file.

## Edit Server

1. Click the "Edit" button on the right side of the server row
2. Modify the configuration
3. Click "Save"

Changes are immediately synced to enabled app configuration files.

## Delete Server

1. Click the "Delete" button on the right side of the server row
2. Confirm deletion

After deletion, the configuration is removed from all app configuration files.

## Import Existing Configurations

If you have already configured MCP servers in CLI tools, you can import them into CC Switch:

1. Click the "Import" button
2. Select the app to import from (Claude/Codex/Gemini/OpenCode)
3. CC Switch reads the existing configuration and imports it

## Configuration File Formats

### Claude (`~/.claude.json`)

```json
{
  "mcpServers": {
    "mcp-fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    }
  }
}
```

### Codex (`~/.codex/config.toml`)

```toml
[mcp_servers.mcp-fetch]
command = "uvx"
args = ["mcp-server-fetch"]
```

### Gemini (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "mcp-fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    }
  }
}
```

## FAQ

### Server Fails to Start

Check:
- Is the command properly installed (e.g., `uvx`)
- Is the command in PATH
- Are the arguments correct

### Configuration Not Taking Effect

Ensure:
- The corresponding app toggle is enabled
- The CLI tool has been restarted