通过 MCP 将 Claude Code 连接到工具

了解如何使用 Model Context Protocol 将 Claude Code 连接到您的工具。

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('visibility', 'commercial'); 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 remotes = server.remotes || []; const httpRemote = remotes.find(r => r.type === 'streamable-http'); const sseRemote = remotes.find(r => r.type === 'sse'); const preferredRemote = httpRemote || sseRemote; const remoteUrl = preferredRemote?.url || meta.url; const remoteType = preferredRemote?.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.replace('--transport streamable-http', '--transport http'); } 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 可以通过 Model Context Protocol (MCP)（一个用于 AI 工具集成的开源标准）连接到数百个外部工具和数据源。MCP 服务器为 Claude Code 提供对您的工具、数据库和 API 的访问权限。

当您发现自己从另一个工具（如问题跟踪器或监控仪表板）复制数据到聊天中时，请连接一个服务器。连接后，Claude 可以直接读取和操作该系统，而不是从您粘贴的内容中工作。

使用 MCP 可以做什么

连接 MCP 服务器后，您可以要求 Claude Code：

从问题跟踪器实现功能："添加 JIRA 问题 ENG-4521 中描述的功能，并在 GitHub 上创建 PR。"
分析监控数据："检查 Sentry 和 Statsig 以检查 ENG-4521 中描述的功能的使用情况。"
查询数据库："根据我们的 PostgreSQL 数据库，查找使用功能 ENG-4521 的 10 个随机用户的电子邮件。"
集成设计："根据在 Slack 中发布的新 Figma 设计更新我们的标准电子邮件模板"
自动化工作流："创建 Gmail 草稿，邀请这 10 个用户参加关于新功能的反馈会议。"
对外部事件做出反应：MCP 服务器也可以充当频道，将消息推送到您的会话中，因此当您不在时，Claude 可以对 Telegram 消息、Discord 聊天或 webhook 事件做出反应。

流行的 MCP 服务器

以下是一些您可以连接到 Claude Code 的常用 MCP 服务器：

安装 MCP 服务器

MCP 服务器可以根据您的需求以三种不同的方式进行配置：

选项 1：添加远程 HTTP 服务器

HTTP 服务器是连接到远程 MCP 服务器的推荐选项。这是云服务最广泛支持的传输方式。

# 基本语法
claude mcp add --transport http <name> <url>

# 真实示例：连接到 Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

# 带有 Bearer 令牌的示例
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

在通过 .mcp.json、~/.claude.json 或 claude mcp add-json 中的 JSON 配置 MCP 服务器时，type 字段接受 streamable-http 作为 http 的别名。MCP 规范对此传输使用名称 streamable-http，因此从服务器文档复制的配置无需修改即可工作。

选项 2：添加远程 SSE 服务器

# 基本语法
claude mcp add --transport sse <name> <url>

# 真实示例：连接到 Asana
claude mcp add --transport sse asana https://mcp.asana.com/sse

# 带有身份验证标头的示例
claude mcp add --transport sse private-api https://api.company.com/sse \
  --header "X-API-Key: your-key-here"

选项 3：添加本地 stdio 服务器

Stdio 服务器作为您机器上的本地进程运行。它们非常适合需要直接系统访问或自定义脚本的工具。

# 基本语法
claude mcp add [options] <name> -- <command> [args...]

# 真实示例：添加 Airtable 服务器
claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \
  -- npx -y airtable-mcp-server

管理您的服务器

配置后，您可以使用这些命令管理您的 MCP 服务器：

# 列出所有配置的服务器
claude mcp list

# 获取特定服务器的详细信息
claude mcp get github

# 删除服务器
claude mcp remove github

# （在 Claude Code 中）检查服务器状态
/mcp

/mcp 面板在每个连接的服务器旁边显示工具计数，并标记声称工具功能但未公开任何工具的服务器。

服务器名称 workspace 保留供内部使用。如果您的配置定义了具有该名称的服务器，Claude Code 会在加载时跳过它，并显示一条警告，要求您重命名它。

动态工具更新

Claude Code 支持 MCP list_changed 通知，允许 MCP 服务器动态更新其可用工具、提示和资源，而无需您断开连接并重新连接。当 MCP 服务器发送 list_changed 通知时，Claude Code 会自动刷新来自该服务器的可用功能。

自动重新连接

如果 HTTP 或 SSE 服务器在会话中途断开连接，Claude Code 会自动以指数退避方式重新连接：最多五次尝试，从一秒延迟开始，每次加倍。服务器在 /mcp 中显示为待处理状态，同时重新连接正在进行中。五次失败尝试后，服务器被标记为失败，您可以从 /mcp 手动重试。Stdio 服务器是本地进程，不会自动重新连接。

