Add an MCP server to Claude Code

What an MCP server gives Claude Code

Claude Code can read and write the files in the folder you started it in. An MCP server extends that reach to things outside the folder. With a server connected, Anthropic's own examples have you asking Claude to add the feature described in a ticket and open a pull request for it, to check how a feature is being used in your analytics, to query a database for a set of records, to update a template from a design file, to draft mail, or to react to messages that arrive from somewhere else while you are away.

A server listens over one of the transports below and publishes a list of tools. Those tools appear to Claude with the server's name in front of them, which is how you can tell in the transcript which one answered. The server is a separate process or a hosted service, not a part of Claude Code, so it can be written by anyone, including you.

One thing to hold on to before adding several. A connected server takes room in the context window, because its tool names and its instructions are loaded when a session starts. Anthropic's tool search defers the full tool definitions until Claude needs them, so the cost at the start of a session stays small, but a server you never use is still not free. Removing the ones you stopped using keeps that space free.

The transports Claude Code supports

Anthropic documents four. Which one you need is decided for you by the server, not by a preference of yours: a hosted service gives you a URL, a tool that has to touch your machine gives you a command to run.

• HTTP. The one Anthropic recommends for a remote server, and the most widely supported transport for cloud services. You give Claude Code a URL.
• SSE. Deprecated. Anthropic's advice is to use HTTP where the service offers it. Claude Code tries HTTP first and falls back to SSE when a server does not accept it, on version 2.1.265 or later. Some services still answer only over SSE, which is why the transport is still there.
• stdio. A local process on your machine. This is the shape for a tool that needs direct access to your system, or for a server you wrote yourself.
• WebSocket. A persistent connection, for a remote server that pushes events to Claude without being asked. It is configured through JSON rather than the transport flag, and it has no OAuth support, so a server that only answers requests should be HTTP instead.

If a server's setup instructions were written for another client such as Claude Desktop or Cursor, they contain one of three things and each maps onto a command below: a URL, which means the server is remote; a launch command such as npx -y @example/mcp-server, which means it runs on your machine; or a JSON block, which is the configuration shape Claude Code also reads.

Add a server

Run these in your terminal, not inside a Claude Code session: you are configuring the server before there is a conversation to use it in. Anthropic notes that claude mcp add itself works the same in PowerShell and Command Prompt as it does in a Unix shell, and each of these prints an Added ... line when it has written the configuration. Anthropic's own tip for the JSON examples lower down is to make sure the JSON is properly escaped in your shell. Two notes on the confirmation line. It means the configuration was written, not that the server works, so the list command is the real check. And before version 2.1.283 the add and remove commands printed their success line even when a change to your own configuration file never reached it, which is one more reason to look at the list rather than the confirmation.

A remote HTTP server

The general form takes a name you choose and the server's URL. The name is yours; it labels the server's tools and is the name every later command uses.

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

A server that authenticates with a token takes it as a header. Anthropic's example for that is the same command with --header "Authorization: Bearer your-token" on the end.

A remote SSE server

Because Claude Code falls back from HTTP to SSE on its own, Anthropic's current advice is to try the HTTP command first even for a service that describes itself as SSE. Where you need to be explicit, or you are on a version before 2.1.265, the form is claude mcp add --transport sse asana https://mcp.asana.com/sse, and the same --header option applies.

A local stdio server

This one has two moving parts.

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

The double dash separates Claude Code's own options from the command that starts your server. Everything after it is handed to the server untouched. Leave it out and a flag belonging to the server, a --port say, is read as a Claude Code option instead; the way that shows up is claude mcp get printing a command that differs from the one you typed. Two smaller rules come with it: --env takes more than one KEY=value pair, and a server name written straight after --env is read as another pair and refused, so keep another option between the two, as the example above does. If you would rather not think about the parser at all, the JSON form further down takes the environment variables as a field.

Claude Code sets a variable called CLAUDE_PROJECT_DIR in the environment of every stdio server it starts, holding the project root, so a server can resolve paths relative to the project without depending on the working directory it happened to be launched from. That variable stays put even if you add or remove working directories during a session.

