Connect Claude Code to tools via MCP

Learn how to connect Claude Code to your tools with the Model Context Protocol.

export const MCPServersTable = ({platform = "all"}) => { const ifYouAreAnAiAgentReadingThisYouShouldInsteadFetch = 'https://api.anthropic.com/mcp-registry/docs'; const [servers, setServers] = useState([]); const [loading, setLoading] = useState(true); const [error, setError] = useState(null); useEffect(() => { const fetchServers = async () => { try { setLoading(true); const allServers = []; let cursor = null; do { const url = new URL('https://api.anthropic.com/mcp-registry/v0/servers'); url.searchParams.set('version', 'latest'); url.searchParams.set('limit', '100'); if (cursor) { url.searchParams.set('cursor', cursor); } const response = await fetch(url); if (!response.ok) { throw new Error(Failed to fetch MCP registry: ${response.status}); } const data = await response.json(); allServers.push(...data.servers); cursor = data.metadata?.nextCursor || null; } while (cursor); const transformedServers = allServers.map(item => { const server = item.server; const meta = item._meta?.['com.anthropic.api/mcp-registry'] || ({}); const worksWith = meta.worksWith || []; const availability = { claudeCode: worksWith.includes('claude-code'), mcpConnector: worksWith.includes('claude-api'), claudeDesktop: worksWith.includes('claude-desktop') }; const remoteUrl = server.remotes?.[0]?.url || meta.url; const remoteType = server.remotes?.[0]?.type; const isTemplatedUrl = remoteUrl?.includes('{'); let setupUrl; if (isTemplatedUrl && meta.requiredFields) { const urlField = meta.requiredFields.find(f => f.field === 'url'); setupUrl = urlField?.sourceUrl || meta.documentation; } const urls = {}; if (!isTemplatedUrl) { if (remoteType === 'streamable-http') { urls.http = remoteUrl; } else if (remoteType === 'sse') { urls.sse = remoteUrl; } } let envVars = []; if (server.packages && server.packages.length > 0) { const npmPackage = server.packages.find(p => p.registryType === 'npm'); if (npmPackage) { urls.stdio = npx -y ${npmPackage.identifier}; if (npmPackage.environmentVariables) { envVars = npmPackage.environmentVariables; } } } return { name: meta.displayName || server.title || server.name, description: meta.oneLiner || server.description, documentation: meta.documentation, urls: urls, envVars: envVars, availability: availability, customCommands: meta.claudeCodeCopyText ? { claudeCode: meta.claudeCodeCopyText } : undefined, setupUrl: setupUrl }; }); setServers(transformedServers); setError(null); } catch (err) { setError(err.message); console.error('Error fetching MCP registry:', err); } finally { setLoading(false); } }; fetchServers(); }, []); const generateClaudeCodeCommand = server => { if (server.customCommands && server.customCommands.claudeCode) { return server.customCommands.claudeCode; } const serverSlug = server.name.toLowerCase().replace(/[^a-z0-9]/g, '-'); if (server.urls.http) { return claude mcp add ${serverSlug} --transport http ${server.urls.http}; } if (server.urls.sse) { return claude mcp add ${serverSlug} --transport sse ${server.urls.sse}; } if (server.urls.stdio) { const envFlags = server.envVars && server.envVars.length > 0 ? server.envVars.map(v => --env ${v.name}=YOUR_${v.name}).join(' ') : ''; const baseCommand = claude mcp add ${serverSlug} --transport stdio; return envFlags ? ${baseCommand} ${envFlags} -- ${server.urls.stdio} : ${baseCommand} -- ${server.urls.stdio}; } return null; }; if (loading) { return

Loading MCP servers...

; } if (error) { return

Error loading MCP servers: {error}

; } const filteredServers = servers.filter(server => { if (platform === "claudeCode") { return server.availability.claudeCode; } else if (platform === "mcpConnector") { return server.availability.mcpConnector; } else if (platform === "claudeDesktop") { return server.availability.claudeDesktop; } else if (platform === "all") { return true; } else { throw new Error(Unknown platform: ${platform}); } }); return <>

  <div className="cards-container">
    {filteredServers.map(server => {
const claudeCodeCommand = generateClaudeCodeCommand(server);
const mcpUrl = server.urls.http || server.urls.sse;
const commandToShow = platform === "claudeCode" ? claudeCodeCommand : mcpUrl;
return <div key={server.name} className="server-card">
          <div>
            {server.documentation ? <a href={server.documentation}>
                <strong>{server.name}</strong>
              </a> : <strong>{server.name}</strong>}
          </div>

          <p style={{
  margin: '0.5rem 0',
  fontSize: '0.9rem'
}}>
            {server.description}
          </p>

          {server.setupUrl && <p style={{
  margin: '0.25rem 0',
  fontSize: '0.8rem',
  fontStyle: 'italic',
  opacity: 0.7
}}>
              Requires user-specific URL.{' '}
              <a href={server.setupUrl} style={{
  textDecoration: 'underline'
}}>
                Get your URL here
              </a>.
            </p>}

          {commandToShow && !server.setupUrl && <>
            <p style={{
  display: 'block',
  fontSize: '0.75rem',
  fontWeight: 500,
  minWidth: 'fit-content',
  marginTop: '0.5rem',
  marginBottom: 0
}}>
              {platform === "claudeCode" ? "Command" : "URL"}
            </p>
            <div className="command-row">
              <code>
                {commandToShow}
              </code>
            </div>
          </>}
        </div>;

})}

</>; };

