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

Use this skill when...	Use configure-mcp instead when...
Understanding MCP architecture and concepts	Setting up `.mcp.json` for a new project
Managing servers at runtime (enable/disable)	Installing new servers interactively
Setting up OAuth remote MCP servers	Running compliance checks on MCP configuration
Troubleshooting connection failures	Adding specific servers from the registry
Implementing `list_changed` dynamic discovery	Generating project standards reports

MCP Architecture Overview

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

Transport	Usage	Auth	Configuration
Stdio (local)	Command-based servers via `npx`, `bunx`, `uvx`, `go run`	None needed	`.mcp.json`
HTTP+SSE (remote)	URL-based servers hosted externally	OAuth 2.1	`.mcp.json` with `url` field

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:

Command	Description
`/mcp`	List all configured MCP servers and their connection status
`/mcp enable <server>`	Enable a server for the current session
`/mcp disable <server>`	Disable a server for the current session (session-scoped only)

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:

Claude Code discovers OAuth metadata from /.well-known/oauth-authorization-server
Discovery metadata is cached to avoid repeated HTTP round-trips on session start
User authorizes in the browser; token is stored and reused across sessions
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:

Server signals that additional scope is required
Claude Code prompts the user to re-authorize with the expanded scope
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:

Using /mcp disable <server> then /mcp enable <server> in the session
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

Server declares {"tools": {"listChanged": true}} in its capabilities response
When the server's tool set changes, it sends notifications/tools/list_changed
Claude Code refreshes its tool list from that server automatically
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

Symptom	Likely Cause	Action
Authorization prompt repeats	Token not persisted	Check token storage permissions
Step-up auth loop	Scope mismatch	Revoke and re-authorize
Discovery fails	Server down or URL wrong	Verify server URL and connectivity
Cache stale	Server changed OAuth config	Disable/enable server to refresh

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

Context	Command
Quick status check	`jq -c '.mcpServers \| keys' .mcp.json 2>/dev/null`
Validate JSON	`jq empty .mcp.json 2>&1`
List env vars needed	`jq -r '.mcpServers[] \| .env // {} \| keys[]' .mcp.json 2>/dev/null \| sort -u`
Check specific server	`jq -e '.mcpServers.context7' .mcp.json >/dev/null 2>&1 && echo "installed"`
Find servers in plugin	`find . -name '.mcp.json' -maxdepth 2`

Quick Reference

Server Types by Transport

Type	When to Use	Example
`command` (stdio)	Local tools, no auth needed	`bunx`, `npx`, `uvx`, `go run`
`url` (HTTP+SSE)	Remote hosted servers, OAuth needed	`https://...`

Key Files

File	Purpose
`.mcp.json`	Project-level MCP server config (team-shareable)
`~/.claude/settings.json`	User-level MCP server config (personal)
`plugin.json`	Plugin-level MCP server declarations

mcp-management