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

```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