Claude Code can connect to hundreds of external tools and data sources through the Model Context Protocol (MCP), an open source standard for AI-tool integrations. MCP servers give Claude Code access to your tools, databases, and APIs.

What you can do with MCP

With MCP servers connected, you can ask Claude Code to:

Implement features from issue trackers: "Add the feature described in JIRA issue ENG-4521 and create a PR on GitHub."
Analyze monitoring data: "Check Sentry and Statsig to check the usage of the feature described in ENG-4521."
Query databases: "Find emails of 10 random users who used feature ENG-4521, based on our PostgreSQL database."
Integrate designs: "Update our standard email template based on the new Figma designs that were posted in Slack"
Automate workflows: "Create Gmail drafts inviting these 10 users to a feedback session about the new feature."

Popular MCP servers

Here are some commonly used MCP servers you can connect to Claude Code:

Installing MCP servers

MCP servers can be configured in three different ways depending on your needs:

Option 1: Add a remote HTTP server

HTTP servers are the recommended option for connecting to remote MCP servers. This is the most widely supported transport for cloud-based services.

# Basic syntax
claude mcp add --transport http <name> <url>

# Real example: Connect to Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

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

Option 2: Add a remote SSE server

# Basic syntax
claude mcp add --transport sse <name> <url>

# Real example: Connect to Asana
claude mcp add --transport sse asana https://mcp.asana.com/sse

# Example with authentication header
claude mcp add --transport sse private-api https://api.company.com/sse \
  --header "X-API-Key: your-key-here"

Option 3: Add a local stdio server

Stdio servers run as local processes on your machine. They're ideal for tools that need direct system access or custom scripts.

# Basic syntax
claude mcp add --transport stdio <name> <command> [args...]

# Real example: Add Airtable server
claude mcp add --transport stdio airtable --env AIRTABLE_API_KEY=YOUR_KEY \
  -- npx -y airtable-mcp-server

Managing your servers

Once configured, you can manage your MCP servers with these commands:

# List all configured servers
claude mcp list

# Get details for a specific server
claude mcp get github

# Remove a server
claude mcp remove github

# (within Claude Code) Check server status
/mcp

Tip

Tips:

Use the --scope flag to specify where the configuration is stored:
local (default): Available only to you in the current project (was called project in older versions)
project: Shared with everyone in the project via .mcp.json file
user: Available to you across all projects (was called global in older versions)
Set environment variables with --env flags (for example, --env KEY=value)
Configure MCP server startup timeout using the MCP_TIMEOUT environment variable (for example, MCP_TIMEOUT=10000 claude sets a 10-second timeout)
Claude Code will display a warning when MCP tool output exceeds 10,000 tokens. To increase this limit, set the MAX_MCP_OUTPUT_TOKENS environment variable (for example, MAX_MCP_OUTPUT_TOKENS=50000)
Use /mcp to authenticate with remote servers that require OAuth 2.0 authentication

Warning

Windows Users: On native Windows (not WSL), local MCP servers that use npx require the cmd /c wrapper to ensure proper execution.

# This creates command="cmd" which Windows can execute
claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

Without the cmd /c wrapper, you'll encounter "Connection closed" errors because Windows cannot directly execute npx. (See the note above for an explanation of the -- parameter.)

Plugin-provided MCP servers

Plugins can bundle MCP servers, automatically providing tools and integrations when the plugin is enabled. Plugin MCP servers work identically to user-configured servers.

How plugin MCP servers work:

