Claude Code MCP Commands — Quick Reference for Setup, Config & Troubleshooting

Claude Code ships with built-in MCP (Model Context Protocol) support. Add external tools — databases, APIs, SaaS platforms — directly from the terminal with claude mcp add. This page covers every command, config option, and common fix.

Command Reference

Command	What It Does
claude mcp add	Add an MCP server (HTTP, stdio, or SSE)
claude mcp list	List all configured servers
claude mcp get <name>	Show details for a specific server
claude mcp remove <name>	Remove a server
claude mcp add-json <name> '<json>'	Add a server from a JSON config string
claude mcp add-from-claude-desktop	Import servers from Claude Desktop
claude mcp serve	Run Claude Code itself as an MCP server
/mcp	(In-session) Show server status, authenticate OAuth servers

claude mcp add — Adding a Server

All options (--transport, --env, --scope, --header) must come before the server name. The -- (double dash) separates the server name from the command and arguments passed to stdio servers.

HTTP (recommended for remote servers)

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

# Examples
claude mcp add --transport http notion https://mcp.notion.com/mcp
claude mcp add --transport http stripe https://mcp.stripe.com
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# With authentication header
claude mcp add --transport http my-api https://mcp.example.com/ \
  --header "Authorization: Bearer $MY_API_KEY"

Stdio (local processes)

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

# Examples
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@localhost:5432/mydb"

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

# Windows: wrap with cmd /c to avoid "Connection closed" errors
claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

SSE (deprecated — use HTTP instead)

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

# Example
claude mcp add --transport sse asana https://mcp.asana.com/sse

SSE (Server-Sent Events) is deprecated. Most servers that supported SSE now support streamable HTTP on the same URL. Use --transport http unless a server specifically requires SSE.

Passing Headers and Environment Variables

# Authentication headers
claude mcp add --transport http my-api https://mcp.example.com/ \
  --header "Authorization: Bearer $MY_API_KEY" \
  --header "X-Custom-Header: value"

# Environment variables (stdio servers)
claude mcp add --transport stdio my-server \
  --env API_KEY=abc123 \
  --env DEBUG=true \
  -- npx @some/mcp-server

For dynamic headers (Kerberos, short-lived tokens, internal SSO), use headersHelper in your .mcp.json — see Dynamic Headers below.

claude mcp list — Listing Servers

claude mcp list

Shows all configured MCP servers with their transport type and scope. Inside a Claude Code session, use /mcp instead — it shows live connection status, available tools, and authentication prompts.

claude mcp get — Server Details

claude mcp get <name>

# Example
claude mcp get github

Shows the full configuration for a specific server, including transport, URL/command, scope, and whether OAuth credentials are configured.

claude mcp remove — Removing a Server

claude mcp remove <name>

# Example
claude mcp remove github

claude mcp add-json — Adding from JSON

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

# HTTP server with headers
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-tool \
  '{"type":"stdio","command":"npx","args":["-y","@some/package"],"env":{"API_KEY":"abc"}}'

claude mcp add-from-claude-desktop — Importing

claude mcp add-from-claude-desktop

Interactive dialog lets you select which servers to import. Works on macOS and WSL. Imported servers keep their original names (duplicates get a numerical suffix like server_1).

Configuration Scopes

MCP servers can be configured at three levels:

Scope	Where It's Stored	Who Sees It	Set With
local (default)	~/.claude.json (keyed by project path)	You, this project only	--scope local (or omit)
project	.mcp.json in project root	Everyone on the team (commit to git)	--scope project
user	~/.claude.json (global section)	You, across all projects	--scope user

Precedence order: local > project > user > plugin-provided > claude.ai connectors. If the same server is defined in multiple scopes, the highest-precedence one wins.

# Add to project scope (shared via git)
claude mcp add --scope project --transport http stripe https://mcp.stripe.com

# Add to user scope (available everywhere)
claude mcp add --scope user --transport http github https://api.githubcopilot.com/mcp/

Tip: Use project scope for team-shared servers (commit .mcp.json to git) and user scope for personal tools you need across all projects.

The .mcp.json Config File

When you use --scope project, Claude Code writes to a .mcp.json file at your project root. You can also create or edit this file directly:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "my-db": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "postgresql://localhost/mydb"]
    },
    "private-api": {
      "type": "http",
      "url": "https://mcp.example.com/",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

Environment Variable Expansion

.mcp.json supports ${VAR} and ${VAR:-default} syntax in command, args, env, url, and headers fields:

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

Credentials stay out of version control — ${API_KEY} reads from the shell environment at connection time.

Dynamic Headers (headersHelper)

For auth schemes beyond static headers (Kerberos, short-lived tokens, internal SSO), use headersHelper to run a command that generates headers at connection time:

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "/opt/bin/get-mcp-auth-headers.sh"
    }
  }
}

The command must write a JSON object of string key-value pairs to stdout. It runs with a 10-second timeout on each connection. Claude Code sets CLAUDE_CODE_MCP_SERVER_NAME and CLAUDE_CODE_MCP_SERVER_URL in the environment so one script can serve multiple servers.

