How to Set Up MCP Servers in Claude Code (November 2026)

MCP lets Claude Code use tools supplied by another program or hosted service. Instead of copying an issue or a database result into chat, you can give Claude access to a server that exposes the relevant tools. What Claude can read or change depends on that server and the permissions you grant.

For a first connection, use the documentation server in Claude Code's official quickstart. It needs no separate account or token, so you can learn the setup flow before adding authentication. We have not run these examples ourselves.

1. Add one server, then verify it

Install Claude Code and complete its own sign-in first. Open a terminal in the project where you want the server available; an empty directory also works. Run this in the terminal, not inside an existing claude conversation:

claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp

The name claude-code-docs is an identifier you choose. Claude Code uses it to label tools and to find the entry when you inspect or remove it. Here, --transport http says to connect to a hosted URL rather than launch a local program.

An Added ... confirmation and a File modified: line mean the configuration was saved. They do not prove that a connection or credential works. Check separately:

claude mcp list
claude mcp get claude-code-docs

For the documentation server, the expected status is ✔ Connected. Next, start claude and ask: Use the claude-code-docs server to look up what MCP_TIMEOUT does. Naming the server makes the intended tool explicit. Review any tool permission prompt, then approve if appropriate. Look for the server name beside the tool call, rather than treating a plausible answer as proof that MCP was used.

You can remove the experiment with claude mcp remove claude-code-docs. Unused servers occupy context through their tool names and instructions, so keeping only useful ones also avoids unnecessary context overhead.

2. Match the transport to the server

Start from the server provider's setup instructions. A URL and a launch command are not interchangeable.

HTTP is the recommended remote transport. In JSON, "type": "http" and its "streamable-http" alias are accepted. A remote entry with a url but no type is not enough: without type, Claude Code interprets an entry as stdio and skips the malformed URL entry.

SSE is deprecated, not unusable. On Claude Code v2.1.265 or later, --transport http tries HTTP first and switches to SSE if the server does not accept it. Earlier versions, or an intentional direct SSE connection, use --transport sse. Prefer HTTP when the provider offers it.

For a local example, the quickstart uses Playwright, requiring Node.js 18 or later:

claude mcp add playwright -- npx -y @playwright/mcp@latest

Everything after -- belongs to the server's launch command. Omit the separator and Claude Code may interpret the server's flags as its own. The first status check can fail while npx downloads the package; check again after that completes. Choose packages you trust: this starts code on your machine.

WebSocket does not support OAuth, and claude mcp add --transport does not accept ws. Use .mcp.json or claude mcp add-json with "type": "ws". Authentication is through headers, including a supported headersHelper for dynamically generated headers. Do not choose WebSocket just because a service is remote; HTTP is simpler for request-response tools.

3. Choose who gets the configuration

Transport determines how the server runs. Scope determines where the definition is available. A local-scoped HTTP server is still remote; “local” here does not mean stdio.

Use local scope for an experiment, project scope for a shared team setup, and user scope for a personal tool you want everywhere. MCP local scope is not .claude/settings.local.json. On Windows, ~/.claude.json means %USERPROFILE%\.claude.json; setting CLAUDE_CONFIG_DIR moves it into that configuration directory.

To move the first example to user scope, remove its local definition before re-adding:

claude mcp remove claude-code-docs --scope local
claude mcp add --scope user --transport http claude-code-docs https://code.claude.com/docs/mcp

For team sharing, use --scope project instead of --scope user. If names collide, local beats project, which beats user; the whole winning definition is used, not a merge of fields. Other sources rank below those three, while organization-provided managedMcpServers ranks above them on v2.1.259 or later. Check the active definition before changing a URL that appears to be ignored.

4. Use the right JSON file

A minimal project-root .mcp.json can contain the same documentation server:

{
  "mcpServers": {
    "claude-code-docs": {
      "type": "http",
      "url": "https://code.claude.com/docs/mcp"
    }
  }
}