Plugins define MCP servers in .mcp.json at the plugin root or inline in plugin.json
When a plugin is enabled, its MCP servers start automatically
Plugin MCP tools appear alongside manually configured MCP tools
Plugin servers are managed through plugin installation (not /mcp commands)

Example plugin MCP configuration:

In .mcp.json at plugin root:

{
  "database-tools": {
    "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
    "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
    "env": {
      "DB_URL": "${DB_URL}"
    }
  }
}

Or inline in plugin.json:

{
  "name": "my-plugin",
  "mcpServers": {
    "plugin-api": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/api-server",
      "args": ["--port", "8080"]
    }
  }
}

Plugin MCP features:

Automatic lifecycle: Servers start when plugin enables, but you must restart Claude Code to apply MCP server changes (enabling or disabling)
Environment variables: Use ${CLAUDE_PLUGIN_ROOT} for plugin-relative paths
User environment access: Access to same environment variables as manually configured servers
Multiple transport types: Support stdio, SSE, and HTTP transports (transport support may vary by server)

Viewing plugin MCP servers:

# Within Claude Code, see all MCP servers including plugin ones
/mcp

Plugin servers appear in the list with indicators showing they come from plugins.

Benefits of plugin MCP servers:

Bundled distribution: Tools and servers packaged together
Automatic setup: No manual MCP configuration needed
Team consistency: Everyone gets the same tools when plugin is installed

See the plugin components reference for details on bundling MCP servers with plugins.

MCP installation scopes

MCP servers can be configured at three different scope levels, each serving distinct purposes for managing server accessibility and sharing. Understanding these scopes helps you determine the best way to configure servers for your specific needs.

Local scope

Local-scoped servers represent the default configuration level and are stored in ~/.claude.json under your project's path. These servers remain private to you and are only accessible when working within the current project directory. This scope is ideal for personal development servers, experimental configurations, or servers containing sensitive credentials that shouldn't be shared.

# Add a local-scoped server (default)
claude mcp add --transport http stripe https://mcp.stripe.com

# Explicitly specify local scope
claude mcp add --transport http stripe --scope local https://mcp.stripe.com

Project scope

Project-scoped servers enable team collaboration by storing configurations in a .mcp.json file at your project's root directory. This file is designed to be checked into version control, ensuring all team members have access to the same MCP tools and services. When you add a project-scoped server, Claude Code automatically creates or updates this file with the appropriate configuration structure.

# Add a project-scoped server
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

The resulting .mcp.json file follows a standardized format:

{
  "mcpServers": {
    "shared-server": {
      "command": "/path/to/server",
      "args": [],
      "env": {}
    }
  }
}

For security reasons, Claude Code prompts for approval before using project-scoped servers from .mcp.json files. If you need to reset these approval choices, use the claude mcp reset-project-choices command.

User scope

User-scoped servers are stored in ~/.claude.json and provide cross-project accessibility, making them available across all projects on your machine while remaining private to your user account. This scope works well for personal utility servers, development tools, or services you frequently use across different projects.

# Add a user server
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

Choosing the right scope

Select your scope based on:

Local scope: Personal servers, experimental configurations, or sensitive credentials specific to one project
Project scope: Team-shared servers, project-specific tools, or services required for collaboration
User scope: Personal utilities needed across multiple projects, development tools, or frequently used services

Scope hierarchy and precedence

MCP server configurations follow a clear precedence hierarchy. When servers with the same name exist at multiple scopes, the system resolves conflicts by prioritizing local-scoped servers first, followed by project-scoped servers, and finally user-scoped servers. This design ensures that personal configurations can override shared ones when needed.

Environment variable expansion in `.mcp.json`

Claude Code supports environment variable expansion in .mcp.json files, allowing teams to share configurations while maintaining flexibility for machine-specific paths and sensitive values like API keys.

Supported syntax:

${VAR} - Expands to the value of environment variable VAR
${VAR:-default} - Expands to VAR if set, otherwise uses default

Expansion locations: Environment variables can be expanded in:

command - The server executable path
args - Command-line arguments
env - Environment variables passed to the server
url - For HTTP server types
headers - For HTTP server authentication

Example with variable expansion:

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

If a required environment variable is not set and has no default value, Claude Code will fail to parse the config.

Practical examples

{/* ### Example: Automate browser testing with Playwright

# 1. Add the Playwright MCP server
claude mcp add --transport stdio playwright -- npx -y @playwright/mcp@latest

# 2. Write and run browser tests
> "Test if the login flow works with test@example.com"
> "Take a screenshot of the checkout page on mobile"
> "Verify that the search feature returns results"
``` */}

