How to Connect an MCP Server to Claude

Connecting an MCP server to Claude takes about two minutes. Most of the time people lose is spent editing a configuration file that Claude Code never reads.

There are four such paths in circulation, all of them wrong, and they appear in a lot of published tutorials. The correct files are ~/.claude.json and <project>/.mcp.json. Nothing else.

Here is the whole flow, taken from the official documentation rather than from other people's blog posts.

Add a remote server

Most hosted servers connect over HTTP with a URL. Run this in your terminal, not inside a claude session:

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

Breaking that down:

• claude mcp add registers the server
• --transport http says the server is hosted at a URL rather than run as a local process
• <name> is anything you choose. Claude Code uses it to label the server's tools in output and to refer to it in later commands
• <server-url> is the endpoint from the service's documentation

You get back a confirmation naming the server and a File modified: line showing which config file was written.

Check it connected

claude mcp list

The status tells you exactly what to do next:

Inside a session, /mcp does the same job and also lets you reconnect or authenticate without leaving the conversation.

Scope: the setting people get wrong

claude mcp add defaults to local scope, meaning private to you and active only in the current project. This is the single most common source of "I added it but it is not there" confusion. You added it in a different directory.

For a server you want everywhere, add --scope user. For one your team should share, use --scope project and commit .mcp.json.

Scope is fixed at add time. To change it, remove the server and re-add it:

claude mcp remove <name> --scope local
claude mcp add --scope user --transport http <name> <server-url>

Run claude mcp get <name> to see which scope currently holds a definition.

Servers that need sign-in

Hosted services like Sentry, Linear and Notion sit behind OAuth. Add the URL first, and claude mcp list will show Needs authentication. That is expected.

Then start a session, run /mcp, select the server, press Enter and choose Authenticate. Your browser opens to the service's sign-in page. Approve there, and the status flips to connected.

Servers that use a static token instead take it at add time:

claude mcp add --transport http <name> <url> --header "Authorization: Bearer <token>"

One detail worth knowing: claude mcp list flags config values with hidden leading or trailing whitespace. Pasted tokens pick these up constantly, and it is a frequent cause of auth failures that look like something worse.

Add a local server

A local stdio server is a program Claude Code starts as a subprocess rather than a service it reaches over a URL. Use one for anything needing local resources: a browser, your filesystem, a database socket.

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

Three differences from the hosted command:

• No --transport flag, because local servers use stdio by default
• Everything after the -- separator is the command Claude Code runs to start the server
• -y tells npx to install without prompting

Omitting the -- is a common mistake. If claude mcp get <name> shows a command different from what you typed, that is usually why.

Servers running through npx need Node.js 18 or later. The first claude mcp list can show a failure while npx downloads the package, so wait and run it again. Playwright is one of the most useful first servers to connect, and we cover it alongside the rest of the developer stack in our guide to MCP servers for developers.

Writing .mcp.json by hand

Worth doing for the project-scope file, because it is checked into the repository and doubles as configuration-as-code for your team.

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

HTTP servers take a url. Stdio servers take command and args.

Claude Code reads this file at session start, so restart after editing. The first time it sees a project-scoped server it asks for approval, which exists so a repository you clone cannot launch processes on your machine without consent. If you rejected it by mistake, claude mcp reset-project-choices clears the decision.

Other surfaces

The CLI is not the only route.

• Claude Code desktop app: add servers through the Connectors UI
• Claude Desktop chat app: a separate application. To copy its servers into the CLI, run claude mcp add-from-claude-desktop on macOS or WSL
• VS Code: connect through the extension
• Claude Code on the web: reads .mcp.json from your repository
• Claude.ai: connectors added at claude.ai/customize/connectors load automatically in the CLI when you sign in with that account

That last one saves duplicated setup and few people know it.

Troubleshooting

No MCP servers configured. Usually a scope problem: you added the server in a different project. Re-add it from the current project, or use --scope user. Otherwise check you edited the right file. Claude Code does not read ~/.claude/.mcp.json, ~/.claude/config/mcp.json, ~/.claude/mcp.json or %APPDATA%\Claude\mcp.json, all of which appear in third-party guides.

Failed to connect or connection error. For HTTP servers, check the URL responds:

curl -I <server-url>

A 404 or 405 means the server is up, since many MCP endpoints answer only POST. A 401 or 403 means it is up and you need to authenticate. No response means a URL or network problem.

For stdio servers, run the configured command directly in your terminal. If it starts and waits for input, the server works and the problem is your config. If it errors, the message names what is missing.

Connection timed out. The default startup timeout is 30 seconds, and a stdio server's first run can exceed it while npx downloads. Raise it in milliseconds:

MCP_TIMEOUT=60000 claude

Connects but no tools appear. Usually a missing environment variable such as an API key. Pass it with --env KEY=value on the add command, or in the env field of the .mcp.json entry.

Changes to .mcp.json not taking effect. The file is read at session start. Restart the session.

Two things to keep in mind

Every connected server costs context. Tool names and server instructions load into every session, so servers you stopped using are quietly making the agent worse at the work you are actually doing. Remove them with claude mcp remove <name>.

Verify a server before connecting it. Servers that fetch external content expose you to prompt injection, where content in a fetched page contains instructions the agent cannot reliably distinguish from yours. Prefer official implementations from the service provider over unreviewed community forks. If you are deciding which servers are worth the context cost, start with our guides for SEO and marketing stacks.

FAQ

Where does Claude Code store MCP configuration? Two files. ~/.claude.json holds local-scope and user-scope servers, and .mcp.json in your project root holds project-scope ones. On Windows, ~/.claude.json resolves to %USERPROFILE%\.claude.json.

Why can Claude Code not see the server I added? Almost always scope. The default is local, meaning that project only. Re-add with --scope user to make it available everywhere.

What is the difference between a remote and a local server? A remote server is hosted at a URL and connects over HTTP. A local server is a program Claude Code runs on your machine over stdio. Use local for anything needing filesystem, browser or database access.

How do I share MCP servers with my team? Add with --scope project and commit the resulting .mcp.json. Teammates who clone the repo get an approval prompt, then it connects for them.

Do I need to name the server in my prompt? No. Claude selects relevant tools on its own. Naming it is only useful when you want to guarantee a specific server handles a request.

Is MCP support free? The protocol is open source and support is built into Claude Code at no extra charge. Individual servers set their own terms.

How this guide was researched

Commands, file paths, status messages and troubleshooting steps here come from Anthropic's official Claude Code documentation rather than from third-party tutorials, which is worth stating because several widely-shared guides in this category give configuration paths Claude Code does not read.

The CLI changes, so if a command behaves differently than described, check the current documentation at code.claude.com/docs before assuming your setup is broken.