Install an MCP Server in Claude Code

To install an MCP server in Claude Code, run claude mcp add. For a remote server use claude mcp add --transport http <name> <url>. For a local one use claude mcp add <name> -- <command>. Then run claude mcp list to confirm it connected. Add --scope project to share it through .mcp.json. Facts checked 31 October 2026.

What you will have at the end

• One remote and one local MCP server connected
• A decision on which scope each server belongs in
• A committed .mcp.json for servers your whole team uses
• A routine for checking status and fixing a server that will not connect
• Limits and security habits that keep context and risk down

New to the idea? MCP, the Model Context Protocol, is how Claude Code reaches tools and data outside your project, such as a browser, a database or an issue tracker. If you want servers to try after this guide, see our Claude Code MCP servers page and the best MCP servers roundup.

The four ways to install, in one table

There is also a WebSocket route for wss:// endpoints, which uses JSON config because --transport does not accept ws. Most servers fall into the first and third rows.

Step 1: Add a remote server

HTTP is the most widely supported transport for cloud services. The docs use Notion as the example.

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

If the service wants a token in a header, pass it with --header.

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

Many hosted servers use sign-in instead of a static token. After adding one, open a session and run /mcp to authenticate. From a shell, claude mcp login <name> does the same. A claude -p or Agent SDK run cannot show the sign-in flow, so authenticate from an interactive session first.

When you configure by JSON, type accepts streamable-http as an alias for http, which is the name the MCP specification uses. A JSON entry with a url and no type is an error, because Claude Code reads an entry with no type as a stdio server and skips it with a message telling you to add "type": "http".

Step 2: Add a local server

Local servers run as processes on your machine. They suit tools that need direct system access. The docs' example adds the Airtable server with a key in its environment.

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

The -- matters. Everything before it belongs to Claude, and everything after it is the command that starts the server, passed through untouched. Without it, Claude would try to read the server's flags as its own.

One trap: --env takes multiple KEY=value pairs, so if the server name comes directly after it, the CLI reads the name as another pair and rejects it. Put at least one other option, such as --transport stdio, between --env and the name.

Claude Code sets CLAUDE_PROJECT_DIR in the spawned server's environment, so a server can find the project root without relying on the working directory. A server that limits file access to allowed folders should use the MCP roots/list request, which Claude Code answers with the launch directory plus any added directories.

Step 3: Turn another client's instructions into a command

Server docs often show setup for Claude Desktop or Cursor and give no claude mcp add line. Look for one of three things.

For the JSON case, give add-json the object inside mcpServers, not the wrapper. This block:

{
  "mcpServers": {
    "example": {
      "command": "npx",
      "args": ["-y", "@example/mcp-server"]
    }
  }
}

becomes this command:

claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'

Two repairs may be needed first. A url entry needs a type of http, sse or ws. And a server key with characters other than letters, numbers, hyphens and underscores needs a new name.

Step 4: Choose a scope

Scope decides which projects load the server and whether teammates get it.

Add the flag to any command.

claude mcp add --transport http stripe --scope local https://mcp.stripe.com
claude mcp add --transport http shared-server --scope project https://example.com/mcp
claude mcp add --transport http notion --scope user https://mcp.notion.com/mcp

A note on naming: MCP local scope is stored in ~/.claude.json under the project's path, which differs from general local settings in .claude/settings.local.json. They are separate things that share a word.

Rules of thumb. Use local for experiments and servers that hold your own credentials. Use project for servers every contributor needs. Use user for servers you want everywhere, like a docs lookup.

A team .mcp.json

Project scope writes a standard file you commit.

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

For safety, Claude Code asks for approval in an interactive session before using a project server from .mcp.json. To reset those choices, run claude mcp reset-project-choices. In claude -p, Agent SDK and cloud runs there is no prompt, so Claude Code does not wait for one. Block a server there by adding it to disabledMcpjsonServers, or start with --strict-mcp-config so only servers from --mcp-config load.

Keep secrets out of the committed file. Use environment variable expansion so each person supplies their own key. In command or args the docs recommend a default, such as ${CLAUDE_PROJECT_DIR:-.}, because that variable exists only in the server's environment.

Step 5: Check it works

claude mcp add prints an Added ... line, which only means the configuration was written. To see whether it connected, use these.

claude mcp list          # all servers, with health
claude mcp get notion    # details for one
claude mcp remove notion

Inside a session, /mcp shows status. claude mcp list prints entries such as Connected, Needs authentication and Failed to connect. A failure status means the server did not connect, not that the command broke.

Some statuses describe a decision, not a connection attempt.

