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

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"

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.

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

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

sse (Server-Sent Events)

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

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

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

Codex (~/.codex/config.toml)

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

Gemini (~/.gemini/settings.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