Claude Code MCP Server Setup That Works (2026)

Most guides that promise to connect an MCP server to Claude Code skip the two things that actually break: which config file the command wrote to, and what to do when the server comes back disconnected. This walkthrough is the opposite. Every command below was checked against Anthropic's Claude Code MCP documentation on 28 August 2026, against Cursor's MCP documentation for the Cursor section, and against OpenAI's own docs for the ChatGPT question. Run claude --version first: the commands here match the 2.1.x line, and the Claude MCP server surface moves fast enough that a guide without a date on it is a guess.

How to Add an MCP Server in Claude Code

Run claude mcp add from your terminal, then run /mcp inside Claude Code to confirm the server connected. There are two shapes of the command, and which one you use depends entirely on whether the server runs as a local process or lives behind a URL.

A remote server, which is now the common case for hosted vendor servers:

claude mcp add --transport http github https://api.githubcopilot.com/mcp/

A local stdio server, which starts a process on your machine and talks to it over standard input and output:

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

Both examples come straight from Anthropic's MCP documentation. The -- separator in the stdio form is not optional and it is the single most common syntax mistake: everything after -- is handed to the server process untouched, so flags meant for the server go after it and flags meant for claude mcp add go before it.

Then verify, every time:

claude mcp list

If the server is not listed, the command wrote to a scope you are not currently in. If it is listed but not connected, the process or the URL failed. Both cases are covered below.

What Is an MCP Server, and Do I Need One?

An MCP server is a program that publishes a list of tools over the Model Context Protocol, each with a name, a description and a JSON Schema for its inputs, so any MCP client can discover and call them. Claude Code is an MCP client, which is why one command is enough to give it a new capability. The protocol itself is documented at modelcontextprotocol.io, and there is a plain-language definition in our MCP server glossary entry.

You need one when the model has to reach something outside your repository: a live API, a database, a browser, a ticketing system. You do not need one when a shell command or a script already does the job, because a well-written CLI is cheaper in tokens than a tool catalog. The short version: MCP is worth it when the same capability is needed across many sessions and many projects, and overkill when it is needed once.

Which are the best MCP servers for Claude Code is a separate question with a long answer, and this guide deliberately does not turn into a roundup. Anthropic's own docs name several remote servers you can register verbatim, including https://mcp.notion.com/mcp, https://mcp.stripe.com and https://mcp.hubspot.com/anthropic. The GitHub MCP server is published as a remote endpoint at https://api.githubcopilot.com/mcp/, which is the one most developers add first. If what you actually want is to build a server rather than connect one, our MCP server build guide covers the tool definition, the handler and the transport choice end to end.

The Three Decisions in Every Registration

Every claude mcp add command answers the same three questions, in this order. Get these right and the rest is typing.

Transport. How Claude Code talks to the server. --transport stdio (the default) spawns a local process. --transport http connects to a URL over Streamable HTTP and is the recommended choice for remote servers. --transport sse still exists but Anthropic's docs mark it deprecated in favour of HTTP. WebSocket servers exist too and are configured through claude mcp add-json with "type":"ws".

Scope. Which config file the server is written into, and therefore who gets it. --scope local (the default) is you, in this project only. --scope project writes .mcp.json at the repository root and is shared with your team through git. --scope user applies across every project on your machine.

Auth. How the server knows who you are. A stdio server usually reads an environment variable you pass with --env. A remote server takes either a static header via --header, or an interactive OAuth flow via claude mcp login.

Those three flags cover almost every server you will ever install. The rest of this guide walks each one, then shows what a failure looks like at each layer.

Scope: Which File Claude Code Actually Writes

Scope is the number-one reason a server "disappears". The flag decides which file on disk your MCP server config lands in, and each file has a different reach.

The paths are the same shape on every operating system. On macOS and Linux ~/.claude.json is exactly that. On Windows, Anthropic's docs state that ~ resolves to %USERPROFILE%, so the file is C:\Users\<you>\.claude.json. If you have set CLAUDE_CONFIG_DIR, every ~/.claude path lives under that directory instead. There is no separate Windows-only or Linux-only config location to hunt for.

Two file-shape traps are worth memorising, both documented in Anthropic's configuration debugging guide:

