How to add MCP servers to Claude Code: commands, scopes, OAuth

Claude Code can use tools from any Model Context Protocol (MCP) server: an issue tracker, a database, error monitoring or your own internal API. You add a server with one claude mcp add command, choose who else gets it with a scope, and sign in with /mcp if the server uses OAuth.

What an MCP server does in Claude Code

An MCP server gives Claude Code tools it can call directly, so it reads and acts on another system instead of working from what you paste into the chat. Remote servers run somewhere else and you connect to a URL; local stdio servers run as a process on your machine.

Add a remote HTTP server

Use --transport http with a name and the server’s URL. The Claude Code docs call HTTP the recommended option for remote servers.

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

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

--transport sse still exists, but the docs mark the SSE transport as deprecated: use HTTP when a server offers it.

Add a local stdio server

Put the server’s start command after --. Everything before it is for Claude Code (--transport, --env, --scope); everything after it is passed to the server untouched.

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

--env accepts several KEY=value pairs, so keep another option such as --transport stdio between the last pair and the server name; otherwise the CLI reads the name as another pair.

Choose a scope

The scope decides which projects load the server and whether teammates get it. Add --scope local, --scope project or --scope user to the command; local is the default.

Scope	Loads in	Shared with team	Stored in
Local (default)	Current project only	No	~/.claude.json
Project	Current project only	Yes, through version control	.mcp.json in the project root
User	All your projects	No	~/.claude.json

A project-scoped server is written to .mcp.json:

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

Keep the type field. Claude Code treats an entry with a url but no type as a stdio server and skips it with a configuration error. To add a server from JSON you already have, use claude mcp add-json <name> '<json>'. If the same name exists in several scopes, the local definition wins over project, and project over user.

Sign in with OAuth

Run /mcp inside Claude Code, pick the server and sign in through your browser. Claude Code marks a remote server as needing authentication when it answers 401 or 403, and stores and refreshes the tokens for you.

From the shell, the same flow is one command:

claude mcp login <name>

Add --no-browser to get a URL to open yourself, which also works over SSH. claude mcp logout <name> clears the stored credentials, and Clear authentication in the /mcp menu revokes access.

Check that the server works

claude mcp list shows every server with a health status, and claude mcp get <name> shows the details of one.

claude mcp list
claude mcp get <name>

The statuses you will see most:

Status	Meaning
✔ Connected	Ready; its tools are available
! Needs authentication	Sign in with /mcp or claude mcp login
✘ Failed to connect	The detail after it shows the HTTP status or error
⏸ Pending approval	A .mcp.json server you have not approved yet

Inside a session, /mcp shows the tool count next to each connected server.

Troubleshooting

Start from the status line, then check these common causes:

• ✘ Failed to connect with a 401. claude mcp add saves the configuration without checking credentials, so a placeholder token is accepted and fails later. Fix the header or sign in again.
• A local server is slow to start. Raise the startup timeout with MCP_TIMEOUT, for example MCP_TIMEOUT=10000 claude for 10 seconds.
• Tool output gets cut off. Claude Code warns above 10,000 tokens of MCP output and limits it to 25,000 by default; set MAX_MCP_OUTPUT_TOKENS to change the limit.
• A teammate’s project server never loads. It is waiting for approval. They need to run claude in the project and approve it.
• A conflict warning for one name in two scopes. Remove the extra definition with claude mcp remove <name> --scope <scope>.

Example: add Hallway Test to Claude Code

Hallway Test is a remote HTTP server with OAuth, so one command adds it and no token is needed. It lets Claude Code send a flow it just built to a real person from our in-house team, who runs it while thinking aloud; see what the usability testing MCP does.

claude mcp add --transport http hallwaytest https://mcp.hallwaytest.ai/mcp

Add --scope user before the name if you want it in every project. Then run /mcp, choose hallwaytest, sign in with Google and approve the connection. Claude Code gets the Hallway Test tools, among them create_usability_task, and slash commands such as /mcp__hallwaytest__test-usability.

A new account can connect right away, but the first request to dispatch a test answers with a link to book the free pilot call. After the 30-minute call we activate the account, with no need to reconnect, and results come back within 24 hours. Claude Code then pulls the recording and transcript through the tools and does the analysis itself. After public launch a test costs $29. For the Claude apps, the setup with a custom connector is on Connect Hallway Test to Claude.

Sources

1. Connect Claude Code to tools via MCP, Claude Code documentation