OAuth Authentication

Many remote MCP servers (GitHub, Sentry, Notion, Stripe, etc.) require OAuth rather than a static API key.

Standard OAuth Flow

1. Add the server: claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
2. Run /mcp inside a Claude Code session
3. Select the server that shows "Authentication required"
4. Complete the OAuth flow in your browser — the token is stored and refreshed automatically

Pre-Configured OAuth Credentials

If the server doesn't support Dynamic Client Registration (you'll see "Incompatible auth server"), register an OAuth app through the server's developer portal, then:

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

--client-secret prompts for masked input. Set MCP_CLIENT_SECRET as an environment variable to skip the prompt in CI.

Fixed Callback Port

Some servers require a specific redirect URI registered in advance:

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

Override OAuth Metadata Discovery

If default OAuth discovery fails, point to a specific metadata URL via .mcp.json:

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "authServerMetadataUrl": "https://auth.example.com/.well-known/openid-configuration"
      }
    }
  }
}

Tool Search

Tool Search keeps MCP context usage low by deferring tool definitions until Claude needs them. Only tool names load at session start — when Claude needs a tool, it searches for it on demand.

Tool Search is enabled by default. Configure it with the ENABLE_TOOL_SEARCH environment variable:

Value	Behavior
(unset)	All MCP tools deferred and loaded on demand (default)
true	Force-enable, including for non-first-party API hosts
auto	Load upfront if tools fit within 10% of context window, defer otherwise
auto:5	Custom threshold (5% of context window)
false	All MCP tools loaded upfront, no deferral

ENABLE_TOOL_SEARCH=auto:5 claude

This means adding more MCP servers has minimal impact on your context window. Scale to dozens of servers without bloating your session.

MCP Resources and Prompts

Resources (@ Mentions)

MCP servers can expose resources you reference with @ in your prompt:

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

Type @ to see available resources from all connected servers in the autocomplete menu.

Prompts (/ Commands)

MCP servers can expose prompts that become slash commands:

/mcp__github__list_prs
/mcp__github__pr_review 456
/mcp__jira__create_issue "Bug in login flow" high

Type / to see all available commands, including those from MCP servers.

Channels (Push Messages)

MCP servers with the claude/channel capability can push messages into your session — CI results, monitoring alerts, chat messages. Enable with --channels at startup. See Anthropic's Channels docs for details.

Output Limits

Setting	Default	What It Does
MAX_MCP_OUTPUT_TOKENS	25,000	Maximum tokens per tool output
Warning threshold	10,000	Claude Code warns above this
MCP_TIMEOUT	—	Server startup timeout (milliseconds)

export MAX_MCP_OUTPUT_TOKENS=50000
claude

MCP server authors can also set _meta["anthropic/maxResultSizeChars"] per-tool (up to 500,000 characters) to raise the limit for specific tools without requiring users to change environment variables.

Scaling Beyond a Few Servers

The native claude mcp add approach works well for a handful of servers. But if your team uses 10+ services — Stripe, HubSpot, PostgreSQL, Gmail, Sentry, PostHog, Google Search Console — you hit practical problems:

• Credential management: Each server needs its own API keys or OAuth tokens. Rotating them means updating every developer's config.
• Server maintenance: Stdio servers are local processes that crash, need updates, and consume resources. Remote servers need hosting.
• Team consistency: Getting every developer to configure the same 15 servers with the right credentials is tedious and error-prone.

MCPBundles solves this. Instead of configuring individual servers, you connect to a single authenticated endpoint that provides access to 10,000+ tools across 500+ providers — all pre-authenticated through your team's workspace.

MCPBundles CLI Setup

pip install mcpbundles
mcpbundles connect my_workspace
mcpbundles init

The init command generates a skill file that Claude Code reads automatically. From that point on, it discovers tools at runtime, searches across services, and executes calls — without per-project configuration.

How It Works

When you ask Claude Code to do something involving an external service, it:

1. Discovers tools at runtime — runs mcpbundles tools --bundle stripe or mcpbundles search "invoice" to find what's available
2. Calls individual tools — constructs shell commands like mcpbundles call search-contacts-d4f --bundle hubspot-crm -- query="acme"
3. Chains calls across services — uses mcpbundles exec to write Python that calls multiple APIs in sequence

Every tool is pre-authenticated through your workspace. Your team connects services once in the MCPBundles dashboard — OAuth, API keys, whatever the service needs — and every Claude Code session gets access automatically.

CLI vs Native MCP Config

	Native claude mcp add	MCPBundles CLI
Best for	1-3 servers, simple use	Multi-service workflows
Setup	claude mcp add per server	pip install mcpbundles && mcpbundles init
Credentials	Per-server, per-developer	Centralized in workspace
Tool limit	All tools loaded at startup (unless Tool Search is on)	Runtime discovery, no limit
Cross-service	One tool call at a time	exec chains calls in Python
Portability	Claude Code only	Same CLI in Cursor, Windsurf, Codex

Available Services

MCPBundles connects Claude Code to tools across every category a development team touches:

