Configuring MCP — Claude Code & the API

One protocol, a client and a server

An MCP server exposes tools (callable functions), resources (readable data), and prompts (slash commands) over a transport. An MCP client — Claude Code, or the Anthropic API's connector — connects and surfaces those capabilities to the model.

Transports

Adding servers with claude mcp add

One command per transport. The server's name is how you reference it everywhere else.

# claude mcp add --transport http <name> <url>
claude mcp add --transport http notion https://mcp.notion.com/mcp

# with a bearer token header
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_PAT"

# claude mcp add [opts] <name> -- <command> [args...]   (everything after -- runs the server)
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

# the -- is REQUIRED: it separates Claude's flags from the server's own args

# deprecated — use HTTP where available
claude mcp add --transport sse asana https://mcp.asana.com/sse \
  --header "X-API-Key: your-key-here"

Managing servers

claude mcp list                 # all configured servers + status
claude mcp get github           # details for one server
claude mcp remove github        # remove it
claude mcp add-json db '{"type":"stdio","command":"/path","args":[],"env":{}}'
claude mcp add-from-claude-desktop   # import from Claude Desktop (macOS/WSL)
# inside a session:  /mcp   # status, OAuth login, clear auth

Where the config lives — and who shares it

The --scope flag decides which projects a server loads in and whether it's shared.

Precedence when the same name is defined twice (whole entry wins, fields are not merged): local → project → user → plugins → claude.ai connectors.

The .mcp.json format (project scope)

{
  "mcpServers": {
    "shared-server": {
      "command": "/path/to/server",
      "args": [],
      "env": {}
    }
  }
}

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

// ${VAR} and ${VAR:-default} expand in command, args, env, url, headers
{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": { "Authorization": "Bearer ${API_KEY}" }
    }
  }
}

Claude Code server config generator

Fill this in and copy the matching claude mcp add command and the .mcp.json entry.

Three ways servers authenticate in Claude Code

• Static header / token — --header "Authorization: Bearer ...", or headers in .mcp.json. Best for PAT-style APIs (e.g. GitHub).
• Environment variables — --env KEY=value for stdio servers (passed into the spawned process), or env in .mcp.json.
• OAuth 2.0 — add the server, then run /mcp and complete the browser flow. Claude Code triggers this automatically when a server returns 401/403; tokens are stored securely and refreshed for you.

OAuth knobs (when auto-setup isn't enough)

# fixed callback port (server pre-registers a redirect URI)
claude mcp add --transport http --callback-port 8080 my-server https://mcp.example.com/mcp

# pre-configured OAuth client (no dynamic registration); --client-secret prompts masked
claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

Connecting MCP servers from the Messages API

The MCP connector lets a raw API call reach a remote MCP server with no separate MCP client. Two pieces: mcp_servers (the connection) and an mcp_toolset in tools (which tools to enable).

Server + toolset shape

MCP on a Managed Agent — server on the agent, auth in a vault

Managed Agents split MCP config across two objects so secrets stay out of the reusable agent definition:

• The agent declares servers with {type, name, url} only — no auth — plus an mcp_toolset to grant access.
• A vault holds the credential (mcp_oauth with auto-refresh, or static_bearer), matched to the server by URL. Attach it at session create via vault_ids.

# 1. Agent declares the server (no auth here)
agent = client.beta.agents.create(
    name="MCP Agent", model="claude-opus-4-8",
    mcp_servers=[{"type": "url", "name": "linear", "url": "https://mcp.linear.app/mcp"}],
    tools=[{"type": "agent_toolset_20260401"},
           {"type": "mcp_toolset", "mcp_server_name": "linear"}],
)

# 2. Vault holds the credential, attached to the session by id
session = client.beta.sessions.create(
    agent=agent.id, environment_id=env.id,
    vault_ids=["vlt_..."],   # contains the Linear MCP OAuth credential
)

Things that bite

Back to API & Claude Code config