Keep the top-level key mcpServers, not servers, and do not put this file under .claude/. Adding mcpServers to settings.json also does not work. Restart the session after editing .mcp.json, because Claude Code reads it at startup.

Interactive sessions ask you to approve project-scoped servers. Review the URL or command before approving a repository's configuration. If you dismissed the prompt, open /mcp; use claude mcp reset-project-choices if you need to reset earlier choices. Non-interactive claude -p runs cannot show this prompt and load project servers without asking, so inspect shared configuration before automating a run.

When adapting another client's JSON for claude mcp add-json, pass a single server definition from inside mcpServers, not the outer wrapper. Server names may contain letters, numbers, hyphens, and underscores.

5. Separate OAuth from token headers

For a hosted service using OAuth, add its documented MCP URL, then inspect the status. ! Needs authentication can be the correct next step rather than a broken setup. In a session, open /mcp, select the server, and choose Authenticate. Alternatively, run claude mcp login <name> from an interactive terminal, replacing <name> with your configured server name.

If the browser does not open, use the authorization URL shown by Claude Code. If the browser callback fails, paste the full callback URL into Claude Code's own prompt. Do not share that URL in a ticket or chat. Complete sign-in before starting a claude -p run, which has no /mcp panel for OAuth.

A service using a static token instead takes an authorization header. This example uses a placeholder address, name, and token; replace them with the provider's values, not literal example credentials:

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

Do not commit live tokens to shared configuration. JSON supports environment references such as "Authorization": "Bearer ${API_KEY}", where API_KEY is your own server-specific variable. Remove accidental spaces or newlines around a pasted token.

If you configure an Authorization header and the server rejects it with 401 or 403, Claude Code reports a failed connection instead of falling back to OAuth. Fix the configured credential, or remove the header if you intend to use the service's OAuth flow. Re-running browser login does not repair a rejected manually configured token.

6. Diagnose the symptom before changing settings

Begin with claude mcp list, then claude mcp get <name>, or use /mcp inside a session.

• No servers configured: confirm you are in the project where you added the local-scoped entry. Check the configuration path and JSON syntax. A malformed entry can be skipped while other entries still load.
• Pending approval: approve the project server through an interactive session after reviewing it.
• Failed to connect: read the HTTP status or error detail. Check the full URL in get, including its MCP endpoint path. A reachable website is not necessarily the correct MCP endpoint.
• Connection error: this status has no appended detail. Check network reachability for HTTP, or the launch command for stdio.
• Connected but no tools: inspect the tool list in /mcp, check required environment variables, then select Reconnect. If tools remain absent, claude --debug=mcp enables logs; inspect the server's stderr under ~/.claude/debug/ without sharing secrets from the logs.

For remote reachability, the quickstart suggests curl -I <url>; PowerShell users should use curl.exe. A 404 or 405 can still show that the host responded, particularly when an endpoint expects POST, but it does not prove the MCP path or protocol is correct. A 401 or 403 points toward authentication. No response suggests checking the URL and network.

For stdio, compare the configured command with the provider's instructions and check the required runtime. Relative paths in command or args resolve from the directory where Claude Code was launched, not from .mcp.json; use absolute paths for local scripts. Also check whether you started with --safe-mode, which disables MCP servers.

The default startup timeout is 30 seconds. A first npx download may take longer. To allow 60 seconds in Bash or Zsh, use MCP_TIMEOUT=60000 claude; in PowerShell, use $env:MCP_TIMEOUT = "60000"; claude. The reference's MCP_TIMEOUT=10000 claude is a 10-second example, not the default. On versions before v2.1.299, some live HTTP servers timed out regardless of this setting; update Claude Code if that matches your case.

Keep the first setup small

Trust the server before connecting it, especially if it retrieves outside content that could contain prompt injection. Start with one useful tool call and inspect its permissions before granting broader access. MCP setup also does not remove your Claude Code usage limits.

Once basic access works, MCP Tasks and mid-job prompts cover a different question: what happens during a longer-running job, not how to register your first server.