mcp-management

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:

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

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