Search

Home › Learn › Add an MCP server to Claude Code

Add an MCP server to Claude Code

Updated 2026-09-23

Claude Code configures MCP servers with the claude mcp command family. The same server can be added by transport (HTTP, SSE, stdio) or from a JSON block, and stored at one of three scopes. Everything below is taken from the Claude Code MCP documentation as of 2026-09-23; flags and file paths change between releases, so check that page if a command is rejected.

Remote HTTP server

HTTP is the recommended transport for remote servers.

# Basic syntax
claude mcp add --transport http <name> <url>

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

--header can be repeated and takes a literal Name: value string. If you write the entry as JSON instead, "type": "http" is required; the docs note that streamable-http is accepted as an alias for http so snippets copied from server READMEs work unmodified. A JSON entry that has a url but no type is treated as a stdio entry and skipped with an error.

Remote SSE server

The docs mark SSE as deprecated and say to use HTTP where available. Some services still expose only an SSE endpoint. Recent versions (v2.1.265+) let you add those with --transport http and fall back to SSE automatically; otherwise:

claude mcp add --transport sse <name> <url>
claude mcp add --transport sse private-api https://api.company.com/sse \
  --header "X-API-Key: your-key-here"

Local stdio server

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

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

The -- separator matters: everything after it is passed to the server untouched, so the server's own flags (for example --port 8080) are not parsed as Claude Code options. --env KEY=value can be repeated; the docs warn that if the server name comes directly after --env, the CLI reads the name as another pair, so put another option such as --transport stdio between them.

Claude Code sets CLAUDE_PROJECT_DIR in the spawned server's environment, and answers the MCP roots/list request with the session's working directories.

From a JSON block

Many servers document an mcpServers block written for another client. Pass the inner object (not the wrapper) to add-json:

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

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"}}'

Two repairs are sometimes needed: add a type to any entry that has a url, and rename keys that contain characters other than letters, numbers, hyphens and underscores. WebSocket servers ("type": "ws") can be added this way as well; --transport does not accept ws.

Managing servers

claude mcp list          # all configured servers with connection status
claude mcp get <name>    # details for one server
claude mcp remove <name> # remove it (also deletes stored OAuth tokens)

Inside a session, /mcp shows status, lets you toggle servers off without removing them, and runs OAuth sign-in.

Scopes

ScopeLoads inSharedStored in
Local (default)current projectno~/.claude.json, under the project path
Projectcurrent projectyes, via version control.mcp.json in the project root
Userall your projectsno~/.claude.json

Pick a scope with --scope local, --scope project or --scope user:

claude mcp add --transport http shared-server --scope project https://example.com/mcp
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

A project-scoped add writes a standard file you can commit:

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

Claude Code prompts for approval in interactive sessions before using servers from a project's .mcp.json; claude mcp reset-project-choices clears those decisions. When the same name is defined in more than one scope, the highest-precedence definition wins whole: local, then project, then user, then plugin-provided servers, then claude.ai connectors. Fields are not merged across scopes.

Environment variables in .mcp.json

.mcp.json supports ${VAR} and ${VAR:-default} in command, args, env, url and headers, which is how a team shares one file without committing keys:

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

One safety rule to know: in a remote server's url and headers, Claude Code reads its own and your cloud provider's credential variables (the docs name ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, AWS_BEARER_TOKEN_BEDROCK, HTTPS_PROXY, NPM_TOKEN among others) as empty rather than expanding them. This stops a repository's .mcp.json from sending your Claude credentials to a third-party server. A name outside that set, such as API_KEY, expands normally.

Authentication

Claude Code supports OAuth 2.0 for remote servers. Add the server, then run /mcp inside a session, or from the shell:

claude mcp login <name>
claude mcp logout <name>

For servers that require a pre-registered redirect URI, --callback-port fixes the port to match http://localhost:PORT/callback, and --client-id with --client-secret supplies pre-configured OAuth credentials. For non-OAuth schemes such as short-lived internal tokens, a headersHelper command in the JSON config can generate headers at connection time; Claude Code runs it only after you have trusted the folder that declares it.

Where mcpnav fits

Each server page on mcpnav has a Connect block that turns the Registry's packages and remotes data into the matching claude mcp add line and a .mcp.json snippet, with <YOUR_VALUE> placeholders for every header and environment variable.

Sources

Sources