How to add an MCP server to Claude Code, in one command

An MCP server gives Claude Code tools it did not have: read current library docs, query a database, open pull requests, publish a changelog. Claude Code adds one with a single terminal command, claude mcp add, and there is no config file to edit unless you want one. This guide covers that command for local and remote servers, the three scopes, environment variables, and how to read a failed connection. Everything here is taken from Anthropic’s Claude Code MCP documentation, read on 23 September 2026.

Remote servers: --transport http

A remote server is already running at a URL. The basic form is the name first, then the URL:

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

If the server wants a token, pass it as a header:

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

HTTP is the transport Anthropic recommends for remote servers. Some services still expose only an older SSE endpoint; the docs say Claude Code v2.1.265 and later try HTTP first and switch to SSE when the server does not accept it, and --transport sse forces it on any version. A server that signs you in with OAuth instead of a header is authenticated from the /mcp panel inside a session.

Local servers: everything after --

A local server is a program Claude Code starts on your machine and talks to over standard input and output. The form for it puts the command after a double dash:

claude mcp add [options] <name> -- <command> [args...]

The -- matters. Everything before it is for Claude Code (--transport, --env, --scope); everything after it is passed to the server untouched. Without it, Claude Code tries to read the server’s own flags, such as -y or --port, as its own options.

Keys go in with --env KEY=value, and you can repeat it. One trap from the docs: if the server name comes straight after --env, the name is read as another KEY=value pair and rejected, so put another option such as --transport stdio between them:

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

The short forms are -t for --transport, -H for --header, -e for --env and -s for --scope.

Scopes: who gets the server

Every command above writes to one of three scopes:

Scope	Loads in	Shared with the team	Stored in
local (default)	this project only	no	~/.claude.json
project	this project only	yes, through git	.mcp.json in the project root
user	all your projects	no	~/.claude.json

Local is right for a server with your personal key. User is for tools you want everywhere, such as a docs server. Project is for a server the whole team should have: Claude Code writes it to .mcp.json, you commit the file, and each teammate is asked to approve it the first time they start Claude Code in that folder. When the same name exists in more than one scope, local wins over project, and project over user; the entries are not merged.

Keep keys out of .mcp.json

A committed .mcp.json must not contain a key. Claude Code expands environment variables in command, args, env, url and headers, with ${VAR} or ${VAR:-default}:

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

Each developer sets API_KEY in their own shell. Two details from the docs: Claude Code’s own credentials such as ANTHROPIC_API_KEY always read as empty in a remote server’s url and headers, so it cannot be sent to a server by mistake (copy the value into a variable with your own name if a server really needs it). And a JSON entry with a url must have a type (http, sse or ws), because an entry without one is read as a local server.

If a server’s README only gives JSON written for another client, claude mcp add-json <name> '<json>' takes the object inside mcpServers, as the docs show.

Worked example: Context7

Context7 is a public MCP server from Upstash that fetches current documentation for a library into the agent’s context. It makes a good first server because it has a remote and a local form, and you can try it without an account: its client setup page says the remote endpoint works without a key at a lower, anonymous rate limit, and the README recommends a free key from the Context7 dashboard for higher limits. These are the commands Context7 gives for Claude Code.

Remote:

claude mcp add --scope user --header "Authorization: Bearer YOUR_API_KEY" --transport http context7 https://mcp.context7.com/mcp

Local, running the npm package (needs Node.js):

claude mcp add --scope user context7 -- npx -y @upstash/context7-mcp --api-key YOUR_API_KEY

Both use --scope user, so the server is there in every project. Then check it:

claude mcp get context7

According to its README the server has two tools, resolve-library-id and query-docs. In a session, try one of the README’s own prompts, such as “Configure a Cloudflare Worker script to cache JSON API responses for five minutes. use context7”, and Claude should call them. To try the remote form without a key, leave out the --header option.

Check that it is connected

• claude mcp list shows every configured server with a status: ✔ Connected, ! Needs authentication or ✘ Failed to connect.
• claude mcp get <name> shows one server, and on a failure an Issue: line with the HTTP status or error code and any error text the server returned.
• /mcp inside a session is the panel: status, tool count per server, OAuth sign-in, reconnect, and a toggle to disable a server without removing it.

To let Claude Code use a server’s tools without asking for approval, add an allow permission rule: mcp__context7__* matches every tool from the server named context7.

When it does not work

Read the status line first. claude mcp get <name> usually says what went wrong. A 401 means the token is wrong, expired or empty.

⏸ Pending approval. A server from .mcp.json that you have not approved. Run claude in that folder, accept the trust dialog and approve it.

The flags went to the wrong program. If a local server will not start, or Claude Code rejects one of the server’s flags, check that the command came after --. Remove it with claude mcp remove <name> and add it again with the command after --.

A variable is missing. If ${VAR} names a variable that is not set and has no default, Claude Code warns in claude mcp list and /mcp, and sends the literal ${VAR} text. Set it and start a new session.

A pasted token has a newline on the end. Claude Code warns about leading or trailing whitespace in url, args, env and headers (for example headers.Authorization) and does not trim it for you. Edit the value.

The server is slow to start. The start-up timeout is set with MCP_TIMEOUT in milliseconds, for example MCP_TIMEOUT=10000 claude for ten seconds.

The same name in two scopes. Claude Code uses the higher-precedence one, and warns when the two point at different endpoints. Remove the one you do not want with claude mcp remove <name> --scope <scope>.

Too many tools. Claude Code’s docs say there is no fixed per-server tool cap: tool search, on by default, loads only tool names at the start. Large tool results are a separate limit: a warning above 10,000 tokens and a cap at 25,000 by default, raised with MAX_MCP_OUTPUT_TOKENS.

Security. A local server runs with your permissions, and a remote one sees whatever the agent sends it. Add servers from sources you trust, with keys that can do no more than the job needs.

Second example: Nordva Launch

The same command connects Claude Code to Nordva Launch, which gives the agent tools for a product’s waitlist, changelog, feedback, notifications and analytics. It is a remote server and the key is a Launch secret key:

claude mcp add --transport http nordva https://mcp.nordva.dev \
  --header "Authorization: Bearer nv_live_..."

Or run npx nordva@latest init in your project: it signs you in through the browser, writes your keys to the env file, and installs the server for Claude Code and other clients. The free plan has no time limit and needs no card. The team version with .mcp.json and the setup_check test are on Connect Claude Code to Nordva Launch, and every tool is listed on the MCP server page.

Who should not use Launch for this: if you wanted to connect a database, GitHub or a docs server, you do not need Launch; the commands above are the whole job. Launch is for someone building a product who wants the agent to run its waitlist, changelog and feedback. If you already have tools for those that you like, keep them.

Setting up Cursor too? The same server as a JSON entry is in How to add an MCP server to Cursor.