• .mcp.json belongs at the repository root, not inside .claude/, and its servers sit under the mcpServers key. VS Code's mcp.json uses a top-level servers key instead, so a file copied from a VS Code setup silently loads nothing.
• settings.json does not read an mcpServers key at all. Servers added there never appear. ~/.claude.json and ~/.claude/settings.json are two different files with two different jobs: the first holds app state and personal MCP servers, the second holds permissions, hooks and env.

When the same server name is defined in more than one place, Anthropic documents the load order as local scope, then project scope, then user scope, then plugin-provided servers, then claude.ai connectors.

Here is the .mcp.json shape you commit, covering both a remote and a local server:

{
  "mcpServers": {
    "acme-api": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${ACME_TOKEN}"
      }
    },
    "local-tool": {
      "type": "stdio",
      "command": "python",
      "args": ["/absolute/path/to/server.py"],
      "env": {
        "API_KEY": "${API_KEY}"
      }
    }
  }
}

Note the ${VAR} references. Anthropic's docs support ${VAR} and ${VAR:-default} expansion in this file, which is what lets you commit .mcp.json to a public repo without committing a token. Do that. A checked-in secret is a worse outcome than a broken server.

Stdio Servers: A Local Process on Your Machine

A stdio server is a command Claude Code runs. That means the command has to exist, has to be findable, and has to get its environment from somewhere.

A Python MCP server, registered from the project directory:

claude mcp add --env DB_URL=postgresql://localhost/dev --transport stdio db \
  -- python /absolute/path/to/server.py --port 8080

Three rules that come directly from Anthropic's troubleshooting table, and that account for most stdio failures:

• Use absolute paths for local scripts. A relative path in command or args resolves against the directory you launched Claude Code from, not against the location of .mcp.json. This is why a server works for you and fails for the teammate who opened a subdirectory.
• Executables on your PATH work as-is. npx, uvx and python do not need absolute paths. Everything else probably does.
• Set env per server. A stdio server inherits Claude Code's environment minus the variables it strips from subprocesses. If your server needs a key, put it in the server's own env block or pass --env, rather than assuming your shell profile reaches it.

On Windows, Anthropic's docs recommend wrapping commands in cmd /c if a direct invocation fails, and giving the full path to the executable in the command field. where claude on Windows and which claude on macOS and Linux will tell you what path to use.

Claude Code also sets CLAUDE_PROJECT_DIR in the environment of every stdio server it launches, which is the clean way for a server to find the repo it is working against without you hardcoding a path.

Remote Servers: A URL Plus a Way to Authenticate

A remote MCP server needs no local install. It needs a URL and credentials, and Claude Code gives you three ways to supply the second half.

Static header. The simplest case, for servers that accept a bearer token or an API key:

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

--header can be repeated for servers that want more than one, for example an Authorization header plus an X-API-Key.

Interactive OAuth. Most hosted vendor servers use this. Add the server without credentials, then log in:

claude mcp add --transport http notion https://mcp.notion.com/mcp
claude mcp login notion

If you are on a remote box or a Linux machine with no browser, claude mcp login notion --no-browser runs the flow without one. claude mcp logout <name> clears the stored credentials, which is the first thing to try when a previously working server starts refusing you.

Pre-configured OAuth client. For servers where you register your own client, pass the client ID and let Claude Code prompt for the secret with masked input, or supply it non-interactively through MCP_CLIENT_SECRET:

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

For anything the flags do not cover, claude mcp add-json takes the raw config object and is the only way to configure a WebSocket server:

claude mcp add-json weather-api \
  '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

Verify the Connection Before You Trust It

Never assume a successful claude mcp add means a working server. The command writes a config entry; it does not prove the server starts. There are two checks, and you want both.

From the terminal:

claude mcp list
claude mcp get github

From inside a Claude Code session, /mcp opens the panel that shows health per server, the tool count, error messages, and toggles to enable, disable or re-authenticate a server without removing it. Anthropic's docs list these statuses:

The status that fools people is ✔ Connected with zero tools. That means the process started but never returned a tool list. Anthropic's guidance is to select Reconnect from /mcp, and if the count stays at zero, run claude --debug=mcp and read the server's stderr in the debug log at ~/.claude/debug/<session-id>.txt.