### Example: Monitor errors with Sentry

```bash  theme={null}
# 1. Add the Sentry MCP server
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# 2. Use /mcp to authenticate with your Sentry account
> /mcp

# 3. Debug production issues
> "What are the most common errors in the last 24 hours?"
> "Show me the stack trace for error ID abc123"
> "Which deployment introduced these new errors?"

Example: Connect to GitHub for code reviews

# 1. Add the GitHub MCP server
claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# 2. In Claude Code, authenticate if needed
> /mcp
# Select "Authenticate" for GitHub

# 3. Now you can ask Claude to work with GitHub
> "Review PR #456 and suggest improvements"
> "Create a new issue for the bug we just found"
> "Show me all open PRs assigned to me"

Example: Query your PostgreSQL database

# 1. Add the database server with your connection string
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

# 2. Query your database naturally
> "What's our total revenue this month?"
> "Show me the schema for the orders table"
> "Find customers who haven't made a purchase in 90 days"

Authenticate with remote MCP servers

Many cloud-based MCP servers require authentication. Claude Code supports OAuth 2.0 for secure connections.

Add the server that requires authentication

For example:

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

Use the /mcp command within Claude Code

In Claude code, use the command:

> /mcp

Then follow the steps in your browser to login.

Add MCP servers from JSON configuration

If you have a JSON configuration for an MCP server, you can add it directly:

Add an MCP server from JSON

# Basic syntax
claude mcp add-json <name> '<json>'

# Example: Adding an HTTP server with JSON configuration
claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

# Example: Adding a stdio server with JSON configuration
claude mcp add-json local-weather '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'

Verify the server was added

claude mcp get weather-api

Import MCP servers from Claude Desktop

If you've already configured MCP servers in Claude Desktop, you can import them:

Import servers from Claude Desktop

# Basic syntax 
claude mcp add-from-claude-desktop

Select which servers to import

After running the command, you'll see an interactive dialog that allows you to select which servers you want to import.

Verify the servers were imported

claude mcp list

Use Claude Code as an MCP server

You can use Claude Code itself as an MCP server that other applications can connect to:

# Start Claude as a stdio MCP server
claude mcp serve

You can use this in Claude Desktop by adding this configuration to claude_desktop_config.json:

{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "claude",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

Warning

Configuring the executable path: The command field must reference the Claude Code executable. If the claude command is not in your system's PATH, you'll need to specify the full path to the executable.

To find the full path:

which claude

Then use the full path in your configuration:

{
"mcpServers": {
"claude-code": {
"type": "stdio",
"command": "/full/path/to/claude",
"args": ["mcp", "serve"],
"env": {}
}
}
}

Without the correct executable path, you'll encounter errors like spawn claude ENOENT.

MCP output limits and warnings

When MCP tools produce large outputs, Claude Code helps manage the token usage to prevent overwhelming your conversation context:

Output warning threshold: Claude Code displays a warning when any MCP tool output exceeds 10,000 tokens
Configurable limit: You can adjust the maximum allowed MCP output tokens using the MAX_MCP_OUTPUT_TOKENS environment variable
Default limit: The default maximum is 25,000 tokens

To increase the limit for tools that produce large outputs:

# Set a higher limit for MCP tool outputs
export MAX_MCP_OUTPUT_TOKENS=50000
claude

This is particularly useful when working with MCP servers that:

Query large datasets or databases
Generate detailed reports or documentation
Process extensive log files or debugging information

Use MCP resources

MCP servers can expose resources that you can reference using @ mentions, similar to how you reference files.

Reference MCP resources

List available resources

Type @ in your prompt to see available resources from all connected MCP servers. Resources appear alongside files in the autocomplete menu.

Reference a specific resource

Use the format @server:protocol://resource/path to reference a resource:

> Can you analyze @github:issue://123 and suggest a fix?

> Please review the API documentation at @docs:file://api/authentication

Multiple resource references

You can reference multiple resources in a single prompt:

> Compare @postgres:schema://users with @docs:file://database/user-model

Use MCP prompts as slash commands

MCP servers can expose prompts that become available as slash commands in Claude Code.

Execute MCP prompts

Discover available prompts

Type / to see all available commands, including those from MCP servers. MCP prompts appear with the format /mcp__servername__promptname.

Execute a prompt without arguments

> /mcp__github__list_prs

Execute a prompt with arguments

Many prompts accept arguments. Pass them space-separated after the command:

> /mcp__github__pr_review 456

> /mcp__jira__create_issue "Bug in login flow" high

Enterprise MCP configuration

For organizations that need centralized control over MCP servers, Claude Code supports two enterprise configuration options:

Exclusive control with managed-mcp.json: Deploy a fixed set of MCP servers that users cannot modify or extend
Policy-based control with allowlists/denylists: Allow users to add their own servers, but restrict which ones are permitted

These options allow IT administrators to:

Control which MCP servers employees can access: Deploy a standardized set of approved MCP servers across the organization
Prevent unauthorized MCP servers: Restrict users from adding unapproved MCP servers
Disable MCP entirely: Remove MCP functionality completely if needed

Option 1: Exclusive control with managed-mcp.json

When you deploy a managed-mcp.json file, it takes exclusive control over all MCP servers. Users cannot add, modify, or use any MCP servers other than those defined in this file. This is the simplest approach for organizations that want complete control.

System administrators deploy the configuration file to a system-wide directory:

macOS: /Library/Application Support/ClaudeCode/managed-mcp.json
Linux and WSL: /etc/claude-code/managed-mcp.json
Windows: C:\Program Files\ClaudeCode\managed-mcp.json

The managed-mcp.json file uses the same format as a standard .mcp.json file:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    },
    "company-internal": {
      "type": "stdio",
      "command": "/usr/local/bin/company-mcp-server",
      "args": ["--config", "/etc/company/mcp-config.json"],
      "env": {
        "COMPANY_API_URL": "https://internal.company.com"
      }
    }
  }
}

Option 2: Policy-based control with allowlists and denylists

Instead of taking exclusive control, administrators can allow users to configure their own MCP servers while enforcing restrictions on which servers are permitted. This approach uses allowedMcpServers and deniedMcpServers in the managed settings file.

Restriction options

Each entry in the allowlist or denylist can restrict servers in three ways:

By server name (serverName): Matches the configured name of the server
By command (serverCommand): Matches the exact command and arguments used to start stdio servers
By URL pattern (serverUrl): Matches remote server URLs with wildcard support

Important: Each entry must have exactly one of serverName, serverCommand, or serverUrl.

Example configuration

{
  "allowedMcpServers": [
    // Allow by server name
    { "serverName": "github" },
    { "serverName": "sentry" },

    // Allow by exact command (for stdio servers)
    { "serverCommand": ["npx", "-y", "@modelcontextprotocol/server-filesystem"] },
    { "serverCommand": ["python", "/usr/local/bin/approved-server.py"] },

    // Allow by URL pattern (for remote servers)
    { "serverUrl": "https://mcp.company.com/*" },
    { "serverUrl": "https://*.internal.corp/*" }
  ],
  "deniedMcpServers": [
    // Block by server name
    { "serverName": "dangerous-server" },

    // Block by exact command (for stdio servers)
    { "serverCommand": ["npx", "-y", "unapproved-package"] },

    // Block by URL pattern (for remote servers)
    { "serverUrl": "https://*.untrusted.com/*" }
  ]
}

How command-based restrictions work

Exact matching:

Command arrays must match exactly - both the command and all arguments in the correct order
Example: ["npx", "-y", "server"] will NOT match ["npx", "server"] or ["npx", "-y", "server", "--flag"]

Stdio server behavior:

When the allowlist contains any serverCommand entries, stdio servers must match one of those commands
Stdio servers cannot pass by name alone when command restrictions are present
This ensures administrators can enforce which commands are allowed to run

Non-stdio server behavior:

Remote servers (HTTP, SSE, WebSocket) use URL-based matching when serverUrl entries exist in the allowlist
If no URL entries exist, remote servers fall back to name-based matching
Command restrictions do not apply to remote servers

How URL-based restrictions work

URL patterns support wildcards using * to match any sequence of characters. This is useful for allowing entire domains or subdomains.

Wildcard examples:

https://mcp.company.com/* - Allow all paths on a specific domain
https://*.example.com/* - Allow any subdomain of example.com
http://localhost:*/* - Allow any port on localhost

Remote server behavior:

When the allowlist contains any serverUrl entries, remote servers must match one of those URL patterns
Remote servers cannot pass by name alone when URL restrictions are present
This ensures administrators can enforce which remote endpoints are allowed

Example: URL-only allowlist

{
"allowedMcpServers": [
{ "serverUrl": "https://mcp.company.com/*" },
{ "serverUrl": "https://*.internal.corp/*" }
]
}

Result:

HTTP server at https://mcp.company.com/api: ✅ Allowed (matches URL pattern)
HTTP server at https://api.internal.corp/mcp: ✅ Allowed (matches wildcard subdomain)
HTTP server at https://external.com/mcp: ❌ Blocked (doesn't match any URL pattern)
Stdio server with any command: ❌ Blocked (no name or command entries to match)

Example: Command-only allowlist

{
"allowedMcpServers": [
{ "serverCommand": ["npx", "-y", "approved-package"] }
]
}

Result:

Stdio server with ["npx", "-y", "approved-package"]: ✅ Allowed (matches command)
Stdio server with ["node", "server.js"]: ❌ Blocked (doesn't match command)
HTTP server named "my-api": ❌ Blocked (no name entries to match)

Example: Mixed name and command allowlist

{
"allowedMcpServers": [
{ "serverName": "github" },
{ "serverCommand": ["npx", "-y", "approved-package"] }
]
}

Result:

Stdio server named "local-tool" with ["npx", "-y", "approved-package"]: ✅ Allowed (matches command)
Stdio server named "local-tool" with ["node", "server.js"]: ❌ Blocked (command entries exist but doesn't match)
Stdio server named "github" with ["node", "server.js"]: ❌ Blocked (stdio servers must match commands when command entries exist)
HTTP server named "github": ✅ Allowed (matches name)
HTTP server named "other-api": ❌ Blocked (name doesn't match)

Example: Name-only allowlist

{
"allowedMcpServers": [
{ "serverName": "github" },
{ "serverName": "internal-tool" }
]
}

Result:

Stdio server named "github" with any command: ✅ Allowed (no command restrictions)
Stdio server named "internal-tool" with any command: ✅ Allowed (no command restrictions)
HTTP server named "github": ✅ Allowed (matches name)
Any server named "other": ❌ Blocked (name doesn't match)

Allowlist behavior (`allowedMcpServers`)

undefined (default): No restrictions - users can configure any MCP server
Empty array []: Complete lockdown - users cannot configure any MCP servers
List of entries: Users can only configure servers that match by name, command, or URL pattern

Denylist behavior (`deniedMcpServers`)

undefined (default): No servers are blocked
Empty array []: No servers are blocked
List of entries: Specified servers are explicitly blocked across all scopes

Important notes

Option 1 and Option 2 can be combined: If managed-mcp.json exists, it has exclusive control and users cannot add servers. Allowlists/denylists still apply to the enterprise servers themselves.
Denylist takes absolute precedence: If a server matches a denylist entry (by name, command, or URL), it will be blocked even if it's on the allowlist
Name-based, command-based, and URL-based restrictions work together: a server passes if it matches either a name entry, a command entry, or a URL pattern (unless blocked by denylist)

To find navigation and other pages in this documentation, fetch the llms.txt file at: https://code.claude.com/docs/llms.txt

mcp.md +70 −16

833 833

834## Enterprise MCP configuration834## Enterprise MCP configuration

835 835

836For organizations that need centralized control over MCP servers, Claude Code supports enterprise-managed MCP configurations. This allows IT administrators to:836For organizations that need centralized control over MCP servers, Claude Code supports two enterprise configuration options:

837

8381. **Exclusive control with `managed-mcp.json`**: Deploy a fixed set of MCP servers that users cannot modify or extend

8392. **Policy-based control with allowlists/denylists**: Allow users to add their own servers, but restrict which ones are permitted

840

841These options allow IT administrators to:

837 842

838* **Control which MCP servers employees can access**: Deploy a standardized set of approved MCP servers across the organization843* **Control which MCP servers employees can access**: Deploy a standardized set of approved MCP servers across the organization

839* **Prevent unauthorized MCP servers**: Optionally restrict users from adding their own MCP servers844* **Prevent unauthorized MCP servers**: Restrict users from adding unapproved MCP servers

840* **Disable MCP entirely**: Remove MCP functionality completely if needed845* **Disable MCP entirely**: Remove MCP functionality completely if needed

841 846

842### Setting up enterprise MCP configuration847### Option 1: Exclusive control with managed-mcp.json

843 848

844System administrators deploy an enterprise MCP configuration file to a system-wide directory:849When you deploy a `managed-mcp.json` file, it takes **exclusive control** over all MCP servers. Users cannot add, modify, or use any MCP servers other than those defined in this file. This is the simplest approach for organizations that want complete control.

850

851System administrators deploy the configuration file to a system-wide directory:

845 852

846* macOS: `/Library/Application Support/ClaudeCode/managed-mcp.json`853* macOS: `/Library/Application Support/ClaudeCode/managed-mcp.json`

847* Linux and WSL: `/etc/claude-code/managed-mcp.json`854* Linux and WSL: `/etc/claude-code/managed-mcp.json`

876}883}

877```884```

878 885

879### Restricting MCP servers with allowlists and denylists886### Option 2: Policy-based control with allowlists and denylists

880 887

881In addition to providing enterprise-managed servers, administrators can control which MCP servers users are allowed to configure using `allowedMcpServers` and `deniedMcpServers` in the [managed settings file](/en/settings#settings-files):888Instead of taking exclusive control, administrators can allow users to configure their own MCP servers while enforcing restrictions on which servers are permitted. This approach uses `allowedMcpServers` and `deniedMcpServers` in the [managed settings file](/en/settings#settings-files).

889

890<Note>

891 **Choosing between options**: Use Option 1 (`managed-mcp.json`) when you want to deploy a fixed set of servers with no user customization. Use Option 2 (allowlists/denylists) when you want to allow users to add their own servers within policy constraints.

892</Note>

882 893

883#### Restriction options894#### Restriction options

884 895

885Each entry in the allowlist or denylist can restrict servers in two ways:896Each entry in the allowlist or denylist can restrict servers in three ways:

886 897

8871. **By server name** (`serverName`): Matches the configured name of the server8981. **By server name** (`serverName`): Matches the configured name of the server

8882. **By command** (`serverCommand`): Matches the exact command and arguments used to start stdio servers8992. **By command** (`serverCommand`): Matches the exact command and arguments used to start stdio servers

9003. **By URL pattern** (`serverUrl`): Matches remote server URLs with wildcard support

889 901

890**Important**: Each entry must have **either** `serverName` **or** `serverCommand`, not both.902**Important**: Each entry must have exactly one of `serverName`, `serverCommand`, or `serverUrl`.

891 903

892#### Example configuration904#### Example configuration

893 905

900 912

901 // Allow by exact command (for stdio servers)913 // Allow by exact command (for stdio servers)

902 { "serverCommand": ["npx", "-y", "@modelcontextprotocol/server-filesystem"] },914 { "serverCommand": ["npx", "-y", "@modelcontextprotocol/server-filesystem"] },

903 { "serverCommand": ["python", "/usr/local/bin/approved-server.py"] }915 { "serverCommand": ["python", "/usr/local/bin/approved-server.py"] },

916

917 // Allow by URL pattern (for remote servers)

918 { "serverUrl": "https://mcp.company.com/*" },

919 { "serverUrl": "https://*.internal.corp/*" }

904 ],920 ],

905 "deniedMcpServers": [921 "deniedMcpServers": [

906 // Block by server name922 // Block by server name

907 { "serverName": "dangerous-server" },923 { "serverName": "dangerous-server" },

908 924

909 // Block by exact command (for stdio servers)925 // Block by exact command (for stdio servers)

910 { "serverCommand": ["npx", "-y", "unapproved-package"] }926 { "serverCommand": ["npx", "-y", "unapproved-package"] },

927

928 // Block by URL pattern (for remote servers)

929 { "serverUrl": "https://*.untrusted.com/*" }

911 ]930 ]

912}931}

913```932```

927 946

928**Non-stdio server behavior**:947**Non-stdio server behavior**:

929 948

930* Remote servers (HTTP, SSE, WebSocket) always match by name only949* Remote servers (HTTP, SSE, WebSocket) use URL-based matching when `serverUrl` entries exist in the allowlist

950* If no URL entries exist, remote servers fall back to name-based matching

931* Command restrictions do not apply to remote servers951* Command restrictions do not apply to remote servers

932 952

953#### How URL-based restrictions work

954

955URL patterns support wildcards using `*` to match any sequence of characters. This is useful for allowing entire domains or subdomains.

956

957**Wildcard examples**:

958

959* `https://mcp.company.com/*` - Allow all paths on a specific domain

