{/* TRANSLATED — 已翻译为中文 */} > ## 文档索引 > 在此处获取完整文档索引：https://code.claude.com/docs/llms.txt > 使用此文件发现所有可用页面，然后再进一步探索。 # 通过 MCP 将 Claude Code 连接到工具 > 了解如何通过模型上下文协议将 Claude Code 连接到你的工具。 Claude Code 可以通过[模型上下文协议（MCP）](https://modelcontextprotocol.io/introduction)连接到数百个外部工具和数据源，这是一个用于 AI 工具集成的开源标准。MCP 服务器使 Claude Code 能够访问你的工具、数据库和 API。 当你发现自己从另一个工具（如问题跟踪器或监控仪表板）将数据复制到聊天中时，请连接服务器。连接后，Claude 可以直接读取和操作该系统，而不是根据你粘贴的内容工作。 ## 使用 MCP 可以做什么 连接 MCP 服务器后，你可以要求 Claude Code： * **从问题跟踪器实现功能**："Add the feature described in JIRA issue ENG-4521 and create a PR on GitHub." * **分析监控数据**："Check Sentry and Statsig to check the usage of the feature described in ENG-4521." * **查询数据库**："Find emails of 10 random users who used feature ENG-4521, based on our PostgreSQL database." * **集成设计**："Update our standard email template based on the new Figma designs that were posted in Slack" * **自动化工作流**："Create Gmail drafts inviting these 10 users to a feedback session about the new feature." * **响应外部事件**：MCP 服务器还可以充当[通道](/en/channels)，将消息推送到你的会话中，以便 Claude 在你离开时响应 Telegram 消息、Discord 聊天或 webhook 事件。 ## 查找和构建 MCP 服务器 在 [Anthropic 目录](https://claude.ai/directory)中浏览经过审查的连接器。目录连接器使用与 Claude Code 相同的 MCP 基础设施，因此你可以使用 `claude mcp add` 添加那里列出的任何远程服务器。 在连接之前验证你信任每个服务器。获取外部内容的服务器可能使你面临[提示注入风险](/en/security#protect-against-prompt-injection)。 要构建自己的服务器，请参阅 [MCP 服务器指南](https://modelcontextprotocol.io/docs/develop/build-server)了解协议基础知识，以及 [Claude 连接器构建文档](https://claude.com/docs/connectors/building)了解身份验证、测试和目录提交。 你也可以让 Claude 使用官方 [`mcp-server-dev` 插件](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/mcp-server-dev)为你搭建服务器。 在 Claude Code 会话中，运行： ``` /plugin install mcp-server-dev@claude-plugins-official ``` 如果 Claude Code 报告找不到市场，先运行 `/plugin marketplace add anthropics/claude-plugins-official`，然后重试安装。安装后，运行 `/reload-plugins` 在当前会话中激活它。 ``` /mcp-server-dev:build-mcp-server ``` Claude 会询问你的用例并搭建远程 HTTP 或本地 stdio 服务器。 ## 安装 MCP 服务器 MCP 服务器可以根据你的需求以三种不同方式配置： ### 选项 1：添加远程 HTTP 服务器 HTTP 服务器是连接到远程 MCP 服务器的推荐选项。这是云服务最广泛支持的传输方式。 ```bash theme={null} # 基本语法 claude mcp add --transport http # 实际示例：连接到 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 服务器（如可用）。 ```bash theme={null} # 基本语法 claude mcp add --transport sse # 实际示例：连接到 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 Code 在生成的服务器环境中将 `CLAUDE_PROJECT_DIR` 设置为项目根目录，因此你的服务器可以解析项目相对路径而不依赖工作目录。这与钩子在其 `CLAUDE_PROJECT_DIR` 变量中接收的目录相同。在服务器进程内读取它，例如 Node 中的 `process.env.CLAUDE_PROJECT_DIR` 或 Python 中的 `os.environ["CLAUDE_PROJECT_DIR"]`。你的服务器还可以调用 MCP `roots/list` 请求，它返回 Claude Code 的启动目录。 此变量在服务器的环境中设置，而不是在 Claude Code 自己的环境中，因此在项目或用户范围的 `.mcp.json` 的 `command` 或 `args` 中通过 `${VAR}` 扩展引用它需要默认值，如 `${CLAUDE_PROJECT_DIR:-.}`。插件提供的 MCP 配置直接替换 `${CLAUDE_PROJECT_DIR}`，不需要默认值。 ```bash theme={null} # 基本语法 claude mcp add [options] -- [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` 这防止了 Claude 的标志和服务器的标志之间的冲突。 ### 管理你的服务器 配置后，你可以使用以下命令管理 MCP 服务器： ```bash theme={null} # 列出所有已配置的服务器 claude mcp list # 获取特定服务器的详情 claude mcp get github # 移除服务器 claude mcp remove github # （在 Claude Code 内）检查服务器状态 /mcp ``` `/mcp` 面板在每个已连接服务器旁边显示工具数量，并标记声明 tools 能力但未公开任何工具的服务器。 如果你的请求需要仍在后台连接的服务器的工具，Claude 会等待该服务器再继续。启用[工具搜索](#scale-with-mcp-tool-search)（默认启用）时，等待发生在 `ToolSearch` 调用内。在没有工具搜索的配置中（如 Vertex AI、自定义 `ANTHROPIC_BASE_URL` 或 `ENABLE_TOOL_SEARCH=false`），Claude 使用 `WaitForMcpServers` 工具代替。 服务器名称 `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` 标志选择加入。参见[通道](/en/channels)使用官方支持的通道，或[通道参考](/en/channels-reference)构建自己的通道。 提示： * 使用 `--scope` 标志指定配置存储位置： * `local`（默认）：仅在当前项目中对你可用（在旧版本中称为 `project`） * `project`：通过 `.mcp.json` 文件与项目中的每个人共享 * `user`：在你所有项目中可用（在旧版本中称为 `global`） * 使用 `--env` 标志设置环境变量（例如 `--env KEY=value`） * 使用 MCP\_TIMEOUT 环境变量配置 MCP 服务器启动超时（例如 `MCP_TIMEOUT=10000 claude` 设置 10 秒超时） * 通过在该服务器的 `.mcp.json` 条目中添加 `timeout` 字段（毫秒）设置每服务器工具执行超时，例如 `"timeout": 600000` 表示十分钟。这仅覆盖该服务器的 `MCP_TOOL_TIMEOUT` 环境变量 * 当 MCP 工具输出超过 10,000 个 token 时，Claude Code 会显示警告。要增加此限制，设置 `MAX_MCP_OUTPUT_TOKENS` 环境变量（例如 `MAX_MCP_OUTPUT_TOKENS=50000`） * 使用 `/mcp` 对需要 OAuth 2.0 身份验证的远程服务器进行身份验证 每服务器的 `timeout` 是每次工具调用的硬性挂钟限制，服务器的进度通知不会延长它。低于 1000 的值会被提升为一秒。对于 HTTP 和 SSE 服务器，每请求的 fetch 首字节预算有 60 秒的最小值，不受此值影响，因此只有工具调用看门狗会遵守较小的值。 ### 插件提供的 MCP 服务器 [插件](/en/plugins)可以捆绑 MCP 服务器，在插件启用时自动提供工具和集成。插件 MCP 服务器与用户配置的服务器工作方式相同。 **插件 MCP 服务器的工作方式**： * 插件在插件根目录的 `.mcp.json` 中或在 `plugin.json` 中内联定义 MCP 服务器 * 插件启用时，其 MCP 服务器自动启动 * 插件 MCP 工具与手动配置的 MCP 工具一起出现 * 插件服务器通过插件安装管理（而非 `/mcp` 命令） **插件 MCP 配置示例**： 在插件根目录的 `.mcp.json` 中： ```json theme={null} { "mcpServers": { "database-tools": { "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server", "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"], "env": { "DB_URL": "${DB_URL}" } } } } ``` 或在 `plugin.json` 中内联： ```json theme={null} { "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}` 访问[持久状态](/en/plugins-reference#persistent-data-directory)（在插件更新后保留），`${CLAUDE_PROJECT_DIR}` 访问稳定的项目根目录 * **用户环境访问**：访问与手动配置的服务器相同的环境变量 * **多种传输类型**：支持 stdio、SSE 和 HTTP 传输（传输支持可能因服务器而异） **查看插件 MCP 服务器**： ```bash theme={null} # 在 Claude Code 内，查看所有 MCP 服务器包括插件服务器 /mcp ``` 插件服务器在列表中显示带有指示器，表明它们来自插件。 **插件 MCP 服务器的优势**： * **捆绑分发**：工具和服务器打包在一起 * **自动设置**：无需手动 MCP 配置 * **团队一致性**：安装插件时每个人都获得相同的工具 参见[插件组件参考](/en/plugins-reference#mcp-servers)了解将 MCP 服务器与插件捆绑的详情。 ## MCP 安装范围 MCP 服务器可以在三个范围配置。你选择的范围控制服务器在哪些项目中加载以及配置是否与团队共享。管理员还可以通过[托管配置](#managed-mcp-configuration)在企业级别部署服务器。 | 范围 | 加载位置 | 与团队共享 | 存储位置 | | ------------------------- | ------------------ | ------------------------ | --------------------------- | | [本地](#local-scope) | 仅当前项目 | 否 | `~/.claude.json` | | [项目](#project-scope) | 仅当前项目 | 是，通过版本控制 | 项目根目录的 `.mcp.json` | | [用户](#user-scope) | 你所有项目 | 否 | `~/.claude.json` | ### 本地范围 本地范围是默认的。本地范围的服务器仅在你添加它的项目中加载，并保持对你私有。Claude Code 将其存储在 `~/.claude.json` 中该项目的路径下，因此同一服务器不会出现在你的其他项目中。将本地范围用于个人开发服务器、实验性配置或你不想放在版本控制中的凭据服务器。 MCP 服务器的"本地范围"术语与一般本地设置不同。MCP 本地范围服务器存储在 `~/.claude.json`（你的主目录），而一般本地设置使用 `.claude/settings.local.json`（在项目目录中）。详见[设置](/en/settings#settings-files)。 ```bash theme={null} # 添加本地范围服务器（默认） 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` 运行时的结果： ```json theme={null} { "projects": { "/path/to/your/project": { "mcpServers": { "stripe": { "type": "http", "url": "https://mcp.stripe.com" } } } } } ``` ### 项目范围 项目范围的服务器通过在项目根目录的 `.mcp.json` 文件中存储配置来实现团队协作。此文件设计为检入版本控制，确保所有团队成员访问相同的 MCP 工具和服务。当你添加项目范围的服务器时，Claude Code 自动创建或更新此文件，使用适当的配置结构。 ```bash theme={null} # 添加项目范围服务器 claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp ``` 生成的 `.mcp.json` 文件遵循标准化格式： ```json theme={null} { "mcpServers": { "shared-server": { "command": "/path/to/server", "args": [], "env": {} } } } ``` 出于安全原因，Claude Code 在使用 `.mcp.json` 文件中的项目范围服务器之前会提示批准。如果你需要重置这些批准选择，使用 `claude mcp reset-project-choices` 命令。 ### 用户范围 用户范围的服务器存储在 `~/.claude.json` 中，提供跨项目的可访问性，使其在你机器上的所有项目中可用，同时保持对你的用户帐户私有。此范围适用于个人实用工具服务器、开发工具或你在不同项目中经常使用的服务。 ```bash theme={null} # 添加用户服务器 claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic ``` ### 范围层次和优先级 当同一服务器在多个地方定义时，Claude Code 连接它一次，使用来自最高优先级源的定义。来自该源的整个服务器条目被使用；字段不会跨范围合并。 1. 本地范围 2. 项目范围 3. 用户范围 4. [插件提供的服务器](/en/plugins) 5. [claude.ai 连接器](#use-mcp-servers-from-claude-ai) 三个范围按名称匹配重复项。插件和连接器按端点匹配，因此指向与上述服务器相同的 URL 或命令的被视为重复。 ### `.mcp.json` 中的环境变量扩展 Claude Code 支持 `.mcp.json` 文件中的环境变量扩展，允许团队共享配置的同时为机器特定路径和敏感值（如 API 密钥）保持灵活性。 **支持的语法：** * `${VAR}` - 扩展为环境变量 `VAR` 的值 * `${VAR:-default}` - 如果已设置则扩展为 `VAR`，否则使用 `default` **扩展位置：** 环境变量可以在以下位置扩展： * `command` - 服务器可执行文件路径 * `args` - 命令行参数 * `env` - 传递给服务器的环境变量 * `url` - 用于 HTTP 服务器类型 * `headers` - 用于 HTTP 服务器身份验证 **带变量扩展的示例：** ```json theme={null} { "mcpServers": { "api-server": { "type": "http", "url": "${API_BASE_URL:-https://api.example.com}/mcp", "headers": { "Authorization": "Bearer ${API_KEY}" } } } } ``` 如果必需的环境变量未设置且没有默认值，Claude Code 将无法解析配置。 ## 实际示例 {/* ### 示例：使用 Playwright 自动化浏览器测试 ```bash claude mcp add --transport stdio playwright -- npx -y @playwright/mcp@latest ``` 然后编写和运行浏览器测试： ```text Test if the login flow works with test@example.com ``` ```text Take a screenshot of the checkout page on mobile ``` ```text Verify that the search feature returns results ``` */} ### 示例：使用 Sentry 监控错误 ```bash theme={null} claude mcp add --transport http sentry https://mcp.sentry.dev/mcp ``` 使用你的 Sentry 帐户进行身份验证： ```text theme={null} /mcp ``` 然后调试生产问题： ```text theme={null} What are the most common errors in the last 24 hours? ``` ```text theme={null} Show me the stack trace for error ID abc123 ``` ```text theme={null} Which deployment introduced these new errors? ``` ### 示例：连接到 GitHub 进行代码审查 GitHub 的远程 MCP 服务器使用作为请求头传递的 GitHub 个人访问令牌进行身份验证。要获取一个，打开你的 [GitHub 令牌设置](https://github.com/settings/personal-access-tokens)，生成一个新的细粒度令牌，授予对你希望 Claude 工作的仓库的访问权限，然后添加服务器： ```bash theme={null} claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \ --header "Authorization: Bearer YOUR_GITHUB_PAT" ``` 然后使用 GitHub： ```text theme={null} Review PR #456 and suggest improvements ``` ```text theme={null} Create a new issue for the bug we just found ``` ```text theme={null} Show me all open PRs assigned to me ``` ### 示例：查询 PostgreSQL 数据库 ```bash theme={null} claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \ --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics" ``` 然后自然地查询你的数据库： ```text theme={null} What's our total revenue this month? ``` ```text theme={null} Show me the schema for the orders table ``` ```text theme={null} Find customers who haven't made a purchase in 90 days ``` ## 对远程 MCP 服务器进行身份验证 许多基于云的 MCP 服务器需要身份验证。Claude Code 支持 OAuth 2.0 进行安全连接。 当服务器响应 `401 Unauthorized` 或 `403 Forbidden` 时，Claude Code 将远程服务器标记为需要身份验证。任一状态码都会在 `/mcp` 中标记服务器，以便你可以完成 OAuth 流程。返回指向其授权服务器的 `WWW-Authenticate` 头的自定义服务器会获得与其他远程服务器相同的自动发现。 例如： ```bash theme={null} claude mcp add --transport http sentry https://mcp.sentry.dev/mcp ``` 在 Claude Code 中，使用命令： ```text theme={null} /mcp ``` 然后按照浏览器中的步骤登录。 提示： * 身份验证令牌安全存储并自动刷新 * 使用 `/mcp` 菜单中的"Clear authentication"撤销访问权限 * 如果浏览器未自动打开，复制提供的 URL 并手动打开 * 如果身份验证后浏览器重定向失败并出现连接错误，将浏览器地址栏中的完整回调 URL 粘贴到 Claude Code 中出现的 URL 提示中 * OAuth 身份验证适用于 HTTP 服务器 ### 使用固定的 OAuth 回调端口 某些 MCP 服务器需要预先注册的特定重定向 URI。默认情况下，Claude Code 为 OAuth 回调选择随机可用端口。使用 `--callback-port` 固定端口，使其与预先注册的 `http://localhost:PORT/callback` 格式的重定向 URI 匹配。 你可以单独使用 `--callback-port`（使用动态客户端注册）或与 `--client-id` 一起使用（使用预配置凭据）。 ```bash theme={null} # 使用动态客户端注册的固定回调端口 claude mcp add --transport http \ --callback-port 8080 \ my-server https://mcp.example.com/mcp ``` ### 使用预配置的 OAuth 凭据 某些 MCP 服务器不支持通过动态客户端注册进行自动 OAuth 设置。如果你看到类似"Incompatible auth server: does not support dynamic client registration"的错误，服务器需要预配置凭据。Claude Code 还支持使用客户端 ID 元数据文档（CIMD）代替动态客户端注册的服务器，并自动发现这些。如果自动发现失败，先通过服务器的开发者门户注册 OAuth 应用，然后在添加服务器时提供凭据。 通过服务器的开发者门户创建应用，记下你的客户端 ID 和客户端密钥。 许多服务器还需要重定向 URI。如果是这样，选择一个端口并注册格式为 `http://localhost:PORT/callback` 的重定向 URI。在下一步中使用相同的端口与 `--callback-port`。 选择以下方法之一。用于 `--callback-port` 的端口可以是任何可用端口。只需匹配你在上一步中注册的重定向 URI。 使用 `--client-id` 传递应用的客户端 ID。`--client-secret` 标志使用掩码输入提示输入密钥： ```bash theme={null} 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` 作为单独标志传递： ```bash theme={null} claude mcp add-json my-server \ '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' \ --client-secret ``` 使用不带客户端 ID 的 `--callback-port` 在使用动态客户端注册时固定端口： ```bash theme={null} claude mcp add-json my-server \ '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"callbackPort":8080}}' ``` 通过环境变量设置密钥以跳过交互提示： ```bash theme={null} 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 中运行 `/mcp` 并按照浏览器登录流程操作。 提示： * 客户端密钥安全存储在你的系统钥匙串（macOS）或凭据文件中，而不是配置中 * 如果服务器使用没有密钥的公共 OAuth 客户端，仅使用 `--client-id` 而不带 `--client-secret` * `--callback-port` 可以与 `--client-id` 一起使用或单独使用 * 这些标志仅适用于 HTTP 和 SSE 传输。对 stdio 服务器无效 * 使用 `claude mcp get ` 验证服务器是否配置了 OAuth 凭据 ### 覆盖 OAuth 元数据发现 将 Claude Code 指向特定的 OAuth 授权服务器元数据 URL 以绕过默认发现链。当 MCP 服务器的标准端点出错或你想通过内部代理路由发现时设置 `authServerMetadataUrl`。默认情况下，Claude Code 首先在 `/.well-known/oauth-protected-resource` 检查 RFC 9728 受保护资源元数据，然后回退到 `/.well-known/oauth-authorization-server` 的 RFC 8414 授权服务器元数据。 在 `.mcp.json` 中服务器配置的 `oauth` 对象中设置 `authServerMetadataUrl`： ```json theme={null} { "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` 参数格式。 ```json theme={null} { "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 运行命令并将其输出合并到连接头中。 ```json theme={null} { "mcpServers": { "internal-api": { "type": "http", "url": "https://mcp.internal.example.com", "headersHelper": "/opt/bin/get-mcp-auth-headers.sh" } } } ``` 命令也可以是内联的： ```json theme={null} { "mcpServers": { "internal-api": { "type": "http", "url": "https://mcp.internal.example.com", "headersHelper": "echo '{\"Authorization\": \"Bearer '\"$(get-token)\"'\"}'" } } } ``` **要求：** * 命令必须将字符串键值对的 JSON 对象写入 stdout * 命令在 shell 中运行，超时 10 秒 * 动态头覆盖同名的任何静态 `headers` 助手在每次连接时重新运行（会话启动和重连时）。没有缓存，因此你的脚本负责任何令牌重用。 Claude Code 在执行助手时设置这些环境变量： | 变量 | 值 | | :-------------------------- | :--------------------------- | | `CLAUDE_CODE_MCP_SERVER_NAME` | MCP 服务器的名称 | | `CLAUDE_CODE_MCP_SERVER_URL` | MCP 服务器的 URL | 使用这些编写一个为多个 MCP 服务器服务的单一助手脚本。 `headersHelper` 执行任意 shell 命令。在项目或本地范围定义时，仅在接受工作区信任对话后运行。 ## 从 JSON 配置添加 MCP 服务器 如果你有 MCP 服务器的 JSON 配置，可以直接添加： ```bash theme={null} # 基本语法 claude mcp add-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 ``` ```bash theme={null} claude mcp get weather-api ``` 提示： * 确保 JSON 在你的 shell 中正确转义 * JSON 必须符合 MCP 服务器配置模式 * 你可以使用 `--scope user` 将服务器添加到用户配置而不是项目特定配置 ## 从 Claude Desktop 导入 MCP 服务器 如果你已经在 Claude Desktop 中配置了 MCP 服务器，可以导入它们： ```bash theme={null} # 基本语法 claude mcp add-from-claude-desktop ``` 运行命令后，你会看到一个交互式对话框，允许你选择要导入的服务器。 ```bash theme={null} claude mcp list ``` 提示： * 此功能仅在 macOS 和 Windows Subsystem for Linux (WSL) 上有效 * 它从这些平台上 Claude Desktop 配置文件的标准位置读取 * 使用 `--scope user` 标志将服务器添加到用户配置 * 导入的服务器将与 Claude Desktop 中的名称相同 * 如果同名的服务器已存在，它们将获得数字后缀（例如 `server_1`） ## 使用来自 Claude.ai 的 MCP 服务器 如果你使用 [Claude.ai](https://claude.ai) 帐户登录了 Claude Code，你在 Claude.ai 中添加的 MCP 服务器会自动在 Claude Code 中可用： 在 [claude.ai/customize/connectors](https://claude.ai/customize/connectors) 添加服务器。在 Team 和 Enterprise 计划中，只有管理员可以添加服务器。 在 Claude.ai 中完成任何必需的身份验证步骤。 在 Claude Code 中，使用命令： ```text theme={null} /mcp ``` Claude.ai 服务器在列表中显示带有指示器，表明它们来自 Claude.ai。 Claude.ai 连接器仅在你的活动[身份验证方法](/en/authentication#authentication-precedence)是 Claude.ai 订阅时获取。当 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN`、`apiKeyHelper` 或第三方提供商（如 Bedrock 或 Vertex）处于活动状态时不会加载，即使你之前运行了 `/login`。如果 `/mcp` 没有列出你添加的连接器，运行 `/status` 确认哪个身份验证方法处于活动状态，取消设置该环境变量或移除 `apiKeyHelper` 设置，然后运行 `/login` 选择你的 Claude.ai 帐户。 你在 Claude Code 中添加的服务器优先于指向相同 URL 的 claude.ai 连接器。当这种情况发生时，`/mcp` 将连接器列为隐藏，并显示如何移除重复项（如果你更愿意使用连接器）。 要在 Claude Code 中禁用 claude.ai MCP 服务器，将 `ENABLE_CLAUDEAI_MCP_SERVERS` 环境变量设置为 `false`： ```bash theme={null} ENABLE_CLAUDEAI_MCP_SERVERS=false claude ``` ## 将 Claude Code 用作 MCP 服务器 你可以将 Claude Code 本身用作其他应用程序可以连接的 MCP 服务器： ```bash theme={null} # 将 Claude 启动为 stdio MCP 服务器 claude mcp serve ``` 你可以在 Claude Desktop 中使用此功能，通过将以下配置添加到 claude\_desktop\_config.json： ```json theme={null} { "mcpServers": { "claude-code": { "type": "stdio", "command": "claude", "args": ["mcp", "serve"], "env": {} } } } ``` **配置可执行文件路径**：`command` 字段必须引用 Claude Code 可执行文件。如果 `claude` 命令不在系统的 PATH 中，你需要指定可执行文件的完整路径。 要查找完整路径： ```bash theme={null} which claude ``` 然后在配置中使用完整路径： ```json theme={null} { "mcpServers": { "claude-code": { "type": "stdio", "command": "/full/path/to/claude", "args": ["mcp", "serve"], "env": {} } } } ``` 没有正确的可执行文件路径，你会遇到类似 `spawn claude ENOENT` 的错误。 提示： * 服务器提供对 Claude 工具的访问，如 View、Edit、LS 等。 * 在 Claude Desktop 中，尝试让 Claude 读取目录中的文件、进行编辑等。 * 请注意，此 MCP 服务器仅将 Claude Code 的工具暴露给你的 MCP 客户端，因此你自己的客户端负责为单个工具调用实现用户确认。 ## MCP 输出限制和警告 当 MCP 工具产生大量输出时，Claude Code 帮助管理 token 使用以防止对话上下文过载： * **输出警告阈值**：当任何 MCP 工具输出超过 10,000 个 token 时，Claude Code 显示警告 * **可配置限制**：你可以使用 `MAX_MCP_OUTPUT_TOKENS` 环境变量调整允许的最大 MCP 输出 token 数 * **默认限制**：默认最大值为 25,000 个 token * **范围**：该环境变量适用于未声明自己限制的工具。设置了 [`anthropic/maxResultSizeChars`](#raise-the-limit-for-a-specific-tool) 的工具对文本内容使用该值，无论 `MAX_MCP_OUTPUT_TOKENS` 设置如何。返回图像数据的工具仍受 `MAX_MCP_OUTPUT_TOKENS` 限制 要增加产生大量输出的工具的限制： ```bash theme={null} export MAX_MCP_OUTPUT_TOKENS=50000 claude ``` 这在处理以下 MCP 服务器时特别有用： * 查询大型数据集或数据库 * 生成详细报告或文档 * 处理大量日志文件或调试信息 ### 为特定工具提高限制 如果你正在构建 MCP 服务器，可以通过在工具的 `tools/list` 响应条目中设置 `_meta["anthropic/maxResultSizeChars"]` 来允许单个工具返回大于默认持久化到磁盘阈值的结果。Claude Code 将该工具的阈值提高到标注的值，最高硬性上限为 500,000 个字符。 这对于返回本质上很大但必要的输出（如数据库模式或完整文件树）的工具很有用。没有标注时，超过默认阈值的结果会被持久化到磁盘并在对话中替换为文件引用。 ```json theme={null} { "name": "get_schema", "description": "Returns the full database schema", "_meta": { "anthropic/maxResultSizeChars": 200000 } } ``` 该标注独立于 `MAX_MCP_OUTPUT_TOKENS` 适用于文本内容，因此用户无需为声明它的工具提高环境变量。返回图像数据的工具仍受 token 限制。 如果你经常遇到特定 MCP 服务器的输出警告且无法控制它们，考虑增加 `MAX_MCP_OUTPUT_TOKENS` 限制。你也可以要求服务器作者添加 `anthropic/maxResultSizeChars` 标注或分页响应。该标注对返回图像内容的工具无效；对于这些工具，提高 `MAX_MCP_OUTPUT_TOKENS` 是唯一选择。 ## 响应 MCP 引导请求 MCP 服务器可以在任务中途使用引导请求你提供结构化输入。当服务器需要它自己无法获取的信息时，Claude Code 显示交互式对话框并将你的响应传回服务器。你这边不需要配置：引导对话框在服务器请求时自动出现。 服务器可以通过两种方式请求输入： * **表单模式**：Claude Code 显示带有服务器定义的表单字段的对话框（例如用户名和密码提示）。填写字段并提交。 * **URL 模式**：Claude Code 打开浏览器 URL 进行身份验证或批准。在浏览器中完成流程，然后在 CLI 中确认。 要自动响应引导请求而不显示对话框，使用 [`Elicitation` 钩子](/en/hooks#elicitation)。 如果你正在构建使用引导的 MCP 服务器，请参阅 [MCP 引导规范](https://modelcontextprotocol.io/docs/learn/client-concepts#elicitation)了解协议详情和模式示例。 ## 使用 MCP 资源 MCP 服务器可以公开你可以使用 @ 提及引用的资源，类似于引用文件的方式。 ### 引用 MCP 资源 在提示中输入 `@` 查看所有已连接 MCP 服务器的可用资源。资源与文件一起出现在自动补全菜单中。 使用格式 `@server:protocol://resource/path` 引用资源： ```text theme={null} Can you analyze @github:issue://123 and suggest a fix? ``` ```text theme={null} Please review the API documentation at @docs:file://api/authentication ``` 你可以在单个提示中引用多个资源： ```text theme={null} Compare @postgres:schema://users with @docs:file://database/user-model ``` 提示： * 资源在被引用时自动获取并作为附件包含 * 资源路径在 @ 提及自动补全中支持模糊搜索 * 当服务器支持时，Claude Code 自动提供列出和读取 MCP 资源的工具 * 资源可以包含 MCP 服务器提供的任何类型的内容（文本、JSON、结构化数据等） ## 使用 MCP 工具搜索进行扩展 工具搜索通过延迟工具定义直到 Claude 需要它们来保持 MCP 上下文使用量低。会话启动时仅加载工具名称，因此添加更多 MCP 服务器对上下文窗口的影响最小。 ### 工作原理 工具搜索默认启用。MCP 工具被延迟而不是预先加载到上下文中，Claude 使用搜索工具在任务需要时发现相关工具。只有 Claude 实际使用的工具才会进入上下文。从你的角度来看，MCP 工具的工作方式与之前完全相同。 如果你更喜欢基于阈值的加载，设置 `ENABLE_TOOL_SEARCH=auto` 在工具适合上下文窗口的 10% 时预先加载模式，仅延迟溢出部分。参见[配置工具搜索](#configure-tool-search)了解所有选项。 ### 对于 MCP 服务器作者 如果你正在构建 MCP 服务器，启用工具搜索后服务器说明字段变得更加有用。服务器说明帮助 Claude 了解何时搜索你的工具，类似于[技能](/en/skills)的工作方式。 添加清晰、描述性的服务器说明，解释： * 你的工具处理什么类别的任务 * Claude 何时应该搜索你的工具 * 你的服务器提供的关键能力 Claude Code 在 2KB 处截断工具描述和服务器说明。保持简洁以避免截断，并将关键细节放在开头附近。 ### 配置工具搜索 工具搜索默认启用：MCP 工具被延迟并按需发现。Claude Code 在 Vertex AI 上默认禁用它。当 `ANTHROPIC_BASE_URL` 指向非第一方主机时也会禁用，因为大多数代理不转发 `tool_reference` 块。明确设置 `ENABLE_TOOL_SEARCH` 以覆盖任一回退。 工具搜索需要支持 `tool_reference` 块的模型：Sonnet 4 及更高版本，或 Opus 4 及更高版本。Haiku 模型不支持。在 Vertex AI 上，工具搜索支持 Claude Sonnet 4.5 及更高版本和 Claude Opus 4.5 及更高版本。 使用 `ENABLE_TOOL_SEARCH` 环境变量控制工具搜索行为： | 值 | 行为 | | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | （未设置）| 所有 MCP 工具延迟并按需加载。在 Vertex AI 或 `ANTHROPIC_BASE_URL` 为非第一方主机时回退到预先加载 | | `true` | 所有 MCP 工具延迟。Claude Code 即使在 Vertex AI 上和通过代理也发送 beta 头。在早于 Sonnet 4.5 或 Opus 4.5 的 Vertex AI 模型上或不支持 `tool_reference` 块的代理上请求失败 | | `auto` | 阈值模式：如果工具适合上下文窗口的 10% 则预先加载，否则延迟 | | `auto:N` | 自定义百分比的阈值模式，其中 `N` 为 0-100。例如 `auto:5` 表示 5% | | `false` | 所有 MCP 工具预先加载，无延迟 | ```bash theme={null} # 使用自定义 5% 阈值 ENABLE_TOOL_SEARCH=auto:5 claude # 完全禁用工具搜索 ENABLE_TOOL_SEARCH=false claude ``` 或在你的 [settings.json `env` 字段](/en/settings#available-settings)中设置值。 你也可以专门禁用 `ToolSearch` 工具： ```json theme={null} { "permissions": { "deny": ["ToolSearch"] } } ``` ### 将服务器从延迟中豁免 如果服务器的工具应该始终对 Claude 可见而无需搜索步骤，在该服务器的配置中将 `alwaysLoad` 设置为 `true`。然后该服务器的每个工具在会话启动时加载到上下文中，无论 `ENABLE_TOOL_SEARCH` 设置如何。将此用于 Claude 每回合都需要的少量工具，因为每个预先加载的工具消耗本来可用于对话的上下文。 以下 `.mcp.json` 条目豁免一个 HTTP 服务器，同时保持其他服务器延迟： ```json theme={null} { "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 启动默认[非阻塞](/en/env-vars)也适用，因为工具必须在第一个提示构建时存在。其他服务器继续在后台连接。 ## 使用 MCP 提示作为命令 MCP 服务器可以公开在 Claude Code 中作为命令可用的提示。 ### 执行 MCP 提示 输入 `/` 查看所有可用命令，包括来自 MCP 服务器的命令。MCP 提示以 `/mcp__servername__promptname` 格式出现。 ```text theme={null} /mcp__github__list_prs ``` 许多提示接受参数。在命令后以空格分隔传递： ```text theme={null} /mcp__github__pr_review 456 ``` ```text theme={null} /mcp__jira__create_issue "Bug in login flow" high ``` 提示： * MCP 提示从已连接的服务器动态发现 * 参数根据提示定义的参数解析 * 提示结果直接注入对话中 * 服务器和提示名称被标准化（空格变为下划线） ## 托管 MCP 配置 对于需要集中控制用户可以连接哪些 MCP 服务器的组织，请参阅[托管 MCP 配置](/en/managed-mcp)。它涵盖了使用 `managed-mcp.json` 部署固定服务器集合、使用 `allowedMcpServers` 和 `deniedMcpServers` 限制服务器，以及服务器被阻止时用户看到的内容。