A WebSocket server

The transport flag does not accept WebSocket, so this one is configured as JSON. The type is ws, and it takes the same URL and headers fields an HTTP server does, with the application's own token in the headers.

claude mcp add-json events-server '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'

Adding from a JSON block

A lot of servers publish their setup as a block written for another client, wrapped in an mcpServers key. Claude Code wants the object inside that wrapper, not the wrapper itself, so the entry is passed to add-json on its own. Two repairs are worth knowing about. An entry that carries a URL but no type fails, because Claude Code reads an entry with no type as a local server, which is why the type has to be added. And server names are limited to letters, numbers, hyphens and the _ character, so a key holding anything else needs a new name.

A JSON entry also accepts streamable-http as an alias for http, so a configuration copied straight out of a server's documentation works without editing. And if the server is already set up in Claude Desktop, on macOS or on Windows Subsystem for Linux claude mcp add-from-claude-desktop imports its servers and asks you which ones to take.

Where the server is stored, and why that matters

Every add command lands the server at one of three scopes, and the scope is the answer to "which projects will see this, and will my team". The default is the local scope, so a command run without a scope flag is private to you and to the one project you ran it in.

• Local. Loads only in the project where you added it, and only for you. Claude Code stores it in ~/.claude.json, under the entry for that project's path, next to that project's other settings. Use it for something you are trying out.
• Project. Loads only in this project, and for everyone who clones it. It lives in a .mcp.json file at the project root, which is meant to be committed. This is the scope that shares a server with a team.
• User. Loads in every project you open on this machine, and stays private to your account. It lives in the same ~/.claude.json, under a top-level mcpServers key. Use it for a tool you reach for everywhere.

The two files are worth naming plainly, because the most common confusion on this page is a server that was added correctly and is being looked for in the wrong place. Claude Code reads ~/.claude.json and a project's .mcp.json. It does not read ~/.claude/.mcp.json, ~/.claude/config/mcp.json, ~/.claude/mcp.json, or a copy under the Windows application-data folder, whatever their names suggest. On Windows, ~/.claude.json is %USERPROFILE%\.claude.json. One more distinction that catches people: "local scope" for a server is not the same as a local settings file. The server entry is in your home directory's ~/.claude.json, while general local settings live in .claude/settings.local.json inside the project.

Changing scope is not a setting you flip. Anthropic's note is that a server's scope is fixed when you add it, so moving one means removing the entry and adding it again at the new scope, which the quickstart walks through for both cases.

When the same server name is defined in more than one place, Claude Code connects it once, using the whole definition from the highest-precedence source, and it does not merge fields between them. Local beats project, project beats user, and a server your organisation provides through managed settings ranks above all of them. Servers are matched across the three scopes by name; a plugin server or a claude.ai connector is matched by endpoint instead, and two URLs count as the same endpoint when they differ only in the case of the scheme or host, a default port such as :443, or a trailing slash.

Environment variables inside a shared config

