mcp-management

Use when adding, configuring, or troubleshooting MCP servers in Claude Code projects — transport types, scoping, OAuth, .mcp.json format, Tool Search, and managed MCP

Model	Source
inherit	pack: claude-code-internals

Tools: Read, Grep, Glob, WebFetch, WebSearch

Full Reference

MCP Management

Announcement

┏━ 🔧 mcp-management ━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ your friendly armadillo is here to serve you ┃ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

Claude Code connects to external tools and services via the Model Context Protocol (MCP) — an open standard for AI-tool integrations.

---

Quick Reference

CLI Commands

Command	What it does
claude mcp add --transport http <name> <url>	Add remote HTTP server (recommended)
claude mcp add --transport sse <name> <url>	Add remote SSE server (deprecated)
claude mcp add --transport stdio <name> -- <cmd> [args]	Add local stdio server
claude mcp add-json <name> '<json>'	Add server from JSON config
claude mcp add-from-claude-desktop	Import servers from Claude Desktop
claude mcp list	List all configured servers
claude mcp get <name>	Get details for a specific server
claude mcp remove <name>	Remove a server
claude mcp reset-project-choices	Reset project-scope approval prompts
claude mcp serve	Expose Claude Code itself as an MCP server
/mcp (in-session)	Check server status + OAuth authentication

Transport Types

Transport	When to use	Status
http (streamable HTTP)	Cloud APIs, remote servers	✓ Recommended
stdio	Local processes, scripts, direct system access	✓ Supported
sse (Server-Sent Events)	Legacy remote servers	⚠ Deprecated — use http

Scope Overview

Scope	Flag	Storage	Visibility
local	--scope local (default)	~/.claude.json	You only, current project
project	--scope project	.mcp.json in project root	All team members (commit to VCS)
user	--scope user	~/.claude.json	You across all projects

Scope Precedence

When same-named servers exist at multiple scopes: local > project > user

Personal configs override shared ones.

---

Transport Details

HTTP (Streamable HTTP) — Recommended

The streamable-http transport replaced SSE in the MCP 2025-03-26 spec. Use it for all cloud-based services.

# Basic
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"

# Real example: Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Real example: GitHub
claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# Real example: Sentry
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

Stdio — Local Processes

Stdio servers run as local processes and communicate via stdin/stdout. Ideal for direct system access.

# Basic syntax — note: ALL flags before name, -- separates from command
claude mcp add --transport stdio [options] <name> -- <command> [args...]

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

# With multiple args
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:[email protected]:5432/analytics"

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

Flag ordering rule: All options (--transport, --env, --scope, --header) must come before the server name. The -- separator prevents flag conflicts between Claude’s flags and the server’s flags.

SSE — Deprecated

# Only use if the server does not support HTTP transport
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"

---

Scoping

Local Scope (Default)

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

# These are equivalent
claude mcp add --transport http stripe https://mcp.stripe.com
claude mcp add --transport http stripe --scope local https://mcp.stripe.com

Use for: Personal dev servers, experiments, sensitive credentials not to be shared.

Project Scope

Stored in .mcp.json at project root. Designed to be committed to version control.

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

Use for: Team-shared servers, project-specific tools, services required for collaboration.

Security: Claude Code prompts for approval before using project-scoped servers. Reset approvals with:

claude mcp reset-project-choices

User Scope

Stored in ~/.claude.json. Available across all projects on your machine, private to you.

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

Use for: Personal utilities across multiple projects, frequently-used development tools.

---

.mcp.json Format

The project-scope config file lives at <project-root>/.mcp.json. Commit it to VCS for team sharing.

Basic Structure

{
  "mcpServers": {
    "server-name": {
      "type": "http",
      "url": "https://mcp.example.com/mcp"
    },
    "local-tool": {
      "type": "stdio",
      "command": "/path/to/server",
      "args": ["--flag", "value"],
      "env": {
        "KEY": "value"
      }
    }
  }
}

Environment Variable Expansion

Claude Code expands env vars in .mcp.json at runtime — keeps secrets out of the file.

Supported syntax:

Syntax	Behavior
${VAR}	Expands to value of VAR; fails if unset
${VAR:-default}	Expands to VAR if set, otherwise default

Where expansion works: command, args, env, url, headers

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    },
    "local-db": {
      "type": "stdio",
      "command": "${TOOLS_DIR:-/usr/local/bin}/db-server",
      "args": ["--dsn", "${DATABASE_URL}"],
      "env": {
        "CACHE_DIR": "${CACHE_DIR:-/tmp}"
      }
    }
  }
}

If a required variable is unset and has no default, config parsing fails.

Plugin MCP Servers in .mcp.json

Plugins can bundle MCP servers in .mcp.json using a plugin root variable for relative paths:

{
  "database-tools": {
    "command": "./servers/db-server",
    "args": ["--config", "./config.json"],
    "env": {
      "DB_URL": "${DB_URL}"
    }
  }
}

---

OAuth Configuration

