MCP Servers

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)
CLI (HTTP)
CLI (SSE)
settings.json

# 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

# 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"

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

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"]
    }
  }
}

Create the file

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

Commit it

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

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).

Get Started

Core Concepts

Configuration

Guides

Reference

Configuration scopes

Transport types

stdio

HTTP

SSE

Adding an MCP server

Server configuration format

stdio server

HTTP server

SSE server

Authentication

Managing MCP servers with `/mcp`

.mcp.json for project teams

Example: filesystem server

Enterprise server management

Build docs developers (and LLMs) love

Get Started

Core Concepts

Configuration

Guides

Reference

Documentation Index

​Configuration scopes

​Transport types

stdio

HTTP

SSE

​Adding an MCP server

​Server configuration format

​stdio server

​HTTP server

​SSE server

​Authentication

​Managing MCP servers with /mcp

​.mcp.json for project teams

​Example: filesystem server

​Enterprise server management

Build docs developers (and LLMs) love

Configuration scopes

Transport types

Adding an MCP server

Server configuration format

stdio server

HTTP server

SSE server

Authentication

Managing MCP servers with `/mcp`

.mcp.json for project teams

Example: filesystem server

Enterprise server management