Claude Code官方文档MCP工具集成Model Context Protocol

Claude Code MCP 协议教程 - 接入外部工具与数据源

使用 Model Context Protocol 把 GitHub、Sentry、数据库、Notion 等外部工具接入 Claude Code，包含安装、范围、OAuth 认证、托管配置与工具搜索。

发布于 2025年5月1日 · 阅读约 27 分钟

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 服务器也可以充当频道，将消息推送到您的会话中。

流行的 MCP 服务器

⚠️ 使用第三方 MCP 服务器需自担风险 - Anthropic 尚未验证所有这些服务器的正确性或安全性。请确保您信任正在安装的 MCP 服务器。使用可能获取不受信任内容的 MCP 服务器时要特别小心，因为这些可能会使您面临提示注入风险。

ℹ️ 需要特定的集成？ 在 GitHub 上查找数百个更多 MCP 服务器，或使用 MCP SDK 构建您自己的服务器。

安装 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 服务器

⚠️ SSE (Server-Sent Events) 传输已弃用。请在可用的地方使用 HTTP 服务器。

# 基本语法
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

ℹ️ 重要：选项顺序

所有选项（--transport、--env、--scope、--header）必须在服务器名称之前。然后 --（双破折号）将服务器名称与传递给 MCP 服务器的命令和参数分开。

例如：

claude mcp add --transport stdio myserver -- npx server → 运行 npx server

claude mcp add --transport stdio --env KEY=value myserver -- python server.py --port 8080 → 运行 python server.py --port 8080，环境中有 KEY=value

管理您的服务器

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

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

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

# 删除服务器
claude mcp remove github

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

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

服务器名称 workspace 保留供内部使用。

动态工具更新

Claude Code 支持 MCP list_changed 通知，允许 MCP 服务器动态更新其可用工具、提示和资源，而无需您断开连接并重新连接。

自动重新连接

如果 HTTP 或 SSE 服务器在会话中途断开连接，Claude Code 会自动以指数退避方式重新连接：最多五次尝试，从一秒延迟开始，每次加倍。

💡 提示：

使用 --scope 标志指定配置的存储位置：

local（默认）：仅在当前项目中对您可用

project：通过 .mcp.json 文件与项目中的每个人共享

user：在所有项目中对您可用

使用 --env 标志设置环境变量（例如，--env KEY=value）

使用 MCP_TIMEOUT 环境变量配置 MCP 服务器启动超时

当 MCP 工具输出超过 10,000 个令牌时，Claude Code 将显示警告

使用 /mcp 对需要 OAuth 2.0 身份验证的远程服务器进行身份验证

插件提供的 MCP 服务器

Plugins 可以捆绑 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 安装范围

MCP 服务器可以在三个不同的范围级别进行配置。

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

本地范围

本地范围是默认范围。本地范围的服务器仅在您添加它的项目中加载，并对您保持私密。

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

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

项目范围

项目范围的服务器通过在项目根目录中存储配置在 .mcp.json 文件中来启用团队协作。此文件设计为检入版本控制，确保所有团队成员都可以访问相同的 MCP 工具和服务。

# 添加项目范围的服务器
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 连接器

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

Claude Code 支持 .mcp.json 文件中的环境变量扩展。

支持的语法：

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

带有变量扩展的示例：

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

实际示例

示例：使用 Sentry 监控错误

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

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

/mcp

然后调试生产问题：

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

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

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

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

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

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

然后使用 GitHub：

审查 PR #456 并建议改进

示例：查询您的 PostgreSQL 数据库

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

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

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

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

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

步骤 1：添加需要身份验证的服务器

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

步骤 2：在 Claude Code 中使用 /mcp 命令

/mcp

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

💡 提示：

身份验证令牌安全存储并自动刷新

使用 /mcp 菜单中的”清除身份验证”撤销访问权限

如果您的浏览器没有自动打开，请复制提供的 URL 并手动打开

OAuth 身份验证适用于 HTTP 服务器

使用固定的 OAuth 回调端口

某些 MCP 服务器需要预先注册的特定重定向 URI。使用 --callback-port 固定端口：

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

使用预配置的 OAuth 凭据

某些 MCP 服务器不支持通过动态客户端注册进行自动 OAuth 设置。

步骤 1：使用服务器注册 OAuth 应用

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

步骤 2：使用您的凭据添加服务器

claude mcp add

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

claude mcp add-json

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

CI / 环境变量

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

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

步骤 3：在 Claude Code 中进行身份验证

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

覆盖 OAuth 元数据发现

指向 Claude Code 一个特定的 OAuth 授权服务器元数据 URL 以绕过默认发现链：

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

