Claude Code MCP server setup: add, scope, check and remove

To add an MCP server to Claude Code, run claude mcp add --transport http <name> <url> in your terminal, add --header if the server needs a key, and check the result with claude mcp list, or /mcp inside a session. By default the server is stored in local scope: this project, on your machine, for you only. claude mcp remove <name> takes it out again.

What an MCP server adds to Claude Code

The Model Context Protocol lets Claude Code call tools that live outside it: a ticket tracker, a database, a design tool, a prototype canvas. Each server exposes a list of tools with typed arguments, and Claude Code calls them like its own tools, under the same permission system. A tool from a server named github is called mcp__github__<tool>, which is also how you name it in permission rules.

Before adding one, the Claude Code MCP documentation gives the rule to start with: verify you trust each server, because servers that fetch external content can expose you to prompt injection. Prompt injection in agent tools covers what that means in practice.

Step 1: choose the transport

HTTP is the recommended transport for remote servers. Servers that run as a local process on your machine use stdio.

# Remote server over HTTP
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Remote server that needs a key in a header
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

# Local server started as a process: everything after -- is its command
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

Two details trip people up with stdio servers. The -- separates Claude Code’s own options from the command that starts the server, so flags like -y reach npx. And --env accepts several KEY=value pairs: if the server name comes right after it, the name is read as another pair and rejected, so put another option, such as --transport stdio, in between.

SSE is deprecated. For a service that only exposes SSE, recent versions accept the same --transport http command and switch to SSE when the server does not accept HTTP.

Step 2: pick a scope

The scope decides who gets the server and where it is written.

Scope	Flag	Stored in	Loads in	Shared
Local (default)	--scope local	~/.claude.json, under this project	This project	No
Project	--scope project	.mcp.json at the project root	This project	Yes, via version control
User	--scope user	~/.claude.json, top level	All your projects	No

Use local scope for anything that carries a personal key. Use project scope when the whole team should get the same server, and commit .mcp.json. For security, Claude Code asks for approval in an interactive session before it uses project servers from .mcp.json; claude mcp reset-project-choices resets those choices. When the same name exists in several scopes, local wins over project, which wins over user.

Step 3: pass the key without leaking it

A server key in the wrong place ends up in a commit or in a chat transcript. Three habits avoid it:

1. Keep keyed servers in local scope. ~/.claude.json lives in your home folder, not in the repository.
2. In .mcp.json, reference a variable instead of the value. Claude Code expands ${VAR} and ${VAR:-default} in command, args, env, url and headers:

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

3. Run the add command yourself, in your own terminal. If the agent runs it, the key passes through the conversation.

Claude Code also guards against two common mistakes. In a remote server’s url and headers, its own credentials, such as ANTHROPIC_API_KEY, read as empty, so a .mcp.json cannot send them to a server it names. And it warns about hidden leading or trailing whitespace, the usual trace of a pasted token with a newline. For more on giving agents narrow credentials, see giving an AI agent access with a scoped key.

Step 4: check that it connected

claude mcp list          # every server with a health status
claude mcp get <name>    # one server, with the failure detail if any

The status tells you what to do next:

• Connected: ready to use.
• Needs authentication: for servers that sign in with OAuth, open /mcp in a session or run claude mcp login <name>.
• Failed to connect: the line shows the HTTP status or error the server returned. For a server with a header you configured, a 401 or 403 usually means the key is wrong or revoked.
• Pending approval: a project server from .mcp.json that you have not approved yet. Run claude in the folder to review it.

Inside a session, /mcp shows the same health and the tool count of each server, and lets you reconnect a server or turn it off without removing it. If the tools do not show up in a session that was already open, restart Claude Code: claude --continue reopens the most recent conversation in the folder.

Step 5: set limits and permissions

Two settings keep a server from surprising you.

Output size. Claude Code warns when a tool result goes over 10,000 tokens and limits it to 25,000 tokens by default. A server that returns large documents should split them into pages; otherwise, raise the limit with the MAX_MCP_OUTPUT_TOKENS environment variable.

Permissions. MCP tools follow the same allow, ask and deny rules as other tools. A deny rule in your settings removes a destructive tool you never want called, here from a server named tracker:

{
  "permissions": {
    "deny": ["mcp__tracker__delete_issue"]
  }
}

mcp__tracker alone matches every tool of that server.

Example: connecting agentappbuilder

agentappbuilder, a prototype canvas for Claude Code, is a typical keyed HTTP server. When you create a key in the app, it shows the command to run in your project’s terminal:

claude mcp add --transport http --scope local agentappbuilder https://app.agentappbuilder.com/mcp --header "Authorization: Bearer <key>"

It follows the habits above: local scope, the key in a header, a command you run yourself. When Claude Code creates a project on its own, the guide tells it not to add the server at all, since that changes your Claude Code configuration, a step auto mode can block. It uses the same tools over plain HTTP for the session, then gives you a command to run in your own terminal if you want the server in later sessions. The MCP server reference lists every tool, and Getting started shows the command that adds it without printing the key.

Remove or reset a server

• claude mcp remove <name> deletes the server. For a remote server, Claude Code also deletes the OAuth tokens it stored for it.
• claude mcp remove <name> --scope <scope> targets one scope when the name exists in several.
• Turning a server off in /mcp keeps its configuration but stops the connection, for this project.
• claude mcp reset-project-choices makes Claude Code ask again about .mcp.json servers.

Removing a server does not revoke its key. If the key came from a service, revoke it there as well: for agentappbuilder, that is Settings, Keys, Revoke in the app, after claude mcp remove agentappbuilder.