960* `https://*.example.com/*` - Allow any subdomain of example.com

961* `http://localhost:*/*` - Allow any port on localhost

962

963**Remote server behavior**:

964

965* When the allowlist contains **any** `serverUrl` entries, remote servers **must** match one of those URL patterns

966* Remote servers cannot pass by name alone when URL restrictions are present

967* This ensures administrators can enforce which remote endpoints are allowed

968

969<Accordion title="Example: URL-only allowlist">

970 ```json theme={null}

971 {

972 "allowedMcpServers": [

973 { "serverUrl": "https://mcp.company.com/*" },

974 { "serverUrl": "https://*.internal.corp/*" }

975 ]

976 }

977 ```

978

979 **Result**:

980

981 * HTTP server at `https://mcp.company.com/api`: ✅ Allowed (matches URL pattern)

982 * HTTP server at `https://api.internal.corp/mcp`: ✅ Allowed (matches wildcard subdomain)

983 * HTTP server at `https://external.com/mcp`: ❌ Blocked (doesn't match any URL pattern)

984 * Stdio server with any command: ❌ Blocked (no name or command entries to match)

985</Accordion>

986

933<Accordion title="Example: Command-only allowlist">987<Accordion title="Example: Command-only allowlist">

934 ```json theme={null}988 ```json theme={null}

935 {989 {

987 1041

988* `undefined` (default): No restrictions - users can configure any MCP server1042* `undefined` (default): No restrictions - users can configure any MCP server

989* Empty array `[]`: Complete lockdown - users cannot configure any MCP servers1043* Empty array `[]`: Complete lockdown - users cannot configure any MCP servers

990* List of entries: Users can only configure servers that match by name or command1044* List of entries: Users can only configure servers that match by name, command, or URL pattern

991 1045

992#### Denylist behavior (`deniedMcpServers`)1046#### Denylist behavior (`deniedMcpServers`)

993 1047

997 1051

998#### Important notes1052#### Important notes

999 1053

1000* These restrictions apply to all scopes: user, project, local, and even enterprise servers from `managed-mcp.json`1054* **Option 1 and Option 2 can be combined**: If `managed-mcp.json` exists, it has exclusive control and users cannot add servers. Allowlists/denylists still apply to the enterprise servers themselves.

1001* **Denylist takes absolute precedence**: If a server matches a denylist entry (by name or command), it will be blocked even if it's on the allowlist1055* **Denylist takes absolute precedence**: If a server matches a denylist entry (by name, command, or URL), it will be blocked even if it's on the allowlist

1002* Name-based and command-based restrictions work together: a server passes if it matches **either** a name entry **or** a command entry (unless blocked by denylist)1056* Name-based, command-based, and URL-based restrictions work together: a server passes if it matches **either** a name entry, a command entry, or a URL pattern (unless blocked by denylist)

1003 1057

1004<Note>1058<Note>

1005 **Enterprise configuration precedence**: The enterprise MCP configuration has the highest precedence and cannot be overridden by user, local, or project configurations.1059 **When using `managed-mcp.json`**: Users cannot add MCP servers through `claude mcp add` or configuration files. The `allowedMcpServers` and `deniedMcpServers` settings still apply to filter which enterprise servers are actually loaded.

1006</Note>1060</Note>

1007 1061

1008 1062

mcp.md 2025-12-18 21:01 UTC to 2025-12-19 21:01 UTC

Connect Claude Code to tools via MCP

What you can do with MCP

Popular MCP servers

Installing MCP servers

Option 1: Add a remote HTTP server

Option 2: Add a remote SSE server

Option 3: Add a local stdio server

Managing your servers

Plugin-provided MCP servers

MCP installation scopes

Local scope

Project scope

User scope

Choosing the right scope

Scope hierarchy and precedence

Environment variable expansion in .mcp.json

Practical examples

Example: Connect to GitHub for code reviews

Example: Query your PostgreSQL database

Authenticate with remote MCP servers

Add the server that requires authentication

Use the /mcp command within Claude Code

Add MCP servers from JSON configuration

Add an MCP server from JSON

Verify the server was added

Import MCP servers from Claude Desktop

Import servers from Claude Desktop

Select which servers to import

Verify the servers were imported

Use Claude Code as an MCP server

MCP output limits and warnings

Use MCP resources

Reference MCP resources

List available resources

Reference a specific resource

Multiple resource references

Use MCP prompts as slash commands

Execute MCP prompts

Discover available prompts

Execute a prompt without arguments

Execute a prompt with arguments

Enterprise MCP configuration

Option 1: Exclusive control with managed-mcp.json

Option 2: Policy-based control with allowlists and denylists

Restriction options

Example configuration

How command-based restrictions work

How URL-based restrictions work

Allowlist behavior (allowedMcpServers)

Denylist behavior (deniedMcpServers)

Important notes

Environment variable expansion in `.mcp.json`

Allowlist behavior (`allowedMcpServers`)

Denylist behavior (`deniedMcpServers`)