docs: add Claude Code MCP server management reference
Reference guide for MCP server CLI commands, installation scopes, OAuth authentication, and configuration file locations. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
314
docs/claude-code-mcp-management.md
Normal file
314
docs/claude-code-mcp-management.md
Normal file
@@ -0,0 +1,314 @@
|
||||
# Claude Code MCP Server Management
|
||||
|
||||
> Source: https://code.claude.com/docs/en/mcp (fetched 2026-02-06)
|
||||
|
||||
## Quick Reference - Managing Servers
|
||||
|
||||
### CLI Commands
|
||||
|
||||
```bash
|
||||
# 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)
|
||||
|
||||
```bash
|
||||
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)
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
```bash
|
||||
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).
|
||||
|
||||
```bash
|
||||
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp
|
||||
```
|
||||
|
||||
`.mcp.json` format:
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"shared-server": {
|
||||
"command": "/path/to/server",
|
||||
"args": [],
|
||||
"env": {}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### User Scope
|
||||
|
||||
Available across all projects, private to your account. Stored in `~/.claude.json`.
|
||||
|
||||
```bash
|
||||
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`
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"api-server": {
|
||||
"type": "http",
|
||||
"url": "${API_BASE_URL:-https://api.example.com}/mcp",
|
||||
"headers": {
|
||||
"Authorization": "Bearer ${API_KEY}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## OAuth Authentication
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
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 |
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
claude mcp serve
|
||||
```
|
||||
|
||||
Claude Desktop config:
|
||||
```json
|
||||
{
|
||||
"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
|
||||
Reference in New Issue
Block a user