A committed .mcp.json is the interesting case for a team, because it would otherwise mean committing a token. Claude Code expands a reference such as ${API_KEY}, or ${API_BASE_URL:-https://api.example.com} with a fallback, in a server's command, its arguments, its environment, its URL and its headers, so each person's own environment supplies the value. A reference to a variable that is not set and has no fallback still loads the server, with a warning naming the variable, and leaves the reference text unexpanded.

There is one part of this that reads like a bug the first time it happens and is deliberate. In a remote server's URL and headers, Claude Code reads a covered credential variable from your environment as empty rather than expanding it, and ignores any fallback on it. Anthropic lists three groups it covers: its own credentials, such as ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN; your cloud provider's, such as AWS_BEARER_TOKEN_BEDROCK; and other credentials your environment carries, such as HTTPS_PROXY and NPM_TOKEN. The point is to stop a project file or a plugin from sending your own credentials to a server it names. If you write Bearer ${ANTHROPIC_AUTH_TOKEN} in a header, the server receives the word Bearer with nothing after it and refuses the request, and Claude Code reports that as a failed connection. Copy the value into a variable of your own name and reference that instead.

Listing, checking and removing

Four commands cover the day-to-day, and one of them lives inside a session.

claude mcp list
claude mcp get notion
claude mcp remove notion
/mcp

claude mcp list is the one to run after any add, because it answers two questions at once: is the server there, and did Claude Code reach it. Each line carries a health word, and a failure on that line belongs to the server rather than to the command. claude mcp get narrows it to one server and shows which scope holds its definition, which is how you settle a disagreement between two projects. claude mcp remove takes the entry out, and for a remote server it also deletes the sign-in tokens and client registration stored for it. Inside a session, typing /mcp opens the panel, which is where you reconnect or sign in without leaving the conversation, see the tool count beside each connected server, and switch a server off without deleting its configuration.

A few of the statuses you can meet there are decisions rather than connection attempts, and Claude Code prints them without reaching for the server at all: a project server waiting for your approval, one you disabled for this project, and one a settings file rejects, which shows in claude mcp get rather than in the list. A server you switch off in the panel is remembered per project in ~/.claude.json, and the server stays listed, marked as disabled.

A hosted server that asks you to sign in is added the same way. After the add, the list shows it as needing authentication, and you complete the sign-in either from /mcp in a session or from your shell with claude mcp login and the server's name, which runs the same OAuth flow without opening the panel. claude mcp logout clears the stored credentials later. Both of those matter if you ever run Claude Code non-interactively: a claude -p run has no panel to sign in from, so the sign-in has to be done first, interactively.

When a server you just added will not connect

Start in one of two places: /mcp inside a session, or claude mcp list from your shell. Both tell you whether the server is even known, and the list carries the first clue when it is. Anthropic documents the symptoms below, and each one has a specific fix. This section covers the ones you meet within minutes of adding a server; the longer catalogue belongs with the rest of Claude Code's error messages.

• The list is empty. Claude Code found no servers for the folder you are in. Three causes cover it. You ran the add command from a different project, which matters because a local-scope server is tied to the project it was added in, so the fix is to add it again from here or to use the user scope. You edited a configuration file at a path Claude Code does not read, and the two files it does read are named above. Or an entry in .mcp.json is malformed: Claude Code skips that entry, loads the others, and prints a parse warning naming the offending field.
• The add command itself complained. When a server in your own or the local scope does not reach ~/.claude.json, the command says the server was not saved, names the file and the reason, and tells you to make that file writable or run the command outside the sandbox before adding the server again. A second message says the server may not have been saved, printed when the file could not be read back to confirm the change, and that one tells you to run claude mcp get with the server's name to check.
• The status says the connection failed. Run claude mcp get with the server's name: the detail sits on an issue line, with the HTTP status or error code and the server's own error text, which often names the problem, such as a rejected token. Claude Code redacts anything credential-shaped from that line and never prints the expanded URL.
• A remote server answers 404. The message names the URL's origin without its path, so run claude mcp get to see the full URL you configured, compare its path against the endpoint the service documents, and re-add the server with the right one.
• A remote server answers 401 or 403, or does not answer at all. A quick request from your own machine separates the cases. In PowerShell use curl.exe, since plain curl there is an alias for a different command. A 404 or 405 means the server is up but the path is worth checking, a 401 or 403 means it is up and needs a sign-in or a header token, and no response at all points at the URL or your network.
• A local server never starts. Run its configured command in your terminal by hand. If it starts and waits for input, the server works, and the problem is the entry Claude Code holds: run claude mcp get and compare the command it shows with what you typed, because a difference usually means the double dash was left out. If the command errors instead, its message names what is missing.
• Startup times out. The default is 30 seconds, and a local server's first run can be slow while the package downloads. Raise the limit in milliseconds by starting Claude Code as MCP_TIMEOUT=60000 claude, or in PowerShell by setting $env:MCP_TIMEOUT on the same line.
• It connects but shows no tools. The panel lists each server's tools, and an empty list usually means the server started without a variable it needs, such as an API key. Pass it with --env KEY=value, or in the entry's environment field, and check the server's own documentation for which variables it wants.
• The server is listed but described as failing. Check the warnings in the list output. A configuration value with hidden whitespace at either end is a common cause of an authentication failure after pasting a token, and Claude Code names the affected field without printing its value. Take the space out: it does not trim them, and uses the value exactly as written.
• An edit you made is not taking effect. Claude Code reads a project's .mcp.json when a session starts, so exit and start a new session after editing it. If you turned a project server down earlier, claude mcp reset-project-choices clears those answers so you are asked again.
• A project server sits waiting for approval. That is the approval prompt, and it needs an interactive session. A folder you have never trusted cannot be approved from the repository either, because a checked-in approval is ignored until you accept the trust prompt.

One of those failures has its own history, and one is still live. A remote server that answers a plain 401 has been reported as a failed connection rather than as a server asking to sign in, in issue 61376; it was filed on 22 May 2026 and closed as completed on 27 May 2026 with a fix for one cause of it, an error during the sign-in discovery being classed as a failure instead of as a server needing a sign-in. If a 401 still shows up as a failed connection, retry the sign-in from the panel before you go looking for a configuration problem. And a server name written straight after --env is still refused on the version this page was checked on: the command answers that the server's own NAME is an invalid environment variable, which reads like a complaint about your name rather than about the order of the arguments. That is issue 62332, filed on 26 May 2026 and closed on 28 June 2026, and it is why the ordering in the example above matters and why claude mcp add-json is a clean way around it.

What Anthropic warns about third-party servers

An MCP server is code from someone else, running with the reach the server was built for, and Anthropic says so plainly. Its instruction before connecting one is to verify that you trust it, and the reason it gives is that a server fetching external content can expose you to prompt injection: text arriving from outside can be written to look like an instruction to Claude.

Anthropic also describes what its own Directory is and is not. Connectors are reviewed against its listing criteria before they are added there, and that review is not a security audit: Anthropic's own words are that it does not security-audit or manage any MCP server. Its advice to anyone nervous about this is to write the server yourself, or to use one from a provider you already trust.

The second warning is about coverage rather than trust. A project's .mcp.json is the file everyone can read in a repository, but servers also arrive from your own user scope, from plugins, and from connectors on your claude.ai account, so reading that one file does not show you every server a session can load. The reason Anthropic gives for the approval prompt is narrower: it exists so a repository you clone cannot launch processes on your machine without your consent.

Where Omniscio fits

Omniscio is a desktop app for running many Claude Code sessions at once, and it has its own view for exactly the question this page ends on: which servers a session is actually starting with. The MCP Servers view manages your own custom servers, so you can add, edit and delete one without hand-editing a configuration file, and its Add MCP server dialog opens on a catalog of official remote servers drawn from the vendors' own documented endpoints. Nothing is installed until you choose it.

The part that answers a question claude mcp list cannot: Omniscio lets you choose per project and per session which servers reach a session, and a custom server is off until you switch it on. Each server resolves most-specific-first, so a session override wins over the project's default and the project's wins over your global one. A choice applies on the session's next start, because servers are loaded when the CLI launches.

It also keeps the usage. Each server shows how often it is called and which of its tools are used, so the ones that have never run are easy to spot and easy to remove. When the servers you have switched on add up to too much overhead, measured by estimated tool-definition tokens, by memory while sessions run, or by having gone unused, Omniscio raises an alert rather than leaving you to guess. The overhead alert is documented in detail if you want the thresholds.

None of that replaces the commands above, and it is not meant to, but one difference matters before you rely on them together. By default an Omniscio session loads only the servers Omniscio set up for it: it starts the CLI with a switch that ignores every server configured outside Omniscio, whichever scope. So a server you add with claude mcp add will not appear in an Omniscio session until you add it in the MCP Servers view and switch it on, or switch that setting off. It is called Stop sessions from loading unused background tools, and it is on by default, in Settings → Performance, under Advanced; the performance settings page explains it. If you are running several sessions, our guide to running multiple Claude Code sessions covers the rest of that setup.