Worked Example: Turn an OpenAPI Spec Into an MCP Server

Here is a pattern worth knowing regardless of which API you use: if a service publishes an OpenAPI spec, you can register it as an MCP server without writing any server code, using a generic bridge that reads the spec and emits one tool per operation.

We will use @ivotoby/openapi-mcp-server as the bridge (version 1.16.1, published 15 June 2026 per the npm registry) and biz collect as the API, because it publishes an OpenAPI 3.1 spec at /openapi.json. Substitute any other spec URL and the command is identical.

Be precise about what this is: biz collect does not host an MCP endpoint. There is no URL to point --transport http at. What it publishes is the OpenAPI 3.1 spec a bridge turns into tools, which is exactly what this recipe consumes.

# Both values are printed on the API docs page at /docs
export BIZ_BASE="<API base URL from /docs>"
export BIZ_KEY="biz_live_..."

claude mcp add --scope user biz-collect \
  --env API_BASE_URL="$BIZ_BASE" \
  --env OPENAPI_SPEC_PATH="$BIZ_BASE/openapi.json" \
  --env "API_HEADERS=Authorization:Bearer $BIZ_KEY" \
  -- npx -y @ivotoby/openapi-mcp-server

Then /mcp, confirm ✔ Connected, and read the tool list. The bridge generates one tool per operation in the spec, named after each operation's operationId, so you should see the search, job, export, account and webhook operations appear. The spec is the contract: POST /api/v1/search takes location and keywords as required fields, plus optional radius_km, result_pages, scrape_emails, scrape_mode and render_fallback, and returns businesses with name, address, phone, website, emails, socials, hours and ratings as JSON.

One flag to know before the model touches it: the search endpoint runs as an async job by default and returns a job id you then poll. Setting wait: true on the request collapses that into a single blocking call, which is what you want when a model is holding the conversation open. Anthropic's docs put the default MCP tool-output ceiling at 25,000 tokens, so keep result_pages low for interactive use and move large jobs to the async path with a webhook.

Once the tool is connected, the interesting work starts in the prompt rather than the config. Our guide on using Claude for lead generation walks through what to ask for, how to qualify what comes back, and where to hand off.

Cursor MCP Server Setup: Same JSON, Different File

A Cursor MCP server uses the same mcpServers JSON shape as Claude Code, in a different file. Per Cursor's own documentation, project scope is .cursor/mcp.json in your project directory and global scope is ~/.cursor/mcp.json in your home directory, and those paths are the same on macOS, Windows and Linux.

{
  "mcpServers": {
    "biz-collect": {
      "command": "npx",
      "args": ["-y", "@ivotoby/openapi-mcp-server"],
      "env": {
        "API_BASE_URL": "${env:BIZ_BASE}",
        "OPENAPI_SPEC_PATH": "${env:BIZ_BASE}/openapi.json",
        "API_HEADERS": "Authorization:Bearer ${env:BIZ_KEY}"
      }
    }
  }
}

Two differences from Claude Code that will bite you if you assume symmetry. Cursor's environment-variable syntax is ${env:VAR}, not ${VAR}. And Cursor has no claude mcp add equivalent CLI, so you edit the file directly, toggle servers in the Customize sidebar, and read failures in the Output panel under MCP Logs. A remote server in Cursor is the same object with url and headers instead of command and args.

Claude Desktop MCP Server Config, and MCP in ChatGPT

A Claude Desktop MCP server is configured in a different application and a different file from Claude Code. Per the Model Context Protocol documentation, it lives at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and %APPDATA%\Claude\claude_desktop_config.json on Windows, and the same docs note Claude Desktop is available for macOS and Windows. On Linux, Claude Code is the supported path. Its MCP logs are at ~/Library/Logs/Claude and %APPDATA%\Claude\logs, with one mcp-server-SERVERNAME.log per server carrying that server's stderr. If you already have servers configured there, claude mcp add-from-claude-desktop imports them.