Removing a remote server also deletes the OAuth tokens and client registration Claude Code stored. It does not revoke them at the issuer. Run claude mcp logout <name> first if you want that where supported.

Step 6: Understand the limits

Servers share your context budget, and a few limits are worth knowing before you add ten.

• Tool search is on by default. Claude searches for tools rather than loading every definition, which keeps many servers affordable. Configurations without it include ENABLE_TOOL_SEARCH=false, and in those cases Claude Code does not tell Claude about failed connections.
• Output size. Claude Code warns when tool output exceeds 10,000 tokens and limits it to 25,000 by default. Raise it with MAX_MCP_OUTPUT_TOKENS, for example MAX_MCP_OUTPUT_TOKENS=50000. Text results over 50,000 characters are saved to a file regardless.
• Startup time. MCP_TIMEOUT=10000 claude sets a 10-second startup timeout.
• Tool call time. A per-server timeout is a hard wall-clock limit per call. MCP_TOOL_TIMEOUT sets the default, which is about 28 hours when unset.
• Reconnection. Remote servers that drop mid-session reconnect automatically, and you can retry failed servers yourself from /mcp.

If a tool is flaky, the first suspect is the output cap, because a large database result can be truncated or saved to a file.

Step 7: Give a server to one subagent only

If only a reviewer needs a browser, do not load a browser server for the whole session. A subagent can scope servers in its frontmatter, by name or inline.

---
name: browser-tester
description: Tests features in a real browser. Use after UI changes.
mcpServers:
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
---

The inline server starts when the subagent starts and stops when it finishes, so its tools never enter your main context. Inline servers need workspace trust. Our subagent guide covers the rest of the file, and the Playwright MCP page covers that server.

A full run for a new team member

Here is the sequence a lead might hand a new hire, using the commands above. The server names are placeholders.

1. Clone the repo. It contains .mcp.json with the two shared servers the team uses.
2. Run claude in the folder. Claude Code lists the project servers and asks you to approve each one. Read the list and approve.
3. Run claude mcp list. Expect the remote server to show Needs authentication until you sign in.
4. Type /mcp, pick the server, and complete the sign-in in the browser.
5. Run claude mcp list again. Both servers should show Connected.
6. Add any personal server in local scope, so it does not leak into the shared file.

If step 5 shows a failure for a stdio server, run its launch command by hand in a terminal. A missing Node version or a missing environment variable is the usual reason, and the terminal shows the real error where Claude Code shows a summary.

Write these six steps into the repo's CLAUDE.md or onboarding doc, so nobody has to rediscover them. The approval prompt is a feature, not friction: it stops a pulled change from silently starting a new process on your machine.

Moving servers between machines

Local and user scopes live in ~/.claude.json, which is not part of any repo. To set up a second machine, rerun the claude mcp add commands, or keep them in a short shell script in your own dotfiles. Project servers come along with the repo, so only the sign-in and any environment variables need repeating.

Keep a list of what you installed and why. Six months from now, a server you do not recognize in claude mcp list is a small puzzle, and removing something you no longer need is easier when a note says what it was for.

Security habits

An MCP server is code, and a remote one is someone else's code reading your prompts. These habits keep the risk down.

1. Read before you add. Check who publishes the server and what it can do. A server with write access can change things.
2. Prefer official servers from the service itself, and pin versions where you run npx.
3. Use read-only credentials where the service allows it. A database server with a read-only user cannot drop a table.
4. Keep tokens out of git. Use --scope local or environment expansion.
5. Review `.mcp.json` changes in pull requests like build scripts.
6. Protect risky tools with permission rules or a PreToolUse hook. See our hooks guide.
7. Remove what you stopped using. Unused servers still cost context and attack surface.

Tool descriptions and results come from the server, so treat text coming back as untrusted input, the same as a web page.

Troubleshooting

Our take

Pick the scope first, because it decides who is affected. Our default is local while you test and project once two people need it. Move to user scope only for servers you truly want in every repo.

Be stingy with servers. Tool search makes many servers affordable, but each one is still something that can fail, drift or leak. Three well-chosen servers beat fifteen. Start with one for docs lookup, one for your tracker and one for the browser, and add more only when a real task needs it.

Checklist

• Used --transport http for remote and -- for local servers
• Chose a scope on purpose
• claude mcp list shows Connected
• Tokens are not in a committed file
• Shared servers are in .mcp.json and reviewed in pull requests
• Risky tools have a permission rule or hook
• Removed servers you no longer use

Related pages

• Claude Code MCP servers
• Best MCP servers
• Claude Code hooks guide
• How to write a subagent
• Claude Code and Playwright for browser QA