限制 OAuth 范围

设置 oauth.scopes 以固定 Claude Code 在授权流程中请求的范围：

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

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

如果您的 MCP 服务器使用 OAuth 以外的身份验证方案（例如 Kerberos、短期令牌或内部 SSO），请使用 headersHelper 在连接时生成请求标头：

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

要求：

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

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

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

从 JSON 配置添加 MCP 服务器

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

步骤 1：从 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"}}'

步骤 2：验证服务器已添加

claude mcp get weather-api

从 Claude Desktop 导入 MCP 服务器

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

步骤 1：从 Claude Desktop 导入服务器

claude mcp add-from-claude-desktop

步骤 2：选择要导入的服务器

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

步骤 3：验证服务器已导入

claude mcp list

💡 提示：

此功能仅在 macOS 和 Windows Subsystem for Linux (WSL) 上有效

它从这些平台上的标准位置读取 Claude Desktop 配置文件

使用 --scope user 标志将服务器添加到您的用户配置

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

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

要在 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": {}
    }
  }
}

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

要查找完整路径：
which claude
然后在您的配置中使用完整路径。

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

MCP 输出限制和警告

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

输出警告阈值：当任何 MCP 工具输出超过 10,000 个令牌时，Claude Code 显示警告
可配置限制：您可以使用 MAX_MCP_OUTPUT_TOKENS 环境变量调整最大允许的 MCP 输出令牌
默认限制：默认最大值为 25,000 个令牌

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

export MAX_MCP_OUTPUT_TOKENS=50000
claude

为特定工具提高限制

如果您正在构建 MCP 服务器，您可以通过在工具的 tools/list 响应条目中设置 _meta["anthropic/maxResultSizeChars"] 来允许单个工具返回大于默认持久化到磁盘阈值的结果：

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

响应 MCP 引发请求

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

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

表单模式：Claude Code 显示一个对话框，其中包含服务器定义的表单字段。
URL 模式：Claude Code 打开浏览器 URL 以进行身份验证或批准。

使用 MCP 资源

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

步骤 1：列出可用资源

在您的提示中键入 @ 以查看来自所有连接的 MCP 服务器的可用资源。

步骤 2：引用特定资源

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

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

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

步骤 3：多个资源引用

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

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

使用 MCP 工具搜索进行扩展

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

工作原理

工具搜索默认启用。MCP 工具被延迟而不是预先加载到上下文中，Claude 使用搜索工具在任务需要时发现相关的工具。仅 Claude 实际使用的工具进入上下文。

配置工具搜索

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

值	行为
（未设置）	所有 MCP 工具被延迟并按需加载
`true`	所有 MCP 工具被延迟
`auto`	阈值模式：如果工具适合上下文窗口的 10% 内，则预先加载，否则延迟
`auto:<N>`	阈值模式，带有自定义百分比
`false`	所有 MCP 工具预先加载，无延迟

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

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

豁免服务器延迟

如果服务器的工具应始终对 Claude 可见而无需搜索步骤，请在该服务器的配置中将 alwaysLoad 设置为 true：

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

将 MCP 提示用作命令

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

步骤 1：发现可用的提示

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

步骤 2：执行不带参数的提示

/mcp__github__list_prs

步骤 3：执行带参数的提示

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

/mcp__github__pr_review 456

/mcp__jira__create_issue "Bug in login flow" high

托管 MCP 配置

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

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

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

部署 managed-mcp.json 文件时，它对所有 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 服务器，而不是进行独占控制，同时对允许的服务器进行限制。

限制选项

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

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

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

示例配置

{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverName": "sentry" },
    { "serverCommand": ["npx", "-y", "@modelcontextprotocol/server-filesystem"] },
    { "serverCommand": ["python", "/usr/local/bin/approved-server.py"] },
    { "serverUrl": "https://mcp.company.com/*" },
    { "serverUrl": "https://*.internal.corp/*" }
  ],
  "deniedMcpServers": [
    { "serverName": "dangerous-server" },
    { "serverCommand": ["npx", "-y", "unapproved-package"] },
    { "serverUrl": "https://*.untrusted.com/*" }
  ]
}

基于命令的限制如何工作

精确匹配：

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

基于 URL 的限制如何工作

URL 模式使用 * 支持通配符以匹配任何字符序列。

通配符示例：

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

允许列表行为 (`allowedMcpServers`)

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

拒绝列表行为 (`deniedMcpServers`)

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

重要说明

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

本文翻译自 Anthropic Claude Code 官方文档，最近一次同步：2025-05-01。