Claude Code MCP reference — transport types (HTTP, SSE, stdio), installation scopes (local, project, user), .mcp.json schema, CLI commands, authentication (OAuth, API keys, env vars), environment variable expansion, plugin-provided MCP servers, subagent MCP scoping, managed enterprise configuration. Background knowledge only — provides authoritative Claude Code documentation for MCP servers. NOT a user-invoked command.
| Transport | When to Use | CLI Flag |
|---|---|---|
| HTTP (recommended) | Cloud services, remote APIs | --transport http |
| SSE (deprecated) | Legacy servers only — prefer HTTP | --transport sse |
| stdio | Local tools, CLI apps, npm packages | --transport stdio (default) |
# HTTP/SSE
claude mcp add --transport http <name> <url>
claude mcp add --transport http <name> <url> --header "Authorization: Bearer $TOKEN"
# stdio
claude mcp add --transport stdio <name> -- <command> [args...]
claude mcp add --transport stdio --env KEY=value <name> -- npx -y @package/server
Option ordering: All flags (--transport, --env, --scope, --header) must come BEFORE the server name. -- separates Claude flags from server command/args.
| Scope | Flag | Storage | Use Case |
|---|---|---|---|
local (default) | --scope local | ~/.claude.json under project path | Personal, this project |
project | --scope project | .mcp.json in repo root (committed) | Team-shared |
user | --scope user | User-wide settings | All your projects |
{
"mcpServers": {
"server-name": {
// HTTP/SSE server
"type": "http", // "http" | "sse"
"url": "https://api.service.com/mcp",
"headers": {
"Authorization": "Bearer ${API_KEY}" // env var expansion
}
},
"local-server": {
// stdio server
"command": "npx",
"args": ["-y", "@package/server"],
"env": {
"DB_URL": "${DATABASE_URL}" // env var expansion
}
}
}
}
Environment variable syntax: ${VAR} expands from process environment. ${VAR:-default} uses default if unset.
| Method | Transport | Example |
|---|---|---|
| OAuth | HTTP | Add server, then /mcp → Select → Authenticate → Browser flow |
| API key | HTTP | --header "Authorization: Bearer $TOKEN" or --header "X-API-Key: $KEY" |
| Env vars | stdio | --env API_KEY=value or "env": {"KEY": "${VAR}"} in .mcp.json |
| Command | Purpose |
|---|---|
claude mcp list | List all configured servers |
claude mcp get <name> | Show server details |
claude mcp remove <name> | Remove a server |
/mcp | Check status, authenticate OAuth servers |
Plugins bundle MCP servers via .mcp.json at plugin root or inline in plugin.json:
{
"server-name": {
"command": "${CLAUDE_PLUGIN_ROOT}/servers/my-server",
"args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
"env": { "DB_URL": "${DB_URL}" }
}
}
${CLAUDE_PLUGIN_ROOT} resolves to the plugin's absolute directory path.
Subagents can declare their own MCP servers in frontmatter:
---