Connecting MCP servers to Claude Code

Who this is for

This guide is for developers who already use Claude Code and want it to read an issue tracker, query a database or drive a browser instead of working from text they paste into the chat. After reading it you should be able to add a server, confirm that it is connected, call it from a session, decide where its configuration should live, and diagnose the most common failures.

What MCP adds

The Model Context Protocol (MCP) gives Claude Code tools beyond its built-in set. The tools come from MCP servers, which run as a local program on your machine or as a hosted service^[1]. The usual trigger for connecting one is noticing that you keep copying data from another tool into the chat. Once the server is connected, Claude can read and act on that system directly^[2].

Prepare

You need Claude Code and a terminal open in a project directory. An empty directory works^[1]. Local stdio servers have their own requirements. The Playwright example needs Node.js 18 or later because it runs through npx^[1].

Step 1: add a hosted server

The quickstart uses the Claude Code documentation MCP server, which is hosted and needs no authentication or special configuration, so it works as a first test^[1]. Run the command in your terminal, not inside a claude session:

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

The name claude-code-docs is yours to choose. Claude Code uses it to label the server's tools in Claude's output and to refer to the server in commands such as claude mcp remove^[1]. The confirmation says local config, which means the server is registered for you, in this project only. If you open a different project, the server is not active there^[1].

Step 2: check the status

claude mcp list

A healthy server shows ✔ Connected. ! Needs authentication means the server needs a browser sign-in or a token. ✘ Failed to connect means it did not respond, and ✘ Connection error means the attempt threw an error^[1]. Start with the status before you change anything else.

Step 3: use it in a session

Start claude and name the server in the request. The documentation's example asks Claude to look up what MCP_TIMEOUT does through the claude-code-docs server. Naming the server makes sure the answer comes from it and not from another tool. Claude Code may ask for permission the first time the server is called, and the tool call in the output carries the server name, which tells you where the answer came from^[1].

When several servers are connected, each tool call is labeled with its server name, so you can see which server produced an answer^[1]. Remove the server when you are done. Each connected server uses some of the context window, because its tool names and server instructions are loaded into every session^[1]:

claude mcp remove claude-code-docs

Choose a scope

The --scope flag decides where the configuration is stored and who sees it. local is the default: private to you, active only in the current project. user is private to you but active in all your projects. project writes to .mcp.json in the project root so the team can share it^[1]^[2].

The storage locations differ. Local servers live in ~/.claude.json under the entry for the project. Project servers live in .mcp.json. User servers live under the top-level mcpServers key of ~/.claude.json^[1]. If the same server is defined in several places, Claude Code uses the whole entry from the highest-precedence source and does not merge fields across scopes. The order is local, project, user, plugin-provided servers and then claude.ai connectors^[2].

Pick the scope by use. Use local for a server you are only trying on your own machine; it applies only to the current project. Use user for a personal tool you want in every project. Use project when the team needs the same server, and commit .mcp.json to version control so everyone shares one configuration^[1]^[2].

Share a server through .mcp.json

A .mcp.json file can be committed to the repository. The example below defines the docs server over HTTP and the Playwright server as a local stdio process:

{
  "mcpServers": {
    "claude-code-docs": {
      "type": "http",
      "url": "https://code.claude.com/docs/mcp"
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

For an HTTP server, url is the endpoint Claude Code connects to. For a stdio server, command and args are the program it starts^[1]. Claude Code reads the file at session start, so restart the session after you edit it^[1].

When a teammate first meets a project-scoped server, Claude Code asks for approval. The prompt stops a cloned repository from starting processes on your machine without your consent^[1]. Approval choices can be reset:

claude mcp reset-project-choices

This prompt cannot be shown in claude -p runs, Agent SDK sessions or cloud sessions outside a project's threads. In those settings, use disabledMcpjsonServers, --setting-sources or --strict-mcp-config instead^[2].

A local stdio server: Playwright

A stdio server is a program that Claude Code starts as a subprocess. Playwright MCP is a good example of a local program that Claude Code starts through npx^[1]:

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

The -- separator matters. Everything before it is read as Claude's own options, such as --transport, --env and --scope. Everything after it is the command that starts the server and is passed through untouched^[2]. Environment variables are passed with --env:

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

A hosted service that needs sign-in: Sentry

Some hosted services run their MCP servers behind OAuth. Adding the Sentry server looks the same as adding the docs server:

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

claude mcp list shows ! Needs authentication at this point, which is expected. Open /mcp inside a session, select sentry, choose Authenticate, and approve the connection in the browser that opens^[1]. Services that take a static token pass it at add time with --header "Authorization: Bearer <token>"^[1]^[2].

When a connection fails

Start with the status. For an HTTP server, check whether the URL answers at all:

curl -I https://mcp.sentry.dev/mcp

A 404 or 405 means the server is up, which is normal for endpoints that accept only POST requests. A 401 or 403 means the server is up and wants authentication. No response at all points to the URL or your network^[1].

A ✘ Failed to connect status means the server did not respond, while ✘ Connection error means the attempt itself threw an error. The two call for different checks, so identify which one you have first^[1]. If the server starts slowly, raise the startup limit. The default is 30 seconds, and MCP_TIMEOUT sets it in milliseconds. For example, this allows 60 seconds:

MCP_TIMEOUT=60000 claude

The limit applies to the session started by that command^[1].

Scripts and CI

In a -p run, Claude Code cannot ask about project servers, so the approval has to be handled in settings beforehand^[2]. The stream-json output reports skipped --mcp-config entries in the mcp_server_errors field of the system/init event. A CI job can read that field and fail when a server did not load^[2].