PepApi.Core/docs/claude-code-mcp-management.md

Claude Code MCP Server Management

Source: https://code.claude.com/docs/en/mcp (fetched 2026-02-06)

Quick Reference - Managing Servers

CLI Commands

# List all configured servers
claude mcp list

# Get details for a specific server
claude mcp get <name>

# Remove a server
claude mcp remove <name>

# Add servers
claude mcp add --transport http <name> <url>
claude mcp add --transport sse <name> <url>
claude mcp add --transport stdio <name> -- <command> [args...]
claude mcp add-json <name> '<json>'

# Import from Claude Desktop
claude mcp add-from-claude-desktop

# Reset project approval choices
claude mcp reset-project-choices

In-Session Management

• /mcp - View and manage all MCP servers, check status, authenticate, reconnect
• @ mentions - Toggle MCP servers on/off during a session (enable/disable)

Restarting After Changes

After editing config files directly, restart Claude Code for changes to take effect.

---

Installing MCP Servers

Option 1: Remote HTTP Server (Recommended)

claude mcp add --transport http <name> <url>

# With Bearer token
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

Option 2: Remote SSE Server (Deprecated)

claude mcp add --transport sse <name> <url>

# With auth header
claude mcp add --transport sse private-api https://api.company.com/sse \
  --header "X-API-Key: your-key-here"

Option 3: Local stdio Server

claude mcp add [options] <name> -- <command> [args...]

# Example
claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \
  -- npx -y airtable-mcp-server

Important: Option ordering - All options (--transport, --env, --scope, --header) must come before the server name. The -- separates the server name from the command/args.

Add from JSON

claude mcp add-json <name> '<json>'

# HTTP example
claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

# stdio example
claude mcp add-json local-tool '{"type":"stdio","command":"/path/to/server","args":["--flag"],"env":{"KEY":"value"}}'

Windows Note

On native Windows (not WSL), local MCP servers using npx require the cmd /c wrapper:

claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

---

MCP Installation Scopes

Local Scope (Default)

Private to you, only accessible in current project. Stored in ~/.claude.json under project path.

claude mcp add --transport http stripe --scope local https://mcp.stripe.com

Project Scope

Shared via .mcp.json at project root (checked into version control).

claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

.mcp.json format:

{
  "mcpServers": {
    "shared-server": {
      "command": "/path/to/server",
      "args": [],
      "env": {}
    }
  }
}

User Scope

Available across all projects, private to your account. Stored in ~/.claude.json.

claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

Precedence

Local > Project > User (local overrides project, project overrides user).

---

Environment Variable Expansion in .mcp.json

Supported syntax:

• ${VAR} - Expands to value of VAR
• ${VAR:-default} - Uses default if VAR not set

Works in: command, args, env, url, headers

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

---

OAuth Authentication

# Add server requiring auth
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# Then authenticate in Claude Code
> /mcp
# Follow browser login flow

Pre-configured OAuth Credentials

For servers that don't support dynamic client registration:

claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

---

MCP Tool Search

Automatically enabled when MCP tool descriptions exceed 10% of context window. Tools are loaded on-demand instead of all upfront.

Configure with ENABLE_TOOL_SEARCH environment variable:

Value	Behavior
auto	Activates at 10% threshold (default)
auto:<N>	Custom threshold percentage
true	Always enabled
false	Disabled, all tools loaded upfront

ENABLE_TOOL_SEARCH=auto:5 claude   # 5% threshold
ENABLE_TOOL_SEARCH=false claude     # Disable

---

MCP Output Limits

• Warning threshold: 10,000 tokens
• Default max: 25,000 tokens
• Configure with: MAX_MCP_OUTPUT_TOKENS=50000

---

Using MCP Resources

Reference resources with @ mentions:

> Can you analyze @github:issue://123 and suggest a fix?
> Compare @postgres:schema://users with @docs:file://database/user-model

---

Using MCP Prompts as Commands

MCP prompts become available as /mcp__servername__promptname commands:

> /mcp__github__list_prs
> /mcp__github__pr_review 456

---

Dynamic Tool Updates

Claude Code supports MCP list_changed notifications, allowing servers to dynamically update available tools without reconnecting.

---

Claude Code as MCP Server

claude mcp serve

Claude Desktop config:

{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "claude",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

---

Plugin-provided MCP Servers

Plugins can bundle MCP servers in .mcp.json at plugin root or inline in plugin.json. Servers start automatically when plugin is enabled. Use ${CLAUDE_PLUGIN_ROOT} for plugin-relative paths.

---

Managed MCP Configuration (Enterprise)

Option 1: Exclusive Control - managed-mcp.json

Deploy to system directory:

• macOS: /Library/Application Support/ClaudeCode/managed-mcp.json
• Linux/WSL: /etc/claude-code/managed-mcp.json
• Windows: C:\Program Files\ClaudeCode\managed-mcp.json

Users cannot add/modify/use any servers not in this file.

Option 2: Policy-Based Control

Use allowedMcpServers and deniedMcpServers in managed settings. Supports restriction by:

• Server name (serverName)
• Command (serverCommand) - exact match
• URL pattern (serverUrl) - supports wildcards with *

Denylist takes absolute precedence over allowlist.

---

Configuration File Locations

Scope	Location
User + Local MCP	~/.claude.json
Project MCP	.mcp.json (project root)
General local settings	.claude/settings.local.json (project dir)
Managed MCP	System directories (see above)

---

Tips

• Use --scope flag: local (default), project (shared), user (global)
• Set env vars with --env KEY=value
• Configure startup timeout: MCP_TIMEOUT=10000 claude
• Use /mcp to authenticate with OAuth servers
• Use /mcp to reconnect to servers