Claude Code supports OAuth 2.0 for remote MCP servers.

Auto OAuth (Most Servers)

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

# 2. In-session: authenticate
> /mcp
# Follow browser flow — tokens stored securely, auto-refreshed

# Revoke: use "Clear authentication" in /mcp menu

Pre-configured OAuth Credentials

For servers that don’t support dynamic client registration (error: “Incompatible auth server: does not support dynamic client registration”):

Step 1: Register an OAuth app in the server’s developer portal. Note client ID, secret, and register redirect URI: http://localhost:<PORT>/callback

Step 2: Add with credentials:

# Via mcp add (--client-secret prompts for masked input)
claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

# Via mcp add-json
claude mcp add-json my-server \
  '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' \
  --client-secret

# Via env var (CI / non-interactive)
MCP_CLIENT_SECRET=your-secret claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

Step 3: In-session, run /mcp and complete browser auth.

Notes:

• Client secret stored in macOS Keychain or credentials file — not in config
• Public OAuth clients (no secret): use --client-id only, omit --client-secret
• OAuth only applies to HTTP and SSE transports — no effect on stdio
• Verify credentials: claude mcp get <name>

---

MCP Tool Search

When you have many MCP servers, tool definitions can consume significant context. Tool Search solves this by loading tools on-demand.

How It Works

1. MCP tools are deferred instead of loaded into context upfront
2. Claude uses a search tool to discover relevant MCP tools when needed
3. Only tools Claude actually needs are loaded into context
4. Tools work identically from the user’s perspective

Auto-activates when: MCP tool descriptions exceed 10% of the context window.

Requires: Sonnet 4+ or Opus 4+. Haiku models do not support Tool Search.

Impact: Can reduce context from ~134,000 tokens to ~5,000 tokens (up to 85% reduction).

Configuration

# Control via ENABLE_TOOL_SEARCH env var
ENABLE_TOOL_SEARCH=auto claude      # Default: activates at 10% threshold
ENABLE_TOOL_SEARCH=auto:5 claude    # Custom 5% threshold
ENABLE_TOOL_SEARCH=true claude      # Always enabled
ENABLE_TOOL_SEARCH=false claude     # Disabled — all tools loaded upfront

Or in settings.json:

{
  "env": {
    "ENABLE_TOOL_SEARCH": "auto:5"
  }
}

To disable the MCPSearch tool specifically:

{
  "permissions": {
    "deny": ["MCPSearch"]
  }
}

For MCP Server Authors

Add clear server instructions explaining what your server does — Tool Search uses these to decide when to search for your tools, similar to how skill descriptions work.

---

Managed MCP (Enterprise)

For organizations needing centralized MCP control.

Option 1: Exclusive Control with managed-mcp.json

Deploy a fixed set of MCP servers users cannot modify or extend. Users cannot run claude mcp add.

System paths (require admin privileges):

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

Format (same as .mcp.json):

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    },
    "company-internal": {
      "type": "stdio",
      "command": "/usr/local/bin/company-mcp-server",
      "args": ["--config", "/etc/company/mcp-config.json"],
      "env": {
        "COMPANY_API_URL": "https://internal.company.com"
      }
    }
  }
}

Option 2: Policy-Based Control (Allowlists / Denylists)

Allow users to add servers, but restrict which ones. Configured in managed settings.json.

Allowlist behavior:

Value	Result
undefined (default)	No restrictions — users can add any server
[] empty array	Complete lockdown — no MCP servers allowed
List of entries	Only matching servers allowed

Denylist: Blocks specified servers. Denylist takes absolute precedence over allowlist.

Match strategies (each entry uses exactly one):

Field	Matches
serverName	Configured server name
serverCommand	Exact stdio command + args array
serverUrl	Remote URL with * wildcard support

{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverCommand": ["npx", "-y", "@modelcontextprotocol/server-filesystem"] },
    { "serverUrl": "https://mcp.company.com/*" },
    { "serverUrl": "https://*.internal.corp/*" }
  ],
  "deniedMcpServers": [
    { "serverName": "dangerous-server" },
    { "serverUrl": "https://*.untrusted.com/*" }
  ]
}

Command matching rules:

• Exact match — ["npx", "-y", "pkg"] does NOT match ["npx", "pkg"] or ["npx", "-y", "pkg", "--flag"]
• When any serverCommand entry exists in allowlist, stdio servers must match one — name alone is insufficient
• Command restrictions do not apply to remote (HTTP/SSE) servers

URL matching rules:

• * matches any sequence of characters
• When any serverUrl entry exists in allowlist, remote servers must match one — name alone is insufficient

Combining options: managed-mcp.json (Option 1) + allowlists/denylists (Option 2) can coexist — allowlists/denylists filter which managed servers are loaded.

---

claude mcp serve — Claude Code as MCP Server

Expose Claude Code’s tools (Read, Edit, LS, Bash, etc.) to other MCP clients.

claude mcp serve

Claude Desktop integration (claude_desktop_config.json):

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

If claude is not in PATH, use the full path:

which claude
# → /usr/local/bin/claude

# Then in config:
{
  "command": "/usr/local/bin/claude"
}

Use cases: Connect Claude Desktop, Cursor, Windsurf, or any MCP client to Claude Code’s file editing and command execution tools.

Note: The MCP client is responsible for implementing user confirmation for individual tool calls — claude mcp serve does not add confirmation prompts.

---

Output Limits

Setting	Value
Warning threshold	10,000 tokens
Default max output	25,000 tokens
Override env var	MAX_MCP_OUTPUT_TOKENS

export MAX_MCP_OUTPUT_TOKENS=50000
claude

---

Dynamic Tool Updates

Claude Code supports MCP list_changed notifications. When an MCP server signals its tools changed, Claude Code automatically refreshes capabilities — no reconnect needed.

---

MCP Resources via @ Mentions

MCP servers can expose resources referenceable with @:

# Format
@server:protocol://resource/path

# Examples
@github:issue://123
@docs:file://api/authentication
@postgres:schema://users

Type @ in a prompt to see available resources from all connected servers.

---

Add from JSON

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

# Stdio server
claude mcp add-json local-weather \
  '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'

# HTTP with pre-configured OAuth
claude mcp add-json my-server \
  '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' \
  --client-secret

---

Import from Claude Desktop

# Interactive selection dialog
claude mcp add-from-claude-desktop

# With user scope
claude mcp add-from-claude-desktop --scope user

Limitations: macOS and WSL only. Reads from Claude Desktop’s standard config location. Name conflicts get numerical suffix (server_1).

---

Claude.ai Servers in Claude Code

If logged in with a Claude.ai account, servers configured at claude.ai/settings/connectors are automatically available. Team/Enterprise plans: admin-only server management.

# Disable Claude.ai servers in Claude Code
ENABLE_CLAUDEAI_MCP_SERVERS=false claude

---

MCP Prompts as Commands

MCP servers can expose prompts as slash commands:

# Format
/mcp__<servername>__<promptname>

# Without args
/mcp__github__list_prs

# With args
/mcp__github__pr_review 456
/mcp__jira__create_issue "Bug in login flow" high

Server and prompt names are normalized — spaces become underscores.

---

Troubleshooting

Server Not Connecting

Symptom	Check
Connection closed on Windows	Add cmd /c wrapper for stdio: -- cmd /c npx -y pkg
Server times out on start	Set MCP_TIMEOUT=10000 claude (ms); default may be too short
spawn claude ENOENT in mcp serve	which claude and use full path in config
Server added but not visible	Run /mcp in-session to check actual status

Tools Not Appearing

Symptom	Check
No tools after add	Restart Claude Code — plugin MCP changes require restart
Tools present but not usable	Check /mcp for auth status; may need OAuth via /mcp
Tool Search hiding tools	Set ENABLE_TOOL_SEARCH=false to load all upfront
Model doesn’t support Tool Search	Haiku models don’t support tool_reference blocks — use Sonnet 4+

Transport Errors

Error	Cause	Fix
Incompatible auth server: does not support dynamic client registration	Server requires pre-configured OAuth credentials	Register OAuth app, use --client-id + --client-secret flags
SSE transport issues	SSE is deprecated	Switch to --transport http if server supports it
HTTP streamable connection error	Redirect after OAuth browser auth	Paste full callback URL from browser address bar when prompted
MAX_MCP_OUTPUT_TOKENS warnings	Tool output too large	Increase limit or configure server to paginate

Project-Scope Approval Issues

# Reset approval choices for .mcp.json servers
claude mcp reset-project-choices

Common Gotchas

• Flag order matters: All claude mcp add flags must come before the server name. -- separates server name from the command.
• SSE is deprecated: Migrate to --transport http whenever the server supports it.
• Scope naming changed: Older docs say project for private and global for cross-project — new names are local and user.
• Windows stdio: Always wrap with cmd /c when using npx on native Windows (not WSL).
• Managed MCP paths: System directories only — ~/Library/... won’t work; requires /Library/... (admin).
• Tool Search model requirement: Sonnet 4+ or Opus 4+ required — Haiku does not support tool_reference blocks.
• Dynamic client registration error: Means the server requires you to register an OAuth app manually first before adding to Claude Code.
• Plugin MCP server changes: Require Claude Code restart to apply — enable/disable doesn’t hot-reload.

---

Environment Variables Reference

Variable	Effect
MCP_TIMEOUT	Server startup timeout in ms (e.g., MCP_TIMEOUT=10000)
MAX_MCP_OUTPUT_TOKENS	Max tokens per MCP tool output (default: 25,000)
ENABLE_TOOL_SEARCH	Tool Search mode: auto, auto:<N>, true, false
ENABLE_CLAUDEAI_MCP_SERVERS	Set false to disable Claude.ai servers in Claude Code
MCP_CLIENT_SECRET	OAuth client secret for non-interactive/CI setup
Plugin root variable	Available inside plugin .mcp.json for relative paths