Skip to main content
MCP (Model Context Protocol) is an open standard that lets Claude Code connect to external servers that expose tools, resources, and prompts. When an MCP server is connected, Claude can call its tools the same way it calls built-in tools like Bash or file operations.

​
Adding an MCP server

Use claude mcp add to register a server. The command syntax depends on the transport type.
Stdio servers run as a local subprocess. The command and any arguments are passed directly.
claude mcp add <name> <command> [args...]
Examples:
# Add a server that runs via npx
claude mcp add my-server -- npx my-mcp-server

# Add a server with subprocess flags
claude mcp add my-server -- my-command --some-flag arg1

# Add a server with environment variables
claude mcp add -e API_KEY=xxx my-server -- npx my-mcp-server
If you pass a URL-shaped string without --transport, Claude Code will warn you that it is treating it as a stdio command. Always specify --transport http or --transport sse for remote servers.

​
Scopes

Every MCP server is stored in one of three user-controlled scopes. Use -s or --scope to choose:
ScopeFlagWhere it’s storedWho it applies to
local-s local (default)Global Claude config, keyed to current projectYou, in this project only
project-s project.mcp.json in the project rootEveryone who checks out the project
user-s userGlobal Claude configYou, in all your projects
# Add for all your projects
claude mcp add -s user my-server -- npx my-mcp-server

# Add to the project's .mcp.json (commit this file to share with your team)
claude mcp add -s project my-server -- npx my-mcp-server
Commit .mcp.json to version control to share a consistent set of MCP servers with your whole team.

​
Listing and removing servers

# List all configured servers and their status
claude mcp list

# Remove a server by name
claude mcp remove <name>

​
The .mcp.json config file

When you use --scope project, Claude Code writes to a .mcp.json file in the current working directory. You can also create or edit this file directly. 
{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["my-mcp-server"],
      "env": {
        "API_KEY": "your-key-here"
      }
    },
    "remote-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}
The type field is optional for stdio servers (it defaults to "stdio"). For remote servers you must set "type": "sse" or "type": "http".

​
Environment variable expansion

Claude Code expands environment variables in MCP server configs at connection time. This applies to command, args, env values, and url/headers fields for remote servers. 
{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["my-mcp-server"],
      "env": {
        "API_KEY": "$MY_API_KEY"
      }
    }
  }
}

​
Transport types

The source defines the following transport types for MCP server configs:
TypeDescription
stdioLaunches a local subprocess and communicates over stdin/stdout. Default when no --transport is given.
sseConnects to a remote server using Server-Sent Events over HTTP.
httpConnects to a remote server using streamable HTTP.
The ws (WebSocket) transport type exists in the codebase but is not exposed via claude mcp add. The sse-ide, ws-ide, and sdk types are internal and used by IDE integrations.

​
Authentication for remote servers

For SSE and HTTP servers that require OAuth, pass the OAuth client ID and optionally a client secret: 
# Add with OAuth client ID
claude mcp add --transport http my-server https://example.com/mcp \
  --client-id <clientId>

# Prompt for client secret (or set MCP_CLIENT_SECRET env var)
claude mcp add --transport http my-server https://example.com/mcp \
  --client-id <clientId> \
  --client-secret

# Fix the OAuth callback port (for pre-registered redirect URIs)
claude mcp add --transport http my-server https://example.com/mcp \
  --client-id <clientId> \
  --callback-port 8080
--client-id, --client-secret, and --callback-port are only valid for sse and http transports. They are ignored for stdio servers.

​
Enabling and disabling servers

You can enable or disable MCP servers without removing them: 
# Disable a specific server
/mcp disable <name>

# Enable a specific server
/mcp enable <name>

# Disable all servers
/mcp disable

# Enable all servers
/mcp enable

​
Reconnecting a server

If a server connection drops, you can reconnect it from within a session: 
/mcp reconnect <name>

​
Enterprise policy settings

Administrators can control which MCP servers are available using policy configuration. Two lists are supported:
  • allowedMcpServers — an allowlist. When set, only listed servers are permitted. An empty list blocks all servers.
  • deniedMcpServers — a denylist. Listed servers are always blocked, even if they appear in the allowlist.
Entries can match by server name, by the command array (stdio servers), or by URL pattern with * wildcards (remote servers). The enterprise-managed MCP config file is stored at the managed path as managed-mcp.json. When this file exists, it takes exclusive control of MCP configuration and users cannot add servers manually.

​
Using MCP tools in a session

Once a server is connected, its tools appear in the tool list and Claude can call them automatically. Tools from MCP servers are prefixed with the server name (e.g., mcp__myserver__toolname). Connected servers are shown with a status indicator. If a server has needs-auth status, you will be prompted to complete authentication before its tools are available.

Build docs developers (and LLMs) love

Get started for freeTalk to us