相同的退避策略也适用于 HTTP 或 SSE 服务器在启动时初始连接失败的情况。从 v2.1.121 开始，Claude Code 在瞬时错误（如 5xx 响应、连接被拒绝或超时）上最多重试初始连接三次，如果仍然无法连接，则将服务器标记为失败。身份验证和未找到错误不会重试，因为它们需要配置更改才能解决。

使用频道推送消息

MCP 服务器也可以直接将消息推送到您的会话中，以便 Claude 可以对外部事件（如 CI 结果、监控警报或聊天消息）做出反应。要启用此功能，您的服务器声明 claude/channel 功能，并在启动时使用 --channels 标志选择加入。请参阅 Channels 以使用官方支持的频道，或 Channels reference 以构建您自己的频道。

插件提供的 MCP 服务器

Plugins 可以捆绑 MCP 服务器，在启用插件时自动提供工具和集成。插件 MCP 服务器的工作方式与用户配置的服务器相同。

插件 MCP 服务器的工作原理：

插件在插件根目录的 .mcp.json 中或在 plugin.json 中内联定义 MCP 服务器
启用插件时，其 MCP 服务器会自动启动
插件 MCP 工具与手动配置的 MCP 工具一起出现
插件服务器通过插件安装进行管理（不是 /mcp 命令）

示例插件 MCP 配置：

在插件根目录的 .mcp.json 中：

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

或在 plugin.json 中内联：

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

插件 MCP 功能：

自动生命周期：在会话启动时，启用的插件的服务器会自动连接。如果您在会话期间启用或禁用插件，请运行 /reload-plugins 以连接或断开其 MCP 服务器
环境变量：对插件相对路径使用 ${CLAUDE_PLUGIN_ROOT}，对持久状态使用 ${CLAUDE_PLUGIN_DATA}，该状态在插件更新后仍然存在
用户环境访问：访问与手动配置的服务器相同的环境变量
多种传输类型：支持 stdio、SSE 和 HTTP 传输（传输支持可能因服务器而异）

查看插件 MCP 服务器：

# 在 Claude Code 中，查看所有 MCP 服务器，包括插件服务器
/mcp

插件服务器在列表中出现，并带有指示它们来自插件的指示符。

插件 MCP 服务器的优势：

捆绑分发：工具和服务器打包在一起
自动设置：无需手动 MCP 配置
团队一致性：安装插件时每个人都获得相同的工具

有关使用插件捆绑 MCP 服务器的详细信息，请参阅插件组件参考。

MCP 安装范围

MCP 服务器可以在三个不同的范围级别进行配置。您选择的范围控制服务器在哪些项目中加载以及配置是否与您的团队共享。管理员还可以通过托管配置在企业级别部署服务器。

范围	加载位置	与团队共享	存储位置
本地	仅当前项目	否	`~/.claude.json`
项目	仅当前项目	是，通过版本控制	项目根目录中的 `.mcp.json`
用户	您的所有项目	否	`~/.claude.json`

本地范围

本地范围是默认范围。本地范围的服务器仅在您添加它的项目中加载，并对您保持私密。Claude Code 将其存储在 ~/.claude.json 中该项目的路径下，因此相同的服务器不会出现在您的其他项目中。对个人开发服务器、实验配置或包含您不想在版本控制中的凭据的服务器使用本地范围。

# 添加本地范围的服务器（默认）
claude mcp add --transport http stripe https://mcp.stripe.com

# 显式指定本地范围
claude mcp add --transport http stripe --scope local https://mcp.stripe.com

该命令将服务器写入 ~/.claude.json 中您当前项目的条目。下面的示例显示从 /path/to/your/project 运行时的结果：

{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "stripe": {
          "type": "http",
          "url": "https://mcp.stripe.com"
        }
      }
    }
  }
}

项目范围

项目范围的服务器通过在项目根目录中存储配置在 .mcp.json 文件中来启用团队协作。此文件设计为检入版本控制，确保所有团队成员都可以访问相同的 MCP 工具和服务。添加项目范围的服务器时，Claude Code 会自动创建或更新此文件，使用适当的配置结构。

# 添加项目范围的服务器
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

生成的 .mcp.json 文件遵循标准化格式：

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

出于安全原因，Claude Code 在使用来自 .mcp.json 文件的项目范围的服务器之前会提示批准。如果您需要重置这些批准选择，请使用 claude mcp reset-project-choices 命令。

用户范围

用户范围的服务器存储在 ~/.claude.json 中，并提供跨项目可访问性，使其在您机器上的所有项目中可用，同时对您的用户帐户保持私密。此范围适用于个人实用程序服务器、开发工具或您在不同项目中经常使用的服务。

# 添加用户服务器
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

范围层次结构和优先级

当具有相同名称的服务器在多个位置定义时，Claude Code 连接到它一次，使用来自最高优先级源的定义：