Category	Services
Payments & Billing	Stripe, Chargebee, ChurnKey, Recurly
CRM	HubSpot, Attio, Salesforce, Close
Databases	PostgreSQL, MySQL, Supabase
Email	Gmail, SendGrid, Campaign Monitor, Fastmail
Analytics	PostHog, Plausible, Google Analytics, FullStory
SEO	Google Search Console, Ahrefs
Dev Tools	GitHub, Linear, Sentry, LaunchDarkly
Cloud	AWS, Cloudflare, Vercel
Monitoring	Datadog, PagerDuty, FireHydrant

Browse the full catalog at mcpbundles.com/skills or search across 10,000+ tools.

Troubleshooting

Server shows "not connected" in /mcp

HTTP servers: The URL might be unreachable. Run curl -I https://your-server-url — a response (even 401) means the server is up. If it times out, the server is down or behind a firewall.

Stdio servers: The command might not be installed. Run the command directly in your terminal (e.g., npx @modelcontextprotocol/server-github) to see if it starts. Common issues: missing Node.js, npx not in PATH, or the package doesn't exist.

Tools aren't showing up

Run claude mcp get my-server to see the server status. If it's connected but shows zero tools, the server might require authentication first — run /mcp inside a session and look for an "Authenticate" option.

For stdio servers, tools are discovered at session start. If you added the server mid-session, start a new session to pick up the tools.

"Permission denied" or tools failing silently

Claude Code asks for permission before calling tools. If you denied a tool once, it won't ask again in that session. Start a new session to reset permissions, or use /permissions to review what's been granted.

Config not syncing across machines

local and user scopes store config in ~/.claude.json on each machine — they don't sync. Use --scope project to write to .mcp.json at the project root, commit it to git, and every machine gets the same config.

SSE transport errors

SSE is deprecated in favor of HTTP (streamable HTTP). If you're getting connection errors with --transport sse, switch to --transport http. Most servers that supported SSE now support streamable HTTP on the same URL.

"Connection closed" on Windows

On native Windows (not WSL), stdio servers using npx need the cmd /c wrapper:

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

OAuth redirect fails

If the browser redirect fails with a connection error after authenticating, paste the full callback URL from your browser's address bar into the URL prompt that appears in Claude Code.

MCP tool output too large

If you see "output exceeds token limit" warnings:

export MAX_MCP_OUTPUT_TOKENS=50000
claude

FAQ

How do I add an MCP server to Claude Code?

Run claude mcp add --transport http my-server https://your-server-url. For stdio servers, use claude mcp add --transport stdio my-server -- command args. Use claude mcp list to see all configured servers.

What MCP commands does Claude Code have?

claude mcp add, claude mcp list, claude mcp get, claude mcp remove, claude mcp add-json, claude mcp add-from-claude-desktop, and claude mcp serve. Inside a session, the /mcp slash command shows server status and handles OAuth authentication.

Where is the Claude Code MCP config stored?

Depends on the scope: local (default) and user both store in ~/.claude.json in your home directory — local is keyed by project path, user is global. project stores in .mcp.json at the project root, which you can commit to git for team sharing. Set with --scope when adding.

Can Claude Code use multiple MCP servers at once?

Yes. Add as many servers as you need with claude mcp add. Claude Code discovers tools from all connected servers and calls the right one based on your request. Tool Search (enabled by default) defers tool definitions so adding more servers has minimal context impact.

Does Claude Code support remote MCP servers?

Yes. Use --transport http for remote servers — no local process needed. This is the recommended transport for hosted MCP servers. The older SSE transport also works but is deprecated.

Can I share MCP server config with my team?

Yes. Use --scope project when adding a server. This saves the config to .mcp.json in the project root, which you can commit to git. All team members get the same server configuration when they clone the repo.

How do I update or change an MCP server's URL?

Remove and re-add it: claude mcp remove my-server && claude mcp add --transport http my-server https://new-url. Or edit ~/.claude.json (for local/user scope) or .mcp.json (for project scope) directly.

What's the difference between HTTP and SSE transport?

HTTP (streamable HTTP) is the current standard — it uses regular HTTP requests with optional streaming. SSE (Server-Sent Events) is the older protocol. Both work, but new servers should use HTTP and existing SSE servers are migrating. Use --transport http unless a server specifically requires SSE.

How many MCP servers can I add to Claude Code?

There's no hard limit. With Tool Search enabled (default), tool definitions are deferred and loaded on demand, so adding more servers has minimal context impact. For large numbers of services, a hub approach (one server that routes to many backends) or the MCPBundles CLI scales better than individual connections.

Does Claude Code MCP work offline?

Stdio servers that run local processes work offline — they don't need internet access. HTTP and SSE servers require network connectivity to the remote endpoint. You can mix local and remote servers in the same configuration.

What is MCP Tool Search?

Tool Search is a Claude Code feature (enabled by default) that defers MCP tool definitions until Claude needs them. Only tool names load at session start. When Claude needs a specific tool, it searches for it on demand. This keeps context usage low even with dozens of MCP servers connected.