Agents Index

How to Add an MCP Server to Claude Code (claude mcp add)

Updated 2026-11-18

To add an MCP server to Claude Code, run claude mcp add. For a remote server use claude mcp add --transport http <name> <url>. For a local server use claude mcp add <name> -- <command> [args...]. Then run /mcp inside Claude Code to check status and sign in if the server needs OAuth.

Add a remote server (HTTP)

HTTP is the recommended transport for remote servers. The syntax is:

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

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

If the server expects a fixed token instead of OAuth, pass a header:

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

The short flags are -t for --transport, -H for --header, -e for --env and -s for --scope.

Add a remote server (SSE)

The Claude Code docs mark SSE as deprecated. Use it only for servers that still require it:

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

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

# With an API key header
claude mcp add --transport sse private-api https://api.company.com/sse \
  --header "X-API-Key: your-key-here"

According to the docs, Claude Code v2.1.265 and later tries HTTP first and switches to SSE when the server does not accept HTTP. On those versions --transport http works for SSE endpoints too. Earlier versions need --transport sse.

Add a local server (stdio)

A stdio server is a process that Claude Code starts on your machine. Put the server's command after a -- separator:

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

# Example: Airtable server with an API key
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

Everything after -- goes to the server untouched. Options before it belong to Claude Code. This matters when the server has its own flags:

claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080

That runs python server.py --port 8080 with KEY=value in the environment. One caveat from the docs: --env accepts several KEY=value pairs, so if the server name comes directly after --env, the CLI reads the name as another pair and rejects it. Put another option, such as --transport stdio, between them.

Choose a scope

Scope decides who sees the server. The default is local.

ScopeFlagLoads inStored in
Local (default)--scope localCurrent project only, private to you~/.claude.json under the project path
Project--scope projectCurrent project, shared via version control.mcp.json in the project root
User--scope userAll your projects~/.claude.json
claude mcp add --transport http shared-server --scope project https://example.com/mcp

When the same server name is defined in several places, local wins over project, project over user. Fields are not merged across scopes.

Edit .mcp.json directly

Project-scoped servers live in .mcp.json. You can write the file by hand:

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

Claude Code asks for approval in interactive sessions before it uses a project-scoped server. This stops a cloned repository from starting a server without your consent. To reset your choices, run claude mcp reset-project-choices.

Use environment variables and keep secrets out of the file

You can reference environment variables in command, args, env, url and headers:

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

This lets you commit .mcp.json while each person keeps their own key in their shell. If a variable is unset and has no default, the server still loads with the literal ${VAR} text, and claude mcp list shows a warning.

Sign in with OAuth

Many remote servers, such as Notion, use OAuth 2.0. Inside Claude Code, run /mcp, select the server and complete the browser login. Tokens are stored and refreshed automatically. Choose "Clear authentication" in the same menu to revoke access.

From a shell, you can do the same:

claude mcp login sentry
claude mcp login sentry --no-browser   # paste-URL flow, useful over SSH
claude mcp logout sentry

Some servers need pre-registered credentials or a fixed redirect port:

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

Use --callback-port alone if the server needs a specific redirect URI (http://localhost:PORT/callback) but supports dynamic client registration.

Check that the server works

After you add a server, run claude mcp list. It shows the health of each configured server, so you can see whether Claude Code reached it. Inside a session, /mcp shows the same status and lets you authenticate. If a remote server shows as failing, test the URL in a browser or with curl before you change your config. The endpoint may be down. Agents Index probes remote endpoints daily, so the listing for a server is a quick way to see whether it is currently online.

Manage servers

# List all servers and their health
claude mcp list

# Show details for one server
claude mcp get notion

# Remove a server
claude mcp remove notion

Removing a remote server deletes its locally stored OAuth tokens but does not revoke them at the provider. To revoke where supported, run claude mcp logout <name> first.

Before you add a server

The Claude Code docs say to verify that you trust each server before connecting it. Servers that fetch external content can expose you to prompt injection. Read the MCP server security checklist before adding anything you did not write.

Not sure which server to add? Browse MCP servers that work with Claude Code, or the official registry listings. If you are new to the protocol, start with what an MCP server is.

Sources

FAQ

What is the command to add an MCP server to Claude Code?

For a remote server run claude mcp add --transport http <name> <url>. For a local server run claude mcp add <name> -- <command> [args]. Add --scope project to share it through .mcp.json.

Where does Claude Code store MCP server config?

Local and user scope servers are stored in ~/.claude.json. Project scope servers are stored in a .mcp.json file in the project root, which you can commit to version control.

How do I sign in to an OAuth MCP server in Claude Code?

Run /mcp inside Claude Code, pick the server and finish the browser login. Tokens are stored and refreshed automatically. From a shell you can also run claude mcp login <name>.

Should I use SSE or HTTP transport?

Use HTTP. The Claude Code docs mark SSE as deprecated. Newer versions try HTTP first and fall back to SSE, so --transport http also works for most SSE endpoints.

More guides