mcp-management（MCP 服务管理）

MCP Server Management

Expert knowledge for managing Model Context Protocol (MCP) servers on a project-by-project basis, with support for runtime management, OAuth remote servers, and dynamic server discovery.

When to Use This Skill

MCP Architecture Overview

MCP connects Claude Code to external tools and data sources via two transport types:

Local Server (Stdio)

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

Remote Server (HTTP+SSE with OAuth)

{
  "mcpServers": {
    "my-remote-server": {
      "url": "https://mcp.example.com/sse",
      "headers": {
        "Authorization": "Bearer ${MY_API_TOKEN}"
      }
    }
  }
}

Runtime Server Management

/mcp Commands (Claude Code 2.1.50+)

Use these slash commands to manage servers without editing configuration files:

Note: Enable/disable are session-scoped. Edit .mcp.json for permanent changes.

Check Server Status

# List configured servers
jq -r '.mcpServers | keys[]' .mcp.json

# Verify server config
jq '.mcpServers.context7' .mcp.json

OAuth Support for Remote MCP Servers

Claude Code 2.1.50+ includes improved OAuth handling for remote MCP servers:

OAuth Flow Overview

Remote MCP servers using HTTP+SSE transport use OAuth 2.1:

1. Claude Code discovers OAuth metadata from /.well-known/oauth-authorization-server
2. Discovery metadata is cached to avoid repeated HTTP round-trips on session start
3. User authorizes in the browser; token is stored and reused across sessions
4. If additional permissions are needed mid-session, step-up auth is triggered

Step-Up Auth

Step-up auth occurs when a tool requires elevated permissions not granted in the initial OAuth flow:

1. Server signals that additional scope is required
2. Claude Code prompts the user to re-authorize with the expanded scope
3. After re-authorization, the original tool call is retried automatically

OAuth Discovery Caching

Metadata from /.well-known/oauth-authorization-server is cached per server URL. If a remote server changes its OAuth configuration, force a refresh by:

1. Using /mcp disable <server> then /mcp enable <server> in the session
2. Or restarting Claude Code to clear the cache

Remote Server Configuration

{
  "mcpServers": {
    "my-service": {
      "url": "https://api.example.com/mcp/sse",
      "headers": {
        "Authorization": "Bearer ${MY_SERVICE_TOKEN}"
      }
    }
  }
}

Use ${VAR_NAME} syntax for environment variable references — never hardcode tokens.

Dynamic Tool Discovery (list_changed)

MCP servers that support the list_changed capability can update their tool list dynamically without requiring a session restart.

How It Works

1. Server declares {"tools": {"listChanged": true}} in its capabilities response
2. When the server's tool set changes, it sends notifications/tools/list_changed
3. Claude Code refreshes its tool list from that server automatically
4. New tools become available immediately in the current session

Practical Implications

• No session restart required when a server adds or removes tools dynamically
• Useful for servers that expose project-context-specific tools
• For resources/list_changed and prompts/list_changed — same pattern applies

Checking Capabilities

The capabilities are declared by the server during initialization. Claude Code subscribes automatically when the server declares support. No client-side configuration is required.

Troubleshooting

Server Won't Connect

# Verify server command is available
which bunx  # or npx, uvx, go

# Test server manually
bunx -y @upstash/context7-mcp  # Should start without error

# Validate JSON syntax
jq empty .mcp.json && echo "JSON is valid" || echo "JSON syntax error"

Missing Environment Variables

# List all env vars referenced in .mcp.json
jq -r '.mcpServers[] | .env // {} | to_entries[] | "\(.key)=\(.value)"' .mcp.json

# Check which are set
jq -r '.mcpServers[] | .env // {} | keys[]' .mcp.json | while read var; do
  clean_var=$(echo "$var" | sed 's/\${//;s/}//')
  [ -z "${!clean_var}" ] && echo "MISSING: $clean_var" || echo "SET: $clean_var"
done

OAuth Remote Server Issues

SDK MCP Server Race Condition (2.1.49/2.1.50)

When using claude-agent-sdk 0.1.39 with MCP servers, a known race condition in SDK-based MCP servers causes CLIConnectionError: ProcessTransport is not ready for writing. Workaround: use pre-computed context or static stdio servers instead of SDK MCP servers.

Configuration Patterns

Project-Scoped (Recommended)

Store in .mcp.json at project root. Add to .gitignore for personal configs or track for team configs.

{
  "mcpServers": {
    "context7": {
      "command": "bunx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  }
}

User-Scoped (Personal)

For servers you want available everywhere, add to ~/.claude/settings.json:

{
  "mcpServers": {
    "my-personal-tool": {
      "command": "npx",
      "args": ["-y", "my-personal-mcp"]
    }
  }
}

Plugin-Scoped

Plugins can declare MCP servers in plugin.json:

{
  "mcpServers": {
    "plugin-api": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/api-server",
      "args": ["--port", "8080"]
    }
  }
}

Or via external file: "mcpServers": "./.mcp.json"

Agentic Optimizations

Quick Reference

Server Types by Transport

Key Files