Configure MCP Servers in Claude Code

Claude Code connects to external tools, databases, and APIs through the Model Context Protocol (MCP), an open standard for AI-tool integrations. You configure servers two ways: the claude mcp CLI family (run in your terminal) for adding and managing servers, and the in-session /mcp slash command for viewing connected servers and completing OAuth authentication.

Note: /mcp is a built-in slash command (it lists servers, shows tool counts, and runs the OAuth login flow). The claude mcp ... commands are run in your terminal, not inside a Claude Code prompt.

Add a server with claude mcp add

The claude mcp add command supports three transports via --transport: http, sse, and stdio.

Remote HTTP server:

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

# Example
claude mcp add --transport http notion https://mcp.notion.com/mcp

Remote HTTP server with a custom header (for static-token auth):

claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

Remote SSE server:

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

Local stdio server. For stdio servers, everything after -- is the command Claude runs to launch the server:

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

# Example with an environment variable
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

The -- (double dash) separates Claude's own options (--transport, --env, --scope) from the command and args passed to the server untouched. --env accepts multiple KEY=value pairs; place at least one other option between --env and the server name so the CLI does not read the name as another env pair.

Add a server from JSON

claude mcp add-json takes a full server definition, which is useful for copying a config straight from a server's docs:

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

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

Choose a scope with --scope

The --scope flag controls where the configuration is stored and who can see it. Valid values are local, project, and user:

# Local (default) — private to you in this project
claude mcp add --transport http stripe https://mcp.stripe.com

# Project — shared with the team via .mcp.json
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

# User — available across all your projects
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

When the same server name is defined at multiple scopes, precedence is local, then project, then user (the highest-precedence entry wins; fields are not merged).

The .mcp.json project file

Adding a server with --scope project creates or updates .mcp.json at the project root. Commit it so teammates inherit the same servers. The format is:

{
  "mcpServers": {
    "paypal": {
      "type": "http",
      "url": "https://mcp.paypal.com/mcp"
    },
    "shared-stdio-server": {
      "command": "/path/to/server",
      "args": [],
      "env": {}
    }
  }
}

For security, Claude Code prompts for approval before using project-scoped servers from .mcp.json. Pending servers show up as ⏸ Pending approval in claude mcp list; review and approve them by running claude interactively. To reset approvals, run claude mcp reset-project-choices.

Environment variable expansion

.mcp.json supports ${VAR} and ${VAR:-default} expansion in command, args, env, url, and headers. This lets a committed config reference machine-specific paths and secrets without hardcoding them:

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

If a referenced variable is unset and has no default, Claude Code fails to parse the config. Keep secrets out of version control by referencing environment variables rather than pasting tokens into .mcp.json.

Manage servers

# List configured servers
claude mcp list

# Show details for one server
claude mcp get github

# Remove a server
claude mcp remove github

Authenticate remote servers with /mcp

Run /mcp inside a Claude Code session to see connected servers, the tool count next to each one, and to authenticate. Claude Code flags a remote server as needing authentication when it responds with 401 Unauthorized or 403 Forbidden; you then complete the OAuth 2.0 browser login from the /mcp menu.

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

# 2. In a Claude Code session, open the MCP panel and follow the OAuth flow
/mcp

# 3. Use the server
What are the most common errors in the last 24 hours?

Use the /mcp menu's "Clear authentication" option to revoke stored OAuth access. You can verify OAuth credentials are configured for a server with claude mcp get <name>.

When to use which

• Use claude mcp add --transport http|sse <url> for remote/hosted servers (these support OAuth).
• Use claude mcp add --transport stdio <name> -- <command> for local servers you launch as a subprocess.
• Use --scope project and commit .mcp.json when the whole team should get the same servers; use the default local scope (or --scope user) for personal setups.
• Use /mcp to authenticate remote servers and to check that a server is connected and exposing tools.

For a step-by-step first-server walkthrough, see the official MCP documentation linked from this page.

• Source repositorygithub.com 2026-07-18T07:31:52+00:00
• Documentationcode.claude.com