本地范围
项目范围
用户范围
插件提供的服务器
claude.ai 连接器

三个范围按名称匹配重复项。插件和连接器按端点匹配，因此指向与上述服务器相同的 URL 或命令的连接器被视为重复项。

`.mcp.json` 中的环境变量扩展

Claude Code 支持 .mcp.json 文件中的环境变量扩展，允许团队共享配置，同时为特定于机器的路径和 API 密钥等敏感值保持灵活性。

支持的语法：

${VAR} - 扩展为环境变量 VAR 的值
${VAR:-default} - 如果设置了 VAR，则扩展为 VAR，否则使用 default

扩展位置： 环境变量可以在以下位置扩展：

command - 服务器可执行文件路径
args - 命令行参数
env - 传递给服务器的环境变量
url - 对于 HTTP 服务器类型
headers - 对于 HTTP 服务器身份验证

带有变量扩展的示例：

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

如果未设置所需的环境变量且没有默认值，Claude Code 将无法解析配置。

实际示例

{/* ### 示例：使用 Playwright 自动化浏览器测试

claude mcp add --transport stdio playwright -- npx -y @playwright/mcp@latest

然后编写并运行浏览器测试：

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
``` */}

### 示例：使用 Sentry 监控错误

```bash theme={null}
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

使用您的 Sentry 帐户进行身份验证：

/mcp

然后调试生产问题：

过去 24 小时内最常见的错误是什么？

显示我错误 ID abc123 的堆栈跟踪

哪个部署引入了这些新错误？

示例：连接到 GitHub 进行代码审查

GitHub 的远程 MCP 服务器使用作为标头传递的 GitHub 个人访问令牌进行身份验证。要获取一个，请打开您的 GitHub 令牌设置，生成一个新的细粒度令牌，具有对您希望 Claude 使用的存储库的访问权限，然后添加服务器：

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

然后使用 GitHub：

审查 PR #456 并建议改进

为我们刚发现的错误创建新问题

显示分配给我的所有开放 PR

示例：查询您的 PostgreSQL 数据库

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

然后自然地查询您的数据库：

本月我们的总收入是多少？

显示订单表的架构

查找 90 天内未进行购买的客户

使用远程 MCP 服务器进行身份验证

许多基于云的 MCP 服务器需要身份验证。Claude Code 支持 OAuth 2.0 以实现安全连接。

添加需要身份验证的服务器

例如：

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

在 Claude Code 中使用 /mcp 命令

在 Claude Code 中，使用命令：

/mcp

然后按照浏览器中的步骤登录。

使用固定的 OAuth 回调端口

某些 MCP 服务器需要预先注册的特定重定向 URI。默认情况下，Claude Code 为 OAuth 回调选择随机可用端口。使用 --callback-port 固定端口，使其与 http://localhost:PORT/callback 形式的预注册重定向 URI 匹配。

您可以单独使用 --callback-port（使用动态客户端注册）或与 --client-id 一起使用（使用预配置的凭据）。

# 使用动态客户端注册的固定回调端口
claude mcp add --transport http \
  --callback-port 8080 \
  my-server https://mcp.example.com/mcp

使用预配置的 OAuth 凭据

某些 MCP 服务器不支持通过动态客户端注册进行自动 OAuth 设置。如果您看到类似"不兼容的身份验证服务器：不支持动态客户端注册"的错误，服务器需要预配置的凭据。Claude Code 也支持使用客户端 ID 元数据文档 (CIMD) 而不是动态客户端注册的服务器，并自动发现这些服务器。如果自动发现失败，请首先通过服务器的开发者门户注册 OAuth 应用，然后在添加服务器时提供凭据。

使用服务器注册 OAuth 应用

通过服务器的开发者门户创建应用，并记下您的客户端 ID 和客户端密钥。

许多服务器还需要重定向 URI。如果是这样，请选择一个端口并以 http://localhost:PORT/callback 的格式注册重定向 URI。在下一步中使用该相同的端口与 --callback-port。

使用您的凭据添加服务器

选择以下方法之一。用于 --callback-port 的端口可以是任何可用的端口。它只需要与您在上一步中注册的重定向 URI 匹配。

使用 --client-id 传递您的应用的客户端 ID。--client-secret 标志使用掩盖的输入提示输入密钥：

claude mcp add --transport http \
--client-id your-client-id --client-secret --callback-port 8080 \
my-server https://mcp.example.com/mcp

在 JSON 配置中包含 oauth 对象，并将 --client-secret 作为单独的标志传递：

claude mcp add-json my-server \
'{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' \
--client-secret

使用 --callback-port 而不使用客户端 ID 来固定端口，同时使用动态客户端注册：

claude mcp add-json my-server \
'{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"callbackPort":8080}}'

通过环境变量设置密钥以跳过交互式提示：

MCP_CLIENT_SECRET=your-secret claude mcp add --transport http \
--client-id your-client-id --client-secret --callback-port 8080 \
my-server https://mcp.example.com/mcp

在 Claude Code 中进行身份验证

在 Claude Code 中运行 /mcp 并按照浏览器登录流程。

覆盖 OAuth 元数据发现

指向 Claude Code 一个特定的 OAuth 授权服务器元数据 URL 以绕过默认发现链。当 MCP 服务器的标准端点出错时，或当您想通过内部代理路由发现时，设置 authServerMetadataUrl。默认情况下，Claude Code 首先检查 RFC 9728 受保护资源元数据（位于 /.well-known/oauth-protected-resource），然后回退到 RFC 8414 授权服务器元数据（位于 /.well-known/oauth-authorization-server）。

在您的服务器配置中的 .mcp.json 的 oauth 对象中设置 authServerMetadataUrl：

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "authServerMetadataUrl": "https://auth.example.com/.well-known/openid-configuration"
      }
    }
  }
}

URL 必须使用 https://。authServerMetadataUrl 需要 Claude Code v2.1.64 或更高版本。元数据 URL 的 scopes_supported 覆盖上游服务器公开的范围。

限制 OAuth 范围

设置 oauth.scopes 以固定 Claude Code 在授权流程中请求的范围。这是限制 MCP 服务器到安全团队批准的子集的支持方式，当上游授权服务器公开的范围超过您想要授予的范围时。该值是单个空格分隔的字符串，与 RFC 6749 §3.3 中的 scope 参数格式匹配。

{
  "mcpServers": {
    "slack": {
      "type": "http",
      "url": "https://mcp.slack.com/mcp",
      "oauth": {
        "scopes": "channels:read chat:write search:read"
      }
    }
  }
}

oauth.scopes 优先于 authServerMetadataUrl 和服务器在 /.well-known 发现的范围。将其保留未设置以让 MCP 服务器确定请求的范围集。

如果授权服务器在 scopes_supported 中公开 offline_access，Claude Code 会将其附加到固定范围，以便可以在没有新浏览器登录的情况下刷新访问令牌。

如果服务器稍后为工具调用返回 403 insufficient_scope，Claude Code 会使用相同的固定范围重新进行身份验证。当您需要的工具需要固定范围之外的范围时，扩展 oauth.scopes。

使用动态标头进行自定义身份验证

如果您的 MCP 服务器使用 OAuth 以外的身份验证方案（例如 Kerberos、短期令牌或内部 SSO），请使用 headersHelper 在连接时生成请求标头。Claude Code 运行命令并将其输出合并到连接标头中。

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "/opt/bin/get-mcp-auth-headers.sh"
    }
  }
}

命令也可以是内联的：

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "echo '{\"Authorization\": \"Bearer '\"$(get-token)\"'\"}'"
    }
  }
}

要求：

命令必须将字符串键值对的 JSON 对象写入标准输出
命令在 shell 中运行，超时时间为 10 秒
动态标头覆盖任何具有相同名称的静态 headers

助手在每次连接时运行（在会话启动和重新连接时）。没有缓存，因此您的脚本负责任何令牌重用。

Claude Code 在执行助手时设置这些环境变量：

变量	值
`CLAUDE_CODE_MCP_SERVER_NAME`	MCP 服务器的名称
`CLAUDE_CODE_MCP_SERVER_URL`	MCP 服务器的 URL

使用这些来编写一个为多个 MCP 服务器服务的单个助手脚本。

从 JSON 配置添加 MCP 服务器

如果您有 MCP 服务器的 JSON 配置，您可以直接添加它：

从 JSON 添加 MCP 服务器

# 基本语法
claude mcp add-json <name> '<json>'

# 示例：添加带有 JSON 配置的 HTTP 服务器
claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

# 示例：添加带有 JSON 配置的 stdio 服务器
claude mcp add-json local-weather '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'

# 示例：添加带有预配置 OAuth 凭据的 HTTP 服务器
claude mcp add-json my-server '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' --client-secret

验证服务器已添加

claude mcp get weather-api

从 Claude Desktop 导入 MCP 服务器

如果您已在 Claude Desktop 中配置了 MCP 服务器，您可以导入它们：

从 Claude Desktop 导入服务器

# 基本语法 
claude mcp add-from-claude-desktop

选择要导入的服务器

运行命令后，您将看到一个交互式对话框，允许您选择要导入的服务器。

验证服务器已导入

claude mcp list

使用来自 Claude.ai 的 MCP 服务器

如果您已使用 Claude.ai 帐户登录 Claude Code，您在 Claude.ai 中添加的 MCP 服务器会自动在 Claude Code 中可用：

在 Claude.ai 中配置 MCP 服务器

在 claude.ai/customize/connectors 添加服务器。在 Team 和 Enterprise 计划上，仅管理员可以添加服务器。

对 MCP 服务器进行身份验证

在 Claude.ai 中完成任何必需的身份验证步骤。

在 Claude Code 中查看和管理服务器

在 Claude Code 中，使用命令：

/mcp

Claude.ai 服务器在列表中出现，并带有指示它们来自 Claude.ai 的指示符。

您在 Claude Code 中添加的服务器优先于指向相同 URL 的 claude.ai 连接器。发生这种情况时，/mcp 会将连接器列为隐藏，并显示如何删除重复项（如果您更希望使用连接器）。

要在 Claude Code 中禁用 claude.ai MCP 服务器，请将 ENABLE_CLAUDEAI_MCP_SERVERS 环境变量设置为 false：

ENABLE_CLAUDEAI_MCP_SERVERS=false claude

将 Claude Code 用作 MCP 服务器

您可以将 Claude Code 本身用作 MCP 服务器，其他应用程序可以连接到它：

# 启动 Claude 作为 stdio MCP 服务器
claude mcp serve

您可以通过将此配置添加到 claude_desktop_config.json 在 Claude Desktop 中使用它：

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

Warning

配置可执行文件路径：command 字段必须引用 Claude Code 可执行文件。如果 claude 命令不在您的系统 PATH 中，您需要指定可执行文件的完整路径。

要查找完整路径：

which claude

然后在您的配置中使用完整路径：

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

没有正确的可执行文件路径，您会遇到类似 spawn claude ENOENT 的错误。

MCP 输出限制和警告

当 MCP 工具产生大量输出时，Claude Code 可帮助管理令牌使用情况，以防止压倒您的对话上下文：

输出警告阈值：当任何 MCP 工具输出超过 10,000 个令牌时，Claude Code 显示警告
可配置限制：您可以使用 MAX_MCP_OUTPUT_TOKENS 环境变量调整最大允许的 MCP 输出令牌
默认限制：默认最大值为 25,000 个令牌
范围：环境变量适用于不声明自己限制的工具。声明 anthropic/maxResultSizeChars 的工具对文本内容使用该值，无论 MAX_MCP_OUTPUT_TOKENS 设置为什么。返回图像数据的工具仍受 MAX_MCP_OUTPUT_TOKENS 限制

要为产生大量输出的工具增加限制：

export MAX_MCP_OUTPUT_TOKENS=50000
claude

这在使用以下 MCP 服务器时特别有用：

查询大型数据集或数据库
生成详细的报告或文档
处理广泛的日志文件或调试信息

为特定工具提高限制

如果您正在构建 MCP 服务器，您可以通过在工具的 tools/list 响应条目中设置 _meta["anthropic/maxResultSizeChars"] 来允许单个工具返回大于默认持久化到磁盘阈值的结果。Claude Code 将该工具的阈值提高到注释值，最高为 500,000 个字符的硬上限。

这对于返回本质上很大但必要的输出的工具很有用，例如数据库架构或完整文件树。没有注释，超过默认阈值的结果会被持久化到磁盘，并在对话中被文件引用替换。

{
  "name": "get_schema",
  "description": "Returns the full database schema",
  "_meta": {
    "anthropic/maxResultSizeChars": 200000
  }
}

对于文本内容，注释独立于 MAX_MCP_OUTPUT_TOKENS 应用，因此用户不需要为声明它的工具提高环境变量。返回图像数据的工具仍受令牌限制。

响应 MCP 引发请求

MCP 服务器可以在任务中途使用引发来请求您的结构化输入。当服务器需要无法自行获取的信息时，Claude Code 会显示交互式对话框并将您的响应传递回服务器。您无需进行任何配置：当服务器请求时，引发对话框会自动出现。

服务器可以通过两种方式请求输入：

表单模式：Claude Code 显示一个对话框，其中包含服务器定义的表单字段（例如，用户名和密码提示）。填写字段并提交。
URL 模式：Claude Code 打开浏览器 URL 以进行身份验证或批准。在浏览器中完成流程，然后在 CLI 中确认。

要自动响应引发请求而不显示对话框，请使用 Elicitation hook。

如果您正在构建使用引发的 MCP 服务器，请参阅 MCP 引发规范以了解协议详细信息和架构示例。

使用 MCP 资源

MCP 服务器可以公开资源，您可以使用 @ 提及来引用，类似于您引用文件的方式。

引用 MCP 资源

列出可用资源

在您的提示中键入 @ 以查看来自所有连接的 MCP 服务器的可用资源。资源与文件一起出现在自动完成菜单中。

引用特定资源

使用格式 @server:protocol://resource/path 来引用资源：

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

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

多个资源引用

您可以在单个提示中引用多个资源：

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

使用 MCP 工具搜索进行扩展

工具搜索通过延迟工具定义直到 Claude 需要它们来保持 MCP 上下文使用低。仅工具名称在会话启动时加载，因此添加更多 MCP 服务器对您的上下文窗口的影响最小。

工作原理

工具搜索默认启用。MCP 工具被延迟而不是预先加载到上下文中，Claude 使用搜索工具在任务需要时发现相关的工具。仅 Claude 实际使用的工具进入上下文。从您的角度来看，MCP 工具的工作方式与之前完全相同。

如果您更喜欢基于阈值的加载，请设置 ENABLE_TOOL_SEARCH=auto 以在工具适合上下文窗口的 10% 内时预先加载架构，仅延迟溢出部分。有关所有选项，请参阅配置工具搜索。

对于 MCP 服务器作者

如果您正在构建 MCP 服务器，启用工具搜索时服务器说明字段会变得更有用。服务器说明可帮助 Claude 了解何时搜索您的工具，类似于 skills 的工作方式。

添加清晰、描述性的服务器说明，说明：

您的工具处理的任务类别
Claude 应何时搜索您的工具
您的服务器提供的关键功能

Claude Code 将工具描述和服务器说明截断为每个 2KB。保持它们简洁以避免截断，并将关键详细信息放在开头。

配置工具搜索

工具搜索默认启用：MCP 工具被延迟并按需发现。在 Vertex AI 上默认禁用，它不接受工具搜索 beta 标头，以及当 ANTHROPIC_BASE_URL 指向非第一方主机时，因为大多数代理不转发 tool_reference 块。显式设置 ENABLE_TOOL_SEARCH 以选择加入。此功能需要支持 tool_reference 块的模型：Sonnet 4 及更高版本，或 Opus 4 及更高版本。Haiku 模型不支持工具搜索。

使用 ENABLE_TOOL_SEARCH 环境变量控制工具搜索行为：

值	行为
（未设置）	所有 MCP 工具被延迟并按需加载。在 Vertex AI 上或当 `ANTHROPIC_BASE_URL` 是非第一方主机时回退到预先加载
`true`	所有 MCP 工具被延迟，包括在 Vertex AI 上和对于非第一方 `ANTHROPIC_BASE_URL`
`auto`	阈值模式：如果工具适合上下文窗口的 10% 内，则预先加载，否则延迟
`auto:<N>`	阈值模式，带有自定义百分比，其中 `<N>` 是 0-100（例如，`auto:5` 表示 5%）
`false`	所有 MCP 工具预先加载，无延迟

# 使用自定义 5% 阈值
ENABLE_TOOL_SEARCH=auto:5 claude

# 完全禁用工具搜索
ENABLE_TOOL_SEARCH=false claude

或在您的settings.json env 字段中设置值。

您也可以专门禁用 ToolSearch 工具：

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

豁免服务器延迟

如果服务器的工具应始终对 Claude 可见而无需搜索步骤，请在该服务器的配置中将 alwaysLoad 设置为 true。来自该服务器的每个工具随后在会话启动时加载到上下文中，无论 ENABLE_TOOL_SEARCH 设置如何。对于 Claude 在每个回合都需要的少量工具，请使用此选项，因为每个预先加载的工具会消耗本来可用于您的对话的上下文。

以下 .mcp.json 条目豁免一个 HTTP 服务器，同时保持其他服务器延迟：

{
  "mcpServers": {
    "core-tools": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "alwaysLoad": true
    }
  }
}

alwaysLoad 字段在所有服务器类型上可用，需要 Claude Code v2.1.121 或更高版本。MCP 服务器也可以通过在工具的 _meta 对象中包含 "anthropic/alwaysLoad": true 来标记单个工具为始终加载，这对该工具仅具有相同的效果。

设置 alwaysLoad: true 也会阻止启动直到服务器连接，上限为标准 5 秒连接超时。即使设置了 MCP_CONNECTION_NONBLOCKING=1，这也适用，因为工具必须在构建第一个提示时存在。当启用非阻塞时，其他服务器仍在后台连接。

将 MCP 提示用作命令

MCP 服务器可以公开在 Claude Code 中作为命令可用的提示。

执行 MCP 提示

发现可用的提示

键入 / 以查看所有可用的命令，包括来自 MCP 服务器的命令。MCP 提示以 /mcp__servername__promptname 的格式出现。

执行不带参数的提示

/mcp__github__list_prs

执行带参数的提示

许多提示接受参数。在命令后面用空格分隔传递它们：

/mcp__github__pr_review 456

/mcp__jira__create_issue "Bug in login flow" high

托管 MCP 配置

对于需要对 MCP 服务器进行集中控制的组织，Claude Code 支持两个配置选项：

使用 managed-mcp.json 的独占控制：部署用户无法修改或扩展的固定 MCP 服务器集
使用允许列表/拒绝列表的基于策略的控制：允许用户添加自己的服务器，但限制允许的服务器

这些选项允许 IT 管理员：

控制员工可以访问哪些 MCP 服务器：在整个组织中部署一组标准化的已批准 MCP 服务器
防止未授权的 MCP 服务器：限制用户添加未批准的 MCP 服务器
完全禁用 MCP：如果需要，完全删除 MCP 功能

选项 1：使用 managed-mcp.json 的独占控制

部署 managed-mcp.json 文件时，它对所有 MCP 服务器进行独占控制。用户无法添加、修改或使用此文件中定义的任何 MCP 服务器以外的任何 MCP 服务器。这是希望完全控制的组织的最简单方法。

系统管理员将配置文件部署到系统范围的目录：

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

managed-mcp.json 文件使用与标准 .mcp.json 文件相同的格式：

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

选项 2：使用允许列表和拒绝列表的基于策略的控制

管理员可以允许用户配置自己的 MCP 服务器，而不是进行独占控制，同时对允许的服务器进行限制。此方法在托管设置文件中使用 allowedMcpServers 和 deniedMcpServers。

限制选项

允许列表或拒绝列表中的每个条目可以通过三种方式限制服务器：

按服务器名称 (serverName)：匹配服务器的配置名称
按命令 (serverCommand)：匹配用于启动 stdio 服务器的确切命令和参数
按 URL 模式 (serverUrl)：匹配带有通配符支持的远程服务器 URL

重要：每个条目必须恰好具有 serverName、serverCommand 或 serverUrl 之一。

示例配置

{
  "allowedMcpServers": [
    // 按服务器名称允许
    { "serverName": "github" },
    { "serverName": "sentry" },

    // 按确切命令允许（对于 stdio 服务器）
    { "serverCommand": ["npx", "-y", "@modelcontextprotocol/server-filesystem"] },
    { "serverCommand": ["python", "/usr/local/bin/approved-server.py"] },

    // 按 URL 模式允许（对于远程服务器）
    { "serverUrl": "https://mcp.company.com/*" },
    { "serverUrl": "https://*.internal.corp/*" }
  ],
  "deniedMcpServers": [
    // 按服务器名称阻止
    { "serverName": "dangerous-server" },

    // 按确切命令阻止（对于 stdio 服务器）
    { "serverCommand": ["npx", "-y", "unapproved-package"] },

    // 按 URL 模式阻止（对于远程服务器）
    { "serverUrl": "https://*.untrusted.com/*" }
  ]
}

基于命令的限制如何工作

精确匹配：

命令数组必须精确匹配 - 命令和所有参数的顺序正确
示例：["npx", "-y", "server"] 将不匹配 ["npx", "server"] 或 ["npx", "-y", "server", "--flag"]

Stdio 服务器行为：

当允许列表包含任何 serverCommand 条目时，stdio 服务器必须匹配其中一个命令
Stdio 服务器在存在命令限制时无法仅按名称通过
这确保管理员可以强制执行允许运行哪些命令

非 stdio 服务器行为：

远程服务器（HTTP、SSE、WebSocket）在允许列表中存在 serverUrl 条目时使用基于 URL 的匹配
如果不存在 URL 条目，远程服务器回退到基于名称的匹配
命令限制不适用于远程服务器

基于 URL 的限制如何工作

URL 模式使用 * 支持通配符以匹配任何字符序列。这对于允许整个域或子域很有用。

通配符示例：

https://mcp.company.com/* - 允许特定域上的所有路径
https://*.example.com/* - 允许 example.com 的任何子域
http://localhost:*/* - 允许 localhost 上的任何端口

主机名匹配不区分大小写，忽略尾部 FQDN 点，匹配 DNS 语义。像 *://Mcp.Example.com/* 这样的模式匹配 https://mcp.example.com/api，https://mcp.example.com. 被视为与 https://mcp.example.com 相同。路径保持区分大小写。

远程服务器行为：

当允许列表包含任何 serverUrl 条目时，远程服务器必须匹配其中一个 URL 模式
远程服务器在存在 URL 限制时无法仅按名称通过
这确保管理员可以强制执行允许哪些远程端点

示例：仅 URL 允许列表

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

结果：

https://mcp.company.com/api 处的 HTTP 服务器：✅ 允许（匹配 URL 模式）
https://api.internal.corp/mcp 处的 HTTP 服务器：✅ 允许（匹配通配符子域）
https://external.com/mcp 处的 HTTP 服务器：❌ 阻止（不匹配任何 URL 模式）
任何命令的 Stdio 服务器：❌ 阻止（没有名称或命令条目可匹配）

示例：仅命令允许列表

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

结果：

带有 ["npx", "-y", "approved-package"] 的 Stdio 服务器：✅ 允许（匹配命令）
带有 ["node", "server.js"] 的 Stdio 服务器：❌ 阻止（不匹配命令）
名为"my-api"的 HTTP 服务器：❌ 阻止（没有名称条目可匹配）

示例：混合名称和命令允许列表

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

结果：

名为"local-tool"、带有 ["npx", "-y", "approved-package"] 的 Stdio 服务器：✅ 允许（匹配命令）
名为"local-tool"、带有 ["node", "server.js"] 的 Stdio 服务器：❌ 阻止（命令条目存在但不匹配）
名为"github"、带有 ["node", "server.js"] 的 Stdio 服务器：❌ 阻止（当命令条目存在时，stdio 服务器必须匹配命令）
名为"github"的 HTTP 服务器：✅ 允许（匹配名称）
名为"other-api"的 HTTP 服务器：❌ 阻止（名称不匹配）

示例：仅名称允许列表

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

结果：

名为"github"、任何命令的 Stdio 服务器：✅ 允许（没有命令限制）
名为"internal-tool"、任何命令的 Stdio 服务器：✅ 允许（没有命令限制）
名为"github"的 HTTP 服务器：✅ 允许（匹配名称）
任何名为"other"的服务器：❌ 阻止（名称不匹配）

允许列表行为 (`allowedMcpServers`)

undefined（默认）：无限制 - 用户可以配置任何 MCP 服务器
空数组 []：完全锁定 - 用户无法配置任何 MCP 服务器
条目列表：用户只能配置按名称、命令或 URL 模式匹配的服务器

拒绝列表行为 (`deniedMcpServers`)

undefined（默认）：没有服务器被阻止
空数组 []：没有服务器被阻止
条目列表：指定的服务器在所有范围内被显式阻止

重要说明

选项 1 和选项 2 可以组合：如果 managed-mcp.json 存在，它具有独占控制，用户无法添加服务器。允许列表/拒绝列表仍然适用于托管服务器本身。
拒绝列表具有绝对优先级：如果服务器匹配拒绝列表条目（按名称、命令或 URL），即使它在允许列表上，它也会被阻止
基于名称、基于命令和基于 URL 的限制一起工作：如果服务器匹配任何名称条目、命令条目或 URL 模式，它就会通过（除非被拒绝列表阻止）

mcp.md 2026-05-08 22:00 UTC to 2026-05-09 04:57 UTC

通过 MCP 将 Claude Code 连接到工具

使用 MCP 可以做什么

流行的 MCP 服务器

安装 MCP 服务器

选项 1：添加远程 HTTP 服务器

选项 2：添加远程 SSE 服务器

选项 3：添加本地 stdio 服务器

管理您的服务器

动态工具更新

自动重新连接

使用频道推送消息

插件提供的 MCP 服务器

MCP 安装范围

本地范围

项目范围

用户范围

范围层次结构和优先级

.mcp.json 中的环境变量扩展

实际示例

示例：连接到 GitHub 进行代码审查

示例：查询您的 PostgreSQL 数据库

使用远程 MCP 服务器进行身份验证

添加需要身份验证的服务器

在 Claude Code 中使用 /mcp 命令

使用固定的 OAuth 回调端口

使用预配置的 OAuth 凭据

使用服务器注册 OAuth 应用

使用您的凭据添加服务器

在 Claude Code 中进行身份验证

覆盖 OAuth 元数据发现

限制 OAuth 范围

使用动态标头进行自定义身份验证

从 JSON 配置添加 MCP 服务器

从 JSON 添加 MCP 服务器

验证服务器已添加

从 Claude Desktop 导入 MCP 服务器

从 Claude Desktop 导入服务器

选择要导入的服务器

验证服务器已导入

使用来自 Claude.ai 的 MCP 服务器

在 Claude.ai 中配置 MCP 服务器

对 MCP 服务器进行身份验证

在 Claude Code 中查看和管理服务器

将 Claude Code 用作 MCP 服务器

MCP 输出限制和警告

为特定工具提高限制

响应 MCP 引发请求

使用 MCP 资源

引用 MCP 资源

列出可用资源

引用特定资源

多个资源引用

使用 MCP 工具搜索进行扩展

工作原理

对于 MCP 服务器作者

配置工具搜索

豁免服务器延迟

将 MCP 提示用作命令

执行 MCP 提示

发现可用的提示

执行不带参数的提示

执行带参数的提示

托管 MCP 配置

选项 1：使用 managed-mcp.json 的独占控制

选项 2：使用允许列表和拒绝列表的基于策略的控制

限制选项

示例配置

基于命令的限制如何工作

基于 URL 的限制如何工作

允许列表行为 (allowedMcpServers)

拒绝列表行为 (deniedMcpServers)

重要说明

`.mcp.json` 中的环境变量扩展

允许列表行为 (`allowedMcpServers`)

拒绝列表行为 (`deniedMcpServers`)