Can I use MCP with ChatGPT? Yes, with real limits. OpenAI's developer-mode documentation states it is available to Pro, Plus, Business, Enterprise and Education accounts on the web, enabled at Settings, then Security and login, then Developer mode. The supported MCP protocols are listed as SSE and streaming HTTP, which means ChatGPT connects to remote servers only: there is no local stdio path the way there is in Claude Code, so a server that runs as npx on your laptop cannot be attached without hosting it somewhere first. Business and Enterprise workspaces additionally need an admin to enable developer mode before it appears.

Troubleshooting: Five Failures and Their Fixes

This is the part the vendor tutorials skip. Each of these is a real failure mode with a documented fix.

1. The server shows as disconnected

Run /mcp and read the actual status rather than guessing. If it is ✘ Failed to connect, the usual cause for a stdio server is a relative path in command or args, which resolves against the directory Claude Code was launched from. Make it absolute. If it shows connected with zero tools, hit Reconnect in /mcp, then run claude --debug=mcp and read the stderr in ~/.claude/debug/<session-id>.txt. If the server never starts within the startup window, raise it: MCP_TIMEOUT=10000 claude.

2. You edited the config in the wrong place

Symptoms: the JSON is obviously right and nothing loads. Check, in this order. Is the file .mcp.json at the repository root rather than inside .claude/? Are the servers under mcpServers rather than a top-level servers key? Did you put mcpServers in settings.json, which does not read that key at all? Is the server defined in a nearer scope that is shadowing the one you edited? And for a project-scoped server: .mcp.json entries need a one-time approval, so if you dismissed that prompt the server stays disabled until you approve it from /mcp. claude mcp reset-project-choices clears those approvals and asks again.

To rule out your whole configuration at once, claude --safe-mode starts a session with every customization disabled, including MCP servers. If the problem vanishes there, something in your config is the cause.

3. The command is not on PATH

✘ Failed to connect on a stdio server with an ENOENT in the log means the executable was not found. Executables on your PATH such as npx, uvx and python work as bare names; everything else should be an absolute path. On Windows, wrap the command in cmd /c and give the full path to the executable. Verify what Claude Code itself resolved to with where claude on Windows or which claude elsewhere. And remember that a stdio server does not inherit your interactive shell profile: if it needs a variable, it goes in that server's env block or behind --env, not in .zshrc.

4. The remote server rejects your auth

! Needs authentication means the URL is reachable and your credentials are not accepted. For an OAuth server, claude mcp logout <name> then claude mcp login <name> re-runs the flow with a clean slate, and --no-browser handles machines with no display. For a token server, confirm the header is the exact string the vendor documents, including the Bearer prefix, and check that the token has not expired or lost a scope. If you would rather not store a static token at all, Claude Code supports a headersHelper script in the config that prints a JSON object of headers to stdout and is re-run with a 10-second timeout, which is the clean way to hold short-lived credentials.

5. Tool definitions are eating your context

Every connected server injects its tool definitions into the context window before you type anything, and a handful of chatty servers can cost more context than the code you are working on. Run /context to see the actual MCP tool footprint for the session. Three levers, in order of how blunt they are: disable the servers you are not using today from the /mcp panel, which keeps the config and drops the tokens; raise or lower MAX_MCP_OUTPUT_TOKENS, which defaults to 25,000, when results rather than definitions are the problem; and if the server is an OpenAPI bridge, use its own filtering. The bridge in this guide takes TOOLS_MODE=dynamic to load only meta-tools instead of one tool per endpoint, plus --exclude-tag to drop whole groups of operations. A spec with sixty endpoints should not become sixty always-loaded tools.

Ship It

The setup that survives contact with a real project comes down to three decisions made deliberately rather than by default: the transport that matches how the server runs, the scope that matches who should get it, and an auth method that does not put a token in git. Everything after that is verification, and verification is one command: /mcp, ✔ Connected, non-zero tool count.

If you want a live data tool in that list rather than another wrapper around your own repo, biz collect is an async REST API that turns a city plus keywords into structured local-business JSON, with an OpenAPI 3.1 spec designed to be read by exactly the kind of bridge shown above, a wait: true synchronous mode so one tool call returns results, and webhooks for the jobs too big to wait on. It is free to start with 200 signup credits and no credit card, which is enough to register the server, watch Claude Code call it, and see the JSON come back.

Wire it up, then let it run. Read the API docs.

FAQ: Claude Code MCP Servers