MCP Servers

Extend Claude with external tools and data sources using the Model Context Protocol.

Model Context Protocol (MCP) is an open standard that lets Claude connect to external tools, APIs, and data sources. Each MCP server exposes a set of tools that Claude can call during a session — just like built-in tools, but powered by external processes or services.

Common uses include: querying databases, searching documentation, interacting with APIs (GitHub, Jira, Slack), running custom business logic, and accessing resources that Claude cannot reach on its own.

Configuration scopes

MCP servers can be configured at different scopes:

Scope	Location	When to use
local	.mcp.json in project root	Project-specific servers that you don’t want to commit to version control
project	.mcp.json in project root (after team approval)	Project-specific servers shared with the team
user	~/.claude/settings.json	Personal servers available in all your projects

The .mcp.json file in your project root is the standard way to share MCP server configs with your team. Claude Code prompts each team member to approve the servers in .mcp.json before connecting to them.

Transport types

MCP servers communicate with Claude Code over one of three transports:

stdio

Claude launches the server as a subprocess and communicates over standard input/output. Best for local tools and CLI wrappers.

HTTP

Claude connects to a running HTTP server using the MCP HTTP transport (streamable HTTP). Best for remote services and microservices.

SSE

Claude connects to a running server using HTTP with Server-Sent Events. Supported for backward compatibility; prefer HTTP for new servers.

Adding an MCP server

CLI (stdio)

# Add a stdio server (default transport)
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /tmp

# Add a stdio server with environment variables
claude mcp add -e GITHUB_TOKEN=ghp_xxx github -- npx -y @modelcontextprotocol/server-github

# Add to project scope (saved to .mcp.json)
claude mcp add --scope project sentry -- npx -y @sentry/mcp-server

CLI (HTTP)

# Add an HTTP server
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# Add an HTTP server with authorization header
claude mcp add --transport http corridor https://app.corridor.dev/api/mcp \
  --header "Authorization: Bearer my-token"

CLI (SSE)

# Add an SSE server
claude mcp add --transport sse my-server https://example.com/mcp/sse

settings.json

Edit ~/.claude/settings.json or .claude/settings.json directly:

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    }
  }
}

The claude mcp add command saves to your local scope (~/.claude/settings.json) by default. Pass --scope project to save to .mcp.json in the current directory instead.

Server configuration format

stdio server

{
  "mcpServers": {
    "my-tool": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@example/mcp-server", "--verbose"],
      "env": {
        "API_KEY": "my-secret-key",
        "BASE_URL": "https://api.example.com"
      }
    }
  }
}

type · "stdio"

Transport type. Optional — defaults to "stdio" for backward compatibility.

command · string · required

The executable to run. Must not be empty.

args · string[]

Arguments passed to the command. Defaults to [].

env · object

Environment variables set for the server subprocess. Values must be strings.

HTTP server

{
  "mcpServers": {
    "my-api": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer my-token",
        "X-Tenant-ID": "acme"
      }
    }
  }
}

type · "http" · required

Must be "http" for HTTP transport.

url · string · required

The URL of the MCP HTTP endpoint.

headers · object

HTTP headers to include with every request. Useful for authentication.

headersHelper · string

Path to a script that outputs headers as JSON. Use this for headers that require dynamic values (for example, short-lived tokens).

oauth · object

OAuth configuration for servers that require OAuth 2.0 authentication. See Authentication below.

SSE server

{
  "mcpServers": {
    "legacy-server": {
      "type": "sse",
      "url": "https://example.com/mcp/sse",
      "headers": {
        "Authorization": "Bearer my-token"
      }
    }
  }
}

type · "sse" · required

Must be "sse" for SSE transport.

url · string · required

The URL of the SSE endpoint.

headers · object

HTTP headers included with every request.

oauth · object

OAuth configuration. See Authentication below.

Authentication

For HTTP and SSE servers that require OAuth 2.0, add an oauth block to the server config:

{
  "mcpServers": {
    "secure-api": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "oauth": {
        "clientId": "my-client-id",
        "callbackPort": 8765
      }
    }
  }
}

oauth.clientId · string

OAuth client ID registered with the authorization server.

oauth.callbackPort · number

Fixed loopback port for the OAuth callback. Only required if the authorization server does not support RFC 8252 port-any matching.

oauth.authServerMetadataUrl · string

URL of the OAuth authorization server’s metadata document (must use HTTPS). Claude Code uses this to discover authorization endpoints.

When you first use an authenticated server, Claude Code opens your browser to complete the OAuth flow. The token is stored in your system keychain and reused for subsequent sessions.

Managing MCP servers with /mcp

Run /mcp inside a Claude Code session to open the MCP management panel. You can:

• View all connected, failed, and disabled servers
• Enable or disable individual servers
• Check server capabilities and connection status

From the CLI, you can also enable or disable servers directly:

# Disable a server
claude mcp disable my-server

# Enable a server
claude mcp enable my-server

# List all configured servers
claude mcp list

# Remove a server
claude mcp remove my-server

.mcp.json for project teams

The .mcp.json file in your project root is the recommended way to share MCP server configurations with your team. It uses the same format as the mcpServers key in settings files:

{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
    }
  }
}

1. Create the file

   Create .mcp.json in your project root (alongside .git/).

2. Commit it

   Add .mcp.json to version control so teammates get the same servers automatically.

3. Team members approve

   When a teammate opens the project, Claude Code shows a dialog asking them to approve the servers listed in .mcp.json. Each person approves once; the decision is stored in their local settings.

Never put secrets (API keys, tokens) directly in .mcp.json since it is committed to version control. Use environment variable references (${MY_TOKEN}) and have team members set the variables in their shell environment or CI secrets.

Example: filesystem server

The official @modelcontextprotocol/server-filesystem server gives Claude access to read and write files in specified directories:

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/projects /tmp

This adds the following to your local settings:

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "~/projects", "/tmp"]
    }
  }
}

After connecting, Claude gains tools like read_file, write_file, list_directory, and search_files, restricted to the paths you specified.

Enterprise server management

Enterprise administrators can control which MCP servers users are allowed to configure:

{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverUrl": "https://*.example.com/*" },
    { "serverCommand": ["npx", "-y", "@company/approved-server"] }
  ],
  "deniedMcpServers": [
    { "serverName": "untrusted-server" }
  ]
}

• allowedMcpServers — if set, only servers matching an entry in this list are permitted. Entries match by name, URL pattern (supports * wildcards), or exact command array.
• deniedMcpServers — servers matching an entry are always blocked, even if they are also on the allowlist.

Set allowManagedMcpServersOnly: true in managed settings to restrict the allowedMcpServers allowlist to the managed settings file only (users can still add their own servers but the admin-defined allowlist applies).