Install MCP

Install MCP Server

Install, list, and remove MCP servers for AI coding tools (ZCode, Claude Code).

Two config formats exist — this skill auto-detects which tool the user runs and writes the right one:

⚠️ Common mistake: ZCode uses mcp.servers (dot, nested), Claude Code uses mcpServers (camelCase, flat). Don't mix them up.

Step 1: Detect which tool the user runs

Ask or infer from context:

• Working dir contains .zcode/ or user mentions "ZCode" → ZCode format
• Working dir contains .claude/ or .mcp.json, or user mentions "Claude Code" → Claude Code format
• Unsure → ask: "你用的是 ZCode 还是 Claude Code?"

Step 2: Check existing config

Read the config file (don't assume it exists):

# ZCode
cat ~/.zcode/cli/config.json 2>/dev/null || echo "(not exists)"

# Claude Code
cat ~/.claude.json 2>/dev/null || echo "(not exists)"

Three cases:

• File doesn't exist → create from scratch with the right skeleton
• File exists, no MCP node → add the node (merge, don't overwrite)
• Same server name exists → ask user whether to overwrite

Step 3: Confirm prerequisites

Most MCP servers launch via npx, needing Node.js 18+:

node --version    # need v18+
npx --version     # confirm npx available

For Python-based MCP, check python --version and uv/pip. Tell the user what's missing.

Step 4: Write config (merge, never overwrite)

Always merge with Python to avoid corrupting other config. Never use text replacement.

ZCode (~/.zcode/cli/config.json):

import json
path = "~/.zcode/cli/config.json"  # expand ~ to absolute
with open(path, encoding="utf-8") as f:
    config = json.load(f)  # if not exists, start from {}
config.setdefault("mcp", {}).setdefault("servers", {})["server-name"] = {
    "command": "npx",
    "args": ["@package/mcp@latest"]
}
with open(path, "w", encoding="utf-8") as f:
    json.dump(config, f, indent=2, ensure_ascii=False)

Claude Code (~/.claude.json):

import json
path = "~/.claude.json"
with open(path, encoding="utf-8") as f:
    config = json.load(f)
config.setdefault("mcpServers", {})["server-name"] = {
    "command": "npx",
    "args": ["@package/mcp@latest"]
}
with open(path, "w", encoding="utf-8") as f:
    json.dump(config, f, indent=2, ensure_ascii=False)

After writing, validate JSON:

python -c "import json; json.load(open('<path>')); print('✓ valid')"

Step 5: Verify (the critical step most people miss)

Editing the config does NOT update the current session's tools. MCP tools are injected at session start; mid-session config changes need a new session to take effect.

Verification path:

1. Have the user check the tool's UI: does the MCP server show "connected"?
2. Have the user start a brand-new session (not resume the old one)
3. In the new session, check: can the model see mcp__<server-name>__* tools?

If the user says "I restarted but still can't call it" — they probably resumed the old session instead of starting fresh. Emphasize: new session, not resume.

Common MCP servers

Playwright (browser automation)

"playwright": { "command": "npx", "args": ["@playwright/mcp@latest"] }

Context7 (up-to-date docs)

"context7": { "command": "npx", "args": ["-y", "@upstash/context7-mcp"] }

Sequential Thinking (structured reasoning)

"sequential-thinking": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"] }

Filesystem (file system access)

"filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "<allowed-dir>"] }

GitHub (GitHub API access)

"github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "<token>" } }

Remove an MCP server

Read config → delete the key under the servers node → write back. Same "new session to take effect" rule applies.

Troubleshooting

Config written but tool shows disconnected?

• Check JSON is valid (python -c "import json; json.load(open('<path>'))")
• Check command is in PATH (which npx)
• Check logs: ZCode → ~/.zcode/v2/logs/, Claude Code → ~/.claude/logs/

Restarted the tool but still can't call the MCP?

• You likely resumed an old session. Start a new session.

npx times out on first run?

• First npx @xxx/mcp@latest downloads the package. Run it manually once to cache: npx @xxx/mcp@latest --help

Project-level vs user-level conflict?

• Project-level overrides user-level for the same server name.

Key reminders

• Always merge JSON with Python, never text-replace (corrupts other config)
• mcp.servers (ZCode) vs mcpServers (Claude Code) — don't confuse them
• Config changes need a new session to take effect — not restart, not resume
• When unsure which tool the user runs, ask