SpyBara
Go Premium

mcp.md 2026-09-13 21:00 UTC to 2026-09-14 22:58 UTC

This page contains 552 additions and 234 deletions.

2026
Mon 14 22:58 Fri 18 23:58 Wed 23 23:57 Fri 25 23:58

通过 MCP 将 Claude Code 连接到工具

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

Claude Code 可以通过 Model Context Protocol (MCP)（一个用于 AI 工具集成的开源标准）连接到数百个外部工具和数据源。MCP 服务器为 Claude Code 提供对您的工具、数据库和 API 的访问权限。

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

如果您是第一次连接服务器，请从 MCP 快速入门 开始，获取分步演练。本页面是完整参考。

使用 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 服务器

在 Anthropic Directory 中浏览已审核的连接器。Directory 连接器使用与 Claude Code 相同的 MCP 基础设施，因此您可以使用 claude mcp add 添加列出的任何远程服务器。

要构建您自己的服务器，请参阅 MCP 服务器指南 了解协议基础知识，以及 Claude 连接器构建文档 了解身份验证、测试和 Directory 提交。

您也可以使用官方的 mcp-server-dev plugin 让 Claude 为您搭建服务器。

1

安装 plugin

在 Claude Code 会话中，运行：

/plugin install mcp-server-dev@claude-plugins-official

如果安装失败，请匹配 Claude Code 报告的消息：

  • Marketplace "claude-plugins-official" not found：使用 /plugin marketplace add anthropics/claude-plugins-official 添加 marketplace，然后重试安装。
  • plugin 在 marketplace 中找不到：检查 plugin 名称。

如果安装摘要报告 Run /reload-plugins to activate.，Claude Code 会为您运行该重新加载。如果重新加载警告您的下一条消息会重新读取对话，请运行 /reload-plugins --force。

2

运行构建 skill

/mcp-server-dev:build-mcp-server

Claude 会询问您的用例，并搭建一个远程 HTTP 或本地 stdio 服务器。

安装 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，因此从服务器文档复制的配置无需修改即可工作。

具有 url 但没有 type 的 JSON 条目是配置错误，因为 Claude Code 将没有 type 的条目读取为 stdio 服务器。Claude Code 跳过该服务器并报告 MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry。在 v2.1.202 之前，Claude Code 将此配置错误报告为 command: expected string, received undefined。

在 --output-format stream-json 运行中，Claude Code 还在 system/init 事件的 mcp_server_errors 字段 中报告跳过的 --mcp-config 条目，以便脚本可以检测到服务器从未加载。这需要 Claude Code v2.1.219 或更高版本。

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

某些服务仍然仅公开 SSE 端点。使用与 HTTP 服务器 相同的 claude mcp add --transport http <name> <url> 命令添加这些。Claude Code 首先尝试 HTTP 传输，当服务器不接受时切换到 SSE。自动切换需要 Claude Code v2.1.265 或更高版本。

在较早的版本上，或直接通过 SSE 连接，请改为传递 --transport 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 Code 在生成的服务器的环境中设置 CLAUDE_PROJECT_DIR 为项目根目录，因此您的服务器可以解析项目相对路径，而无需依赖工作目录。这与 hooks 在其 CLAUDE_PROJECT_DIR 变量中接收的目录相同。从服务器进程内部读取它，例如 Node 中的 process.env.CLAUDE_PROJECT_DIR 或 Python 中的 os.environ["CLAUDE_PROJECT_DIR"]。

CLAUDE_PROJECT_DIR 是稳定的项目根目录，在会话中添加或删除工作目录时不会更改。限制自己的文件系统访问到一组允许目录的服务器应该实现 MCP roots/list 请求。Claude Code 使用会话的启动目录加上您使用 --add-dir、/add-dir 或 additionalDirectories 设置授予的每个 额外工作目录 来回答 roots/list。当该集合更改时，Claude Code 发送 notifications/roots/list_changed。在 v2.1.203 之前，roots/list 仅返回启动目录，Claude Code 不发送 notifications/roots/list_changed。

此变量在服务器的环境中设置，而不是在 Claude Code 自己的环境中，因此通过项目范围的 .mcp.json 条目或本地或用户范围的 ~/.claude.json 中的服务器条目中的 command 或 args 中的 ${VAR} 扩展来引用它需要默认值，例如 ${CLAUDE_PROJECT_DIR:-.}。插件提供的 MCP 配置直接替换 ${CLAUDE_PROJECT_DIR} 并且不需要默认值。

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

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

选项 4：添加远程 WebSocket 服务器

WebSocket 服务器保持持久的双向连接，适合推送事件给 Claude 的远程 MCP 服务器。当您的服务器仅响应请求时，请改用 HTTP，因为 HTTP 支持 OAuth 和 claude mcp add --transport 标志，而 WebSocket 都不支持。

在 .mcp.json 中或使用 claude mcp add-json 配置 WebSocket 服务器：

claude mcp add-json events-server \
  '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'

type: "ws" 条目接受与 http 相同的 url、headers、headersHelper、timeout 和 alwaysLoad 字段。身份验证仅限于标头，因此在 headers 中传递静态令牌或在连接时使用 headersHelper 生成一个。claude mcp add --transport 标志不接受 ws。

从为另一个客户端编写的设置说明添加服务器

MCP 服务器不特定于 Claude Code，因此服务器的设置说明可能是为 Claude Desktop、Cursor 或另一个 MCP 客户端编写的，并且不提供 claude mcp add 命令。要添加服务器，请在这些说明中查找以下三项之一：

  • URL，例如 https://mcp.example.com/mcp：服务器是远程的。
  • 启动命令，例如 npx -y @example/mcp-server：服务器在您的机器上运行。
  • mcpServers JSON 块：为另一个客户端的设置文件编写的配置。

每一项都是 安装 MCP 服务器 中四个选项之一接受的输入。找到您下面拥有的形状，将其转换为 Claude Code 接受的命令。除非您添加 --scope project 或 --scope user，否则每个命令都写入 本地范围。

从 URL

URL 表示服务器是远程的。对于 https:// 端点，使用 --transport http 添加它，或在说明说端点使用 SSE 时遵循 选项 2。对于 wss:// 端点，改用 选项 4，因为 --transport 不接受 ws：

claude mcp add --transport http example https://mcp.example.com/mcp

如果说明还提供 API 密钥或令牌标头，请使用 --header 传递它，如 选项 1 所示。

从 `npx`、`uvx` 或二进制命令

启动命令表示服务器作为本地 stdio 进程运行。将整个命令放在 -- 之后，以便 Claude Code 将标志（如 -y）传递给启动服务器的命令，而不是将它们读取为自己的选项。使用 --env 传递说明要求的任何环境变量，在服务器名称之后和 -- 之前：

claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server

选项 3 完整涵盖 -- 分隔符。

从 `mcpServers` JSON 块

为另一个 MCP 客户端（如 Claude Desktop）编写的 mcpServers 块使用 Claude Code 读取的包装键和条目形状。将 mcpServers 内的对象传递给 claude mcp add-json，而不是包装器。两个条目需要先修复：

  • 没有 type 的 url：添加 "type": "http"、"type": "sse" 或 "type": "ws" 以匹配端点。Claude Code 将没有 type 的条目读取为 stdio 服务器，因此没有 type 的 url 条目会失败。
  • 具有字母、数字、连字符和下划线以外的字符的键：选择仅使用这些字符的服务器名称。否则键是服务器名称。

例如，此块：

{
  "mcpServers": {
    "example": {
      "command": "npx",
      "args": ["-y", "@example/mcp-server"]
    }
  }
}

变成此命令：

claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'

从 JSON 配置添加 MCP 服务器 涵盖 add-json 的 shell 转义和 --scope 标志。要改为与您的团队共享服务器，请添加 --scope project，或在项目根目录的 .mcp.json 下的 mcpServers 中添加条目并提交它。项目范围 涵盖 Claude Code 如何加载和批准该文件。

每个 claude mcp add 和 claude mcp add-json 命令都会打印一个 Added ... 行。要检查 Claude Code 是否已连接，请运行 claude mcp get <name>；服务器状态 涵盖它显示的状态和 .mcp.json 服务器的批准步骤。

管理您的服务器

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

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

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

# 删除服务器
claude mcp remove notion

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

删除远程服务器时，Claude Code 也会删除为该服务器存储的 OAuth 令牌和客户端注册。

服务器状态

claude mcp add 通过打印 Added ... 行确认成功添加，这意味着配置已写入。claude mcp list 然后在它列出的每个服务器旁边显示健康状态，例如 ✔ Connected、! Needs authentication 或 ✘ Failed to connect。失败状态意味着 Claude Code 无法连接到该服务器，而不是列表命令失败。

此列表中的状态报告配置决策而不是连接尝试，因此 Claude Code 在不连接到服务器的情况下打印它们：

  • ⏸ Pending approval (run `claude` to approve)：来自 .mcp.json 的项目范围服务器，您尚未批准。Claude Code 在 claude mcp list 和 claude mcp get <name> 中都显示它。运行 claude 交互式地审查和批准它。
  • ✘ Rejected (see disabledMcpjsonServers in settings)：由 disabledMcpjsonServers 条目拒绝的 .mcp.json 服务器。Claude Code 仅在 claude mcp get <name> 中显示它。
  • ⊘ Disabled for this project (re-enable via /mcp)：项目的 disabledMcpServers 列表命名的服务器。Claude Code 在 claude mcp list 和 claude mcp get <name> 中都显示它。从 /mcp 面板打开服务器。在 v2.1.238 之前，两个命令都连接到禁用的服务器以进行健康检查并报告连接结果。

WebSocket 服务器不会出现在 claude mcp list 输出中。使用 claude mcp get <name> 或 /mcp 面板检查它们。

项目服务器批准和工作区信任

从 v2.1.196 开始，claude mcp list 和 claude mcp get 仅从未检入存储库的设置文件中读取 .mcp.json 批准，直到您通过在其中运行 claude 并接受工作区信任对话来信任工作区。克隆的存储库无法批准自己的服务器：提交到项目的 .claude/settings.json 的 enableAllProjectMcpServers 或 enabledMcpjsonServers 在不受信任的文件夹中被忽略，服务器保持在 ⏸ Pending approval 而不是被连接和健康检查。

这些来源的批准仍然适用于不受信任的文件夹：

  • 您的用户 ~/.claude/settings.json
  • 托管设置
  • 使用 --settings 传递的设置

Claude Code 也应用来自未跟踪的 .claude/settings.local.json 的批准，但它运行 git 来检查文件是否被跟踪，并且仅在 受信任的文件夹 中运行该检查。在您从未信任的文件夹中，Claude Code 等待信任对话后才应用文件的批准，除非文件夹是您自己的配置主目录：您的主目录，或一个您已设置为 CLAUDE_CONFIG_DIR 的 .claude 的目录。在 v2.1.207 之前，Claude Code 即使在您从未信任的文件夹中也应用来自未跟踪的 .claude/settings.local.json 的批准。

任何设置文件中的 disabledMcpjsonServers 条目仍然拒绝服务器。

服务器状态详情

在 /mcp 中（包括服务器的菜单）和 /plugin 管理器中，您之前使用过的远程 HTTP 或 SSE 服务器可以显示 cached 状态，例如 cached 2h ago · connects on first use · 5 tools。Claude Code 从发现缓存（保存在上一个会话中）加载了服务器的工具列表，而不是在启动时连接，Claude Code 在 Claude 首次调用服务器的工具之一时连接服务器。工具从您的第一条消息开始可用，因此您无需执行任何操作。发现缓存及其 cached 状态需要 Claude Code v2.1.221 或更高版本。

发现缓存默认关闭，除非逐步推出已为您的帐户启用它。设置 MCP_DISCOVERY_CACHE=1 以打开它，或设置为 0 以在推出启用它时保持关闭。在 v2.1.238 之前，缓存默认打开。

/mcp 中服务器菜单中的两个操作也会影响该服务器的缓存条目：

  • 重新连接：在 cached 服务器上，Claude Code 现在连接它而不是在其第一个工具调用时连接，并保留条目。在连接或失败的服务器上，Claude Code 重新连接它并也丢弃条目。
  • 清除身份验证：Claude Code 撤销服务器的身份验证并也丢弃条目。

丢弃条目后，Claude Code 从服务器而不是从缓存获取服务器的工具列表。

当服务器的状态为 ✘ Failed to connect 时，claude mcp list 将失败详情附加到该状态行，claude mcp get <name> 在 Issue: 行上显示它：HTTP 状态或错误代码，加上服务器返回的任何错误文本。/mcp 中服务器的详情视图在其 Issue: 行中包含相同的服务器报告的文本。Claude Code 从此详情中编辑类似凭证的文本，并且从不包含扩展的服务器 URL，它可能携带机密。Claude Code 不向 ✘ Connection error 状态附加详情，因为它会打印的异常文本可以嵌入该 URL。在 v2.1.219 之前，两个命令仅显示裸失败状态，没有状态代码或服务器的错误文本。

当您从 /mcp 完成身份验证且连接仍然因 HTTP 状态或传输错误代码而失败时，Claude Code 在尝试后打印的消息中添加该代码和服务器 URL 的来源。来源是方案和主机，加上 URL 命名的端口（如 https://mcp.example.com）。

  • 路径和查询从不出现在该消息中。
  • 对于本地、项目、用户 范围 中的服务器或托管 MCP 配置中的服务器，来源显示该配置中写入的主机，因此主机中的 ${VAR} 引用在消息中不会展开。
  • 对于没有状态或错误代码的失败，Claude Code 显示错误文本而不显示来源。

配置为空 url 的远程服务器在 /mcp、claude mcp list 和 /plugin 管理器中显示为 not configured，Claude Code 不尝试连接到它。插件可以包含这样的占位符条目，用于您稍后配置的连接器，因此 Claude Code 不将其报告为错误或设置问题。/mcp 中服务器的详情视图读取 No URL configured for this server；设置条目的 url 以连接它。在 v2.1.208 之前，Claude Code 将空 url 报告为配置问题，并提示重新连接。

配置警告

Claude Code 警告以下配置问题。每个条目说明 Claude Code 检查什么以及如何清除警告：

  • 隐藏的空格：当 MCP 配置值携带隐藏的前导或尾随空格时，Claude Code 发出警告，这通常来自粘贴带有尾随换行符的令牌。Claude Code 检查 command、url、每个 args 条目以及 env 和 headers 下的值和键名。Claude Code 在 claude mcp list 输出和 /mcp 中显示警告，命名受影响的字段而不回显其值，例如 Leading or trailing whitespace in: headers.Authorization。Claude Code 不修剪空格并完全按照写入的方式使用值，因此编辑配置以删除它。
  • 在多个范围中具有相同名称：如果您在多个 范围 中定义相同的服务器名称，具有不同的端点，Claude Code 在 claude mcp list 输出和 /mcp 中警告冲突。Claude Code 按端点存储 OAuth 登录，因此当您对在一个项目中加载的定义进行身份验证时，您仍然需要在另一个项目中单独登录，其中不同的定义加载。保留您想要的端点并使用 claude mcp remove <name> --scope <scope> 删除其他端点。在警告中，Claude Code 引用每个范围的端点，如您的配置中写入的那样，带有 ${VAR} 引用 未展开，因此它从不显示已解析的值，例如 API 密钥。
  • 保留名称：Claude Code 保留其内置服务器的名称，包括 workspace、claude-in-chrome、computer-use、Claude Preview 和 Claude Browser。如果您的配置定义了具有保留名称的服务器，Claude Code 在加载时跳过它并显示警告，要求您重命名它。claude mcp add 拒绝带有错误的保留名称。Claude Preview 和 Claude Browser 都命名 Claude Code 桌面应用的预览窗格 使用的内置服务器。在 v2.1.205 之前，Claude Browser 未被保留，因此用户配置的服务器可以在该名称下注册。
  • 缺少环境变量：如果 ${VAR} 引用 在服务器的配置中命名一个未设置且没有 :-default 的变量，Claude Code 在 claude mcp list 输出和 /mcp 中警告，命名变量，并仍然加载服务器，${VAR} 文本未展开。设置变量或添加 ${VAR:-default} 回退。

工具可用性

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

如果您的请求需要来自仍在后台连接的服务器的工具，Claude 会在继续之前等待该服务器。等待的方式取决于您的配置：

  • 使用 工具搜索（默认）：等待发生在 ToolSearch 调用内。
  • 不使用工具搜索：Claude 改用 WaitForMcpServers 工具。不使用工具搜索的配置包括自定义 ANTHROPIC_BASE_URL、ENABLE_TOOL_SEARCH=false 和 Google Cloud 的 Agent Platform 上早于 Claude 4.5 代的模型。
  • 在 Microsoft Foundry 部署托管在 Azure 上：Claude 开始使用工具搜索路径而不是 WaitForMcpServers，因为 Claude Code 仅从 API 发现部署的服务器端拒绝。在 Claude Code 将该部署切换到 前期加载 后，来自完成连接的服务器的工具在 Claude 的下一个请求中变为可用。

启用工具搜索后，当服务器在 Claude 工作时完成连接时，Claude Code 在同一轮的下一个请求中将服务器的工具名称列出给 Claude。Claude 然后可以搜索和调用这些工具，而无需等待您的下一条消息。

禁用服务器而不删除它

在 /mcp 面板中切换服务器关闭，以停止 Claude Code 连接到它，而不会丢失其配置。Claude Code 仍然在 /mcp 中列出服务器，标记为禁用。

切换服务器时，Claude Code 在 ~/.claude.json 中按项目记录您的选择，在两个涵盖不相交服务器集的列表之一中：

  • disabledMcpServers：用户配置的服务器、插件服务器、您的组织 通过托管设置提供 的服务器、Claude Code 自己获取 的 claude.ai 连接器以及默认打开的内置服务器的选择退出列表。Claude Code 不连接您在此处列出的服务器。当您使用 禁用 claude.ai 连接器 中描述的按项目 /mcp 切换禁用 claude.ai 连接器时，Claude Code 在此列表下使用其显示名称（例如 claude.ai Slack）写入它。
  • enabledMcpServers：默认关闭的内置服务器（如 computer-use）的选择加入列表。Claude Code 仅当您在此处列出时才连接默认关闭的服务器。

Claude Code 为每个服务器查询恰好两个列表之一，因此两个列表都不会覆盖另一个。如果您将常规服务器添加到 enabledMcpServers，或将默认关闭的内置服务器添加到 disabledMcpServers，Claude Code 会忽略该条目。

disabledMcpServers 和 enabledMcpServers 与 enabledMcpjsonServers 和 disabledMcpjsonServers 无关，后者控制项目的 .mcp.json 文件中定义的服务器的批准。

MCP 客户端运行时

Claude Code 通过两个客户端运行时之一连接到 MCP 服务器。v1 运行时基于 MCP TypeScript SDK 1.x。v2 运行时是 MCP TypeScript SDK 2.0 上的相同代码，它添加了 MCP 协议修订版 2026-07-28。本页的其余部分适用于两个运行时，除非某个部分命名 v2 运行时。

在 Claude Code v2.1.232 或更高版本上，Claude Code 使用 v2 运行时。它在每次启动时选择一个运行时，并保持到您退出。当您运行它时，它使用 v1：

在 v2 上，Claude Code 也：

  • 询问 HTTP 和 claude.ai 连接器服务器是否支持较新的修订版，并与支持的服务器一起使用。它仅在您设置 MCP_PROTOCOL_NEGOTIATION 为 auto 时询问 stdio 服务器，并像 v1 一样连接到每个其他服务器。
  • 从 它保持打开的流 上的较新修订版的服务器接收 list_changed 通知。
  • 不注册在较新修订版上连接的 通道 服务器，因为该修订版无法携带通道消息。
  • 失败 MCP OAuth 登录，其授权响应命名意外的发行者。

Anthropic 可以使用 Claude Code 获取的功能标志将特定服务器保持在较早的协议上，或将其从该流中移除。

要自己选择运行时，请设置 MCP_SDK_GENERATION 为 v1 或 v2。要决定 Claude Code 是否询问，请设置 MCP_PROTOCOL_NEGOTIATION 为 auto 或 legacy。在 Claude Code 默认使用 v1 的地方，固定 v2 不会使其询问，因此也设置 auto。

动态工具更新

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

如果刷新请求失败，Claude Code 保留服务器之前发现的工具、提示和资源，直到稍后的刷新成功。在 v2.1.214 之前，刷新期间的瞬时错误将服务器的工具、提示和资源替换为空列表。

v2 运行时上的通知流

在 v2 运行时 上，Claude Code 从 它保持打开的流 上的较新协议修订版的服务器接收 list_changed 通知。当流关闭时，Claude Code 重新打开它，有两个限制：

  • 流在 10 秒内再次关闭：Claude Code 重新打开它最多三次，然后停止该连接。
  • 流保持打开超过 10 秒，然后关闭，如无服务器主机的流通常所做的那样：在一小时内五次重新打开后，Claude Code 等待大约六小时才能进行下一次。

在流重新打开之前，您保留服务器的最后获取的工具、提示和资源。要更快地获取其更改，请从 /mcp 重新连接服务器。

自动重新连接

Claude Code 重新连接在会话中期断开的远程服务器，并在瞬时错误后重试 HTTP 或 SSE 服务器的首次连接。Stdio 服务器是本地进程，Claude Code 不会自动重新连接它们。

远程服务器的会话中期断开

Claude Code 使用指数退避重新连接断开的远程服务器：最多五次尝试，从一秒延迟开始，每次加倍。您看到的内容取决于您如何运行 Claude Code：

  • 在交互式会话中：/mcp 在 Claude Code 重新连接时显示服务器为待处理。在五次失败尝试后，Claude Code 将服务器标记为失败，或在服务器需要再次授权时标记为需要身份验证。您可以从 /mcp 手动重试。
  • 在 claude -p 运行和 Agent SDK 会话中：Claude Code 按相同的计划重新连接，没有 /mcp 面板显示尝试。

失败的首次连接

当 HTTP 或 SSE 服务器的首次连接因瞬时错误（如 5xx 响应、连接被拒绝或超时）而失败时，Claude Code 最多重试三次。如果连接仍然失败，Claude Code 将服务器标记为失败。Claude Code 在启动时和在会话中期添加服务器时以这种方式重试。这包括 Claude Code 从其配置添加到 云会话 的服务器和您使用 Agent SDK 的 setMcpServers() 添加的服务器。

Claude Code 在这些情况下不重试：

  • WebSocket 服务器的首次连接
  • 身份验证或未找到错误，因为它需要配置更改来解决。当 headersHelper 是服务器唯一的 Authorization 标头来源时，Claude Code 仍然重试身份验证错误，因为它在每次尝试时重新运行助手并可以获取新凭证

失败的发现请求

服务器连接后，Claude Code 向其发送功能发现请求，例如 tools/list、prompts/list 和 resources/list。Claude Code 在瞬时网络或服务器错误后最多重试这些请求三次，短退避。它不重试身份验证错误、4xx 响应或请求超时。

Claude 如何了解服务器失败

Claude Code 是否告诉 Claude 配置的服务器无法连接取决于 工具搜索，默认打开：

  • 使用工具搜索，Claude Code 告诉 Claude 哪个服务器失败及其连接错误，因此 Claude 在其响应中报告连接失败。Claude Code 在 ToolSearch 结果中包含相同的信息，这些结果找不到匹配的工具。
  • 在任何 不使用工具搜索的配置 中，Claude Code 不向 Claude 报告失败的服务器连接。

使用通道推送消息

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

在 v2 运行时 上，如果您设置 MCP_PROTOCOL_NEGOTIATION 为 auto 并且通道服务器协商 MCP 协议修订版 2026-07-28，它无法传递通道消息，因此 Claude Code 不将其注册为通道。保留变量未设置，或将其设置为 legacy，将 stdio 服务器保持在较早的握手上。

每个服务器的 timeout 是每个工具调用的硬墙钟限制，来自服务器的进度通知不会延长它。低于 1000 的值被忽略并回退到 MCP_TOOL_TIMEOUT，或在该变量未设置时回退到其约 28 小时的默认值。对于 HTTP、SSE 或 claude.ai 连接器 服务器，还有第二个每请求计时器，涵盖从服务器的第一个响应字节的每个请求。Claude Code 将该计时器设置为三个值中最大的：60 秒、适用于服务器的工具超时和 MCP_TIMEOUT。未设置的 MCP_TOOL_TIMEOUT 的 28 小时默认值不进入该比较，低于 60 秒的值不会缩短计时器。Stdio 和 WebSocket 服务器没有每请求计时器。

至少 1000 的每个服务器 timeout 也充当下面描述的空闲超时的下限：Claude Code 从不因空闲而中止该服务器的工具调用早于每个服务器的 timeout。需要 Claude Code v2.1.203 或更高版本。

对在空闲窗口中不发送响应和不发送进度通知的 MCP 服务器的工具调用因错误而中止，而不是等待墙钟限制。空闲超时需要 Claude Code v2.1.187 或更高版本。它适用于除 IDE 服务器和 SDK 进程内服务器外的每个服务器类型。对于 HTTP、SSE、WebSocket 和 claude.ai 连接器 服务器，空闲窗口默认为五分钟，对于 stdio 服务器默认为 30 分钟。在 v2.1.203 之前，stdio 服务器免除空闲超时。

在 CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT 环境变量中以毫秒为单位设置以更改空闲窗口，或将其设置为 0 以禁用检查。

这些超时限制调用可以运行多长时间，不总是它阻止会话多长时间：在主对话中运行超过两分钟的主对话调用首先移动到后台任务。请参阅 长工具调用的自动后台处理。

长工具调用的自动后台处理

在主对话中仍在运行两分钟后的 MCP 工具调用移动到后台任务，而不是阻止会话。Claude 立即接收任务 ID 并继续工作，结果在调用解决时作为任务通知到达。自动后台处理需要 Claude Code v2.1.212 或更高版本。

任务出现在 /tasks 中，您也可以在其中停止它，它在退出会话时不会保留。每个调用的限制仍然适用于调用在后台运行时：由每个服务器 timeout 或 MCP_TOOL_TIMEOUT 设置的墙钟限制，以及由 CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT 设置的空闲超时。

在 CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS 环境变量中以毫秒为单位设置以更改阈值，或将其设置为 0 以关闭自动后台处理。将 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS 设置为 1 也会关闭它，以及所有其他后台任务功能。

某些调用从不移动到后台：

  • 来自 子代理 的调用；Claude Code 仅后台处理主对话调用
  • 对 IDE 服务器的调用
  • 在 非交互模式 中的调用，除非 CLAUDE_AUTO_BACKGROUND_TASKS 设置为 1，因为一次性运行可能在结果到达之前结束

等待打开的 引出对话 的调用在对话打开时不会后台处理；服务器被阻止在您的输入上，而不是缓慢，因此 Claude Code 将移动推迟到对话关闭。

插件提供的 MCP 服务器

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

插件 MCP 服务器如何工作：

  • 插件在插件根目录或 plugin.json 中内联的 .mcp.json 中定义 MCP 服务器
  • 当您启用插件时，Claude Code 自动启动其 MCP 服务器
  • Claude Code 将插件 MCP 工具与手动配置的 MCP 工具一起提供
  • 您通过安装或卸载插件添加和删除插件服务器，而不是使用 /mcp 命令。您仍然可以在 /mcp 中 切换已安装的插件服务器关闭，这会停止 Claude Code 连接到它而不删除插件

示例插件 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 功能：

  • 自动生命周期：服务器在这些点连接和断开连接：
    • 在会话启动时，Claude Code 自动连接启用的插件的服务器。在 /mcp 中，您之前使用过的远程（HTTP 或 SSE）插件服务器可以显示 cached 状态 而不是；Claude Code 在 Claude 首次调用其工具之一时连接它
    • 如果您在会话期间启用或禁用插件，Claude Code 在更改应用时连接或断开其 MCP 服务器。在不重新启动的情况下应用插件更改 描述何时应用。在没有交互式终端的会话中，/reload-plugins 不连接或断开插件 MCP 服务器；这些更改在您的下一个会话中生效
    • 当您重新加载时，Claude Code 保留配置未更改的插件服务器的实时连接，并在您从 Agent SDK 中 替换会话的 MCP 服务器列表 而不命名它们时执行相同操作
    • 当您在 v2.1.246 或更高版本上使用 /cd 移动会话 时，Claude Code 连接新目录的设置启用的插件的服务器，并断开不再启用的插件的服务器，因此您不需要在移动后运行 /reload-plugins
    • 在 网络会话 中，对尚未连接的插件服务器的 MCP 调用（例如在空闲会话唤醒后）按需启动服务器并等待其连接
  • 路径占位符：${CLAUDE_PLUGIN_ROOT} 解析为插件的安装目录，${CLAUDE_PLUGIN_DATA} 解析为其 持久状态 目录，${CLAUDE_PROJECT_DIR} 解析为稳定的项目根目录。替换适用于：
    • stdio 服务器：command、args、env
    • http、sse 和 ws 服务器：url、headers 和 headersHelper。在 v2.1.195 之前，headersHelper 将占位符作为文字字符串传递
  • 用户环境访问：访问与手动配置的服务器相同的环境变量
  • 多种传输类型：支持 stdio、SSE、HTTP 和 WebSocket 传输，尽管传输支持可能因服务器而异

插件服务器在 /mcp 中出现，指示器显示它们来自插件。

插件 MCP 工具名称：

来自插件捆绑的 MCP 服务器的工具在其可调用名称中包含插件名称和服务器键。完整形式是 mcp__plugin_<plugin-name>_<server-name>__<tool-name>，其中 A-Z、a-z、0-9、_ 和 - 之外的任何字符都被替换为 _。对于名为 my-plugin 的插件中捆绑的 database-tools 服务器，query 工具可调用为：

mcp__plugin_my-plugin_database-tools__query

在 权限规则 中、技能的 allowed-tools 列表中、子代理的 tools 字段 中或 hook 匹配器 中引用工具时使用此完整名称。针对裸服务器键编写的 hook 匹配器（如 mcp__database-tools__.*）从不为插件捆绑的服务器触发。

服务器本身在作用域名称 plugin:<plugin-name>:<server-name> 下注册，例如 plugin:my-plugin:database-tools。在需要配置的服务器名称的地方使用该名称，例如 mcp_tool hook 的 server 字段。

有关使用插件捆绑 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 文件中来启用团队协作。当您添加项目范围的服务器时，Claude Code 会自动创建或更新此文件，使用适当的配置结构。将 .mcp.json 检入版本控制，以便您团队中的每个人都能获得相同的 MCP 工具和服务。

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

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

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

出于安全原因，Claude Code 在交互式会话中使用来自 .mcp.json 文件的项目范围的服务器之前会提示批准。要重置这些批准选择，请运行 claude mcp reset-project-choices。

在 claude -p 运行、Agent SDK 会话和云会话中，Claude Code 无法显示该提示：它加载项目范围的服务器而不询问。Claude Code 还会在您以 bypassPermissions 模式启动的会话中跳过提示，其中用户设置或托管设置中设置了 skipDangerousModePermissionPrompt。要无论如何保持服务器不加载：

  • 将其添加到 disabledMcpjsonServers，这会在每个权限模式中阻止它。
  • 使用 --setting-sources 或 SDK 的 settingSources 选项完全排除项目设置。
  • 使用 --strict-mcp-config 启动会话。Claude Code 随后仅使用您通过 --mcp-config 传递的 MCP 服务器。跳过 Claude Code 未加载的项目范围服务器的批准提示需要 Claude Code v2.1.246 或更高版本；在 v2.1.246 之前，严格会话仍然会等待它们的批准，这会导致后台会话在启动时等待。有关该标志在托管 MCP 文件下的作用，请参阅使用 managed-mcp.json 进行独占控制。

项目服务器批准和工作区信任涵盖了提交到存储库的批准如何与工作区信任交互。

用户范围

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

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

范围层次结构和优先级

当具有相同名称的服务器在多个位置定义时，Claude Code 连接到它一次，使用来自最高优先级源的定义。整个服务器条目来自该源；字段不会跨范围合并。

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

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

您的组织通过 managedMcpServers 托管设置提供的服务器排名高于所有这些，因此当其中一个重复它时，Claude Code 连接组织的定义。需要 Claude Code v2.1.259 或更高版本。

如果您在桌面应用的代码选项卡中打开本地会话，其中 ~/.claude.json（用户范围）的顶级和 .mcp.json 中具有相同的 stdio 服务器名称，代码选项卡使用 ~/.claude.json 定义。

`.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 在 claude mcp list 输出中为该服务器报告缺失变量警告，并按原样使用未扩展的 ${VAR} 文本。设置变量或添加 :-default 回退，以便服务器使用您想要的值启动。

实际示例

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

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

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

将 YOUR_GITHUB_PAT 替换为您的个人访问令牌。claude mcp add 命令保存配置而不验证凭据，因此此处接受占位符值，但服务器稍后无法连接。要验证连接，请运行 /mcp 并检查服务器是否显示 connected。具有错误凭据的服务器显示 failed，失败详情包括服务器返回的 HTTP 状态，例如 401。

然后使用 GitHub：

审查 PR #456 并建议改进

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

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

示例：查询您的 PostgreSQL 数据库

DBHub，@bytebase/dbhub 包，是一个 MCP 服务器，通过您在 --dsn 中传递的连接字符串将 Claude 连接到关系数据库。在连接字符串中使用只读数据库用户，以便 Claude 运行的查询无法修改数据：

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

要确认服务器启动，请运行 /mcp 并检查 db 是否显示 connected。

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

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

显示订单表的架构

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

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

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

Claude Code 将远程服务器标记为需要身份验证，当服务器响应 401 Unauthorized 或 403 Forbidden 时。Claude Code 显示的内容取决于服务器：

  • 对于您尚未登录的服务器，任一状态代码都会在 /mcp 中标记它，以便您可以完成 OAuth 流程。
  • 对于 claude.ai 连接器，由 claude.ai 拒绝您的会话令牌导致的 401 不会标记连接器，因为重新授权连接器无法修复您的登录。Claude Code 改为显示 会话令牌被拒绝状态。
  • 对于您在 headers 中配置了 Authorization 标头的服务器，或通过 headersHelper 配置的服务器，连接时的 401 或 403 不会标记服务器，因为要修复的凭据是您配置的凭据。Claude Code 改为报告连接失败。
  • 对于 传递到云会话的连接器，Claude Code 不运行登录流程，因为会话的代理使用您在 claude.ai 中授予的授权向连接器进行身份验证。当那里的连接器需要再次授权时，请在 claude.ai/customize/connectors 重新连接它，而不是从会话中重新连接。

当对您已登录的 OAuth 服务器的请求返回 401 Unauthorized 时，Claude Code 会刷新存储的令牌、重新连接并重试请求一次。只有在该重试也失败时，它才会在 /mcp 中标记服务器。在 v2.1.206 之前，由于网络错误等暂时性原因导致的令牌刷新失败会将 OAuth 服务器标记为在会话的其余时间需要身份验证，即使其刷新令牌仍然有效。

当服务器拒绝存储的刷新令牌时，Claude Code 会立即显示一个指向 /mcp 的通知。打开 /mcp 并在服务器上选择 Re-authenticate 以在下一个工具调用失败之前重新登录。

返回指向其授权服务器的 WWW-Authenticate 标头的自定义服务器获得与任何其他远程服务器相同的自动发现。

Claude Code 也会在启动时显示通知，当一个或多个配置的服务器需要身份验证时，这样您就不必打开 /mcp 来发现哪些服务器需要登录。该通知需要 Claude Code v2.1.193 或更高版本。它仅计算您可以从 Claude Code 登录的服务器。在 v2.1.218 之前，它还计算 claude.ai 连接器，这些连接器在 claude.ai 中未连接，您只能从 claude.ai 设置中连接。

在非交互模式下，没有 /mcp 面板，因此 Claude Code 无法为您运行 OAuth 流程。从 v2.1.196 开始，当配置的服务器在 claude -p 或启用了 工具搜索（这是默认设置）的 Agent SDK 运行期间需要身份验证时，Claude Code 会告诉 Claude 该服务器的工具不可用，直到您授权它。Claude 可以命名需要登录的服务器，而不是响应就像服务器未配置一样。从与 /mcp 的交互式会话或 claude mcp login <name> 完成登录。

如果您为服务器配置了 headers.Authorization，而服务器拒绝了该标头，Claude Code 会将连接报告为失败，而不是回退到 OAuth。检查令牌对于 MCP 端点是否有效，或删除标头以使用 OAuth 流程。

1

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

如果您已在 MCP 快速入门 中添加了 sentry 服务器，请跳过此步骤：使用相同的服务器名称在相同的范围再次运行 claude mcp add 会失败，出现 MCP server sentry already exists in local config。否则，运行：

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

在 Claude Code 中使用 /mcp 命令

在 Claude Code 中，使用命令：

/mcp

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

从命令行进行身份验证

从 v2.1.186 开始，claude mcp login <name> 直接从您的 shell 运行配置的服务器的 OAuth 流程，因此您无需在会话内打开 /mcp 面板。

claude mcp login sentry

要稍后清除存储的凭据，请运行 claude mcp logout <name>。

从 v2.1.191 开始，该命令检测何时没有本地浏览器可用，例如在 SSH 会话期间或在没有显示服务器的 Linux 上，并打印授权 URL 而不是尝试打开浏览器。在您的本地计算机上打开 URL，然后将浏览器地址栏中的完整重定向 URL 粘贴回提示符。该命令需要交互式终端来执行粘贴步骤，因此请使用 ssh -t 连接。传递 --no-browser 以强制 URL 提示，即使检测到本地浏览器。

claude mcp login sentry --no-browser

使用固定的 OAuth 回调端口

某些 MCP 服务器需要预先注册的特定重定向 URI。默认情况下，Claude Code 为 OAuth 回调选择随机可用端口。使用 --callback-port 固定端口，使其与 http://localhost:PORT/callback 形式的预注册重定向 URI 匹配。如果 Claude Code v2.1.229 上的登录失败并出现重定向 URI 不匹配，请参阅 使用预配置的 OAuth 凭据 下的版本说明。

您可以单独使用 --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 应用，然后在添加服务器时提供凭据。

1

使用服务器注册 OAuth 应用

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

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

在 v2.1.229 中，Claude Code 发送了 http://127.0.0.1:PORT/callback，而精确匹配注册重定向 URI 的服务器拒绝了登录，出现重定向 URI 不匹配。Claude Code v2.1.231 恢复了 localhost 形式。要在 v2.1.229 上恢复，请升级 Claude Code，或临时将 http://127.0.0.1:PORT/callback 形式添加到服务器的注册重定向 URI。

2

使用您的凭据添加服务器

选择以下方法之一。用于 --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
3

在 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://。元数据 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 服务器确定请求的范围集。

从 v2.1.196 开始，当未设置 oauth.scopes 时，Claude Code 请求服务器的 WWW-Authenticate 标头或其受保护资源元数据提供的范围，当两者都未提供时不发送 scope 参数。它不再从自动发现的授权服务器元数据请求完整的 scopes_supported 目录。请求该目录导致公开仅限管理员或模板范围的身份提供者拒绝授权请求，出现 invalid_scope 错误。从配置的 authServerMetadataUrl 获取的元数据仍然将其 scopes_supported 作为请求的范围提供。

如果授权服务器在 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 对象写入标准输出
  • Claude Code 在 shell 中运行命令，并在 10 秒后放弃
  • Claude Code 根据 您配置服务器的位置 选择命令的工作目录，因此请将脚本作为绝对路径或放在 PATH 上
  • 动态标头覆盖任何具有相同名称的静态 headers

Claude Code 在每次连接时运行助手，在会话启动和重新连接时，一旦 项目和本地范围服务器的信任规则 允许它运行。它不缓存结果，因此您的脚本负责任何令牌重用。

如果工具调用返回 401 Unauthorized 或 403 Forbidden，Claude Code 会自动在相同规则下重新运行助手，使用新标头重新连接，并重试调用一次。只有在该重试也失败时，Claude Code 才会在 /mcp 中将服务器标记为需要身份验证。

当助手的输出包含 Authorization 标头时，Claude Code 使用该凭据作为服务器的身份验证，不会回退到 OAuth。

如果服务器在连接时拒绝助手的凭据，Claude Code 会报告连接失败，而不是将服务器标记为需要身份验证。修复您的助手返回的凭据，然后从 /mcp 重新连接以重新运行助手。

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

变量 值
CLAUDE_CODE_MCP_SERVER_NAME MCP 服务器的名称
CLAUDE_CODE_MCP_SERVER_URL MCP 服务器的 URL
CLAUDE_PLUGIN_ROOT 插件的根目录。仅当 插件 提供服务器时设置

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

插件提供的 headersHelper 无法引用插件的 ${user_config.*} 值，因为命令通过 shell 运行。Claude Code 报告服务器配置错误，并显示 错误，不替换该值。将 ${user_config.KEY} 放在服务器的 headers 字段中，该字段不会被 shell 解析，或让助手脚本从配置文件中读取该值。在 v2.1.207 之前，headersHelper 替换了 ${user_config.*} 值。

助手运行的位置

Claude Code 根据声明服务器的配置选择 headersHelper 命令的工作目录。Claude Code 在 Bash 中运行的 cd 不会移动它，/cd 仅对从会话主工作目录运行的服务器移动它。下表给出了相对路径在您的 headersHelper 命令中解析的目录。

您配置服务器的位置 工作目录
插件 插件的根目录。需要 Claude Code v2.1.195 或更高版本
项目 .mcp.json 或 本地范围 服务器 声明服务器的项目目录
项目中的代理文件、来自 SDK 的 mcpServers 选项或 setMcpServers() 方法的服务器，或 --mcp-config 会话的 主工作目录
用户范围、托管 MCP、claude.ai 连接器，或项目外的代理文件，包括来自 --add-dir 目录的代理文件 您的配置目录，~/.claude 除非您设置了 CLAUDE_CONFIG_DIR

在 v2.1.238 之前，Claude Code 也从您启动它的目录运行用户范围、托管和 claude.ai 连接器服务器的助手，以及来自项目外的代理文件。

助手可以读取哪些变量

存储库或插件提供的 headersHelper 是您没有编写的命令，因此 Claude Code 运行它时不会从您的环境中提供凭据变量，例如 ANTHROPIC_API_KEY。您配置服务器的位置决定了这是否适用：

  • 已删除：项目 .mcp.json 中的服务器或在插件中，以及来自您的项目或 --add-dir 目录的代理文件中的内联服务器
  • 未删除：用户 或 本地范围 的服务器、托管 MCP 中的服务器、来自 claude.ai 连接器 的服务器、由 SDK 或 --mcp-config 提供的服务器，以及来自 ~/.claude/agents/、托管设置或通过 --agents 传递的代理文件中的内联服务器

除了 Git 的 GIT_CONFIG_KEY_<n> 变量外，Claude Code 从您的环境中删除每个名称看起来像凭据的变量，例如名称中包含 TOKEN、SECRET、PASSWORD、KEY 或 AUTH 的变量（无论大小写），因此 ANTHROPIC_API_KEY 和 MY_REGISTRY_TOKEN 都被删除。Claude Code 也删除一个固定的凭据变量列表，其名称不遵循该模式，例如 ANTHROPIC_CUSTOM_HEADERS。

当这适用于您的助手时，让脚本从文件或凭据存储中读取其凭据。如果服务器的 url 展开这些变量之一，助手接收的 CLAUDE_CODE_MCP_SERVER_URL 值也会将该部分替换为 REDACTED。

在 headersHelper 运行之前信任文件夹

Claude Code 执行 headersHelper 作为任意 shell 命令。对于项目 .mcp.json 中的服务器或 本地范围 的服务器，它仅在您接受声明服务器的项目目录的 信任对话框 后运行助手。在 v2.1.238 之前，claude -p 或 SDK 会话运行这些助手而不检查信任，交互式会话在您信任父文件夹后运行它们。

  • 不计入的信任：父文件夹的信任，以及 claude -p 或 SDK 会话为 设置文件中的 hooks 获得的自动信任
  • 直到您信任文件夹：Claude Code 仅使用其静态 headers 连接服务器。在 claude -p 或 SDK 会话中，它也会向 stderr 打印每个服务器一行 headersHelper not run，告诉您如何授予信任。
  • 无对话框的信任：在 ~/.claude.json 中设置 projects["<path>"].hasTrustDialogAccepted 为 true。<path> 是文件夹 项目允许规则和工作区信任 说 Claude Code 将信任键入的位置。

Claude Code 对在 代理文件 中声明的服务器应用相同的规则，检查该代理文件来自何处：您的项目（对于其 .claude/agents/ 目录中的文件）或 --add-dir 目录。直到您 信任该项目或目录本身，Claude Code 不会加载服务器，因此其助手也永远不会运行。

从 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"}}'

# 示例：添加带有预配置 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
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

通过 claude mcp 命令添加的服务器名称只能包含字母、数字、连字符和下划线。Claude Desktop 不应用该限制，因此名称中包含任何其他字符（如空格）的 Claude Desktop 服务器无法导入。导入会报告它拒绝的每个名称，并仍然导入您选择的其他服务器。在 v2.1.205 之前，第一个无效名称会停止导入，所选的服务器都不会被添加。

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

如果您已使用 claude.ai 账户登录 Claude Code，您在 claude.ai 中添加的 MCP 服务器（称为 connectors）会自动在 Claude Code 中可用：

1

在 claude.ai 中配置 MCP 服务器

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

2

对 MCP 服务器进行身份验证

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

3

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

在 Claude Code 中，使用命令：

/mcp

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

当您的组织在 claude.ai 中管理其身份验证时，Claude Code 在 /mcp 和 /plugin 管理器中将连接器标记为 managed。托管状态不会改变 Claude Code 连接到连接器的方式或应用您的组织的 工具控制。

您从未登录过的连接器会在 claude.ai 部分末尾的 Show unused connectors 行后面折叠，因此组织预配的列表不会填满面板。选择该行以展开它们。您之前登录过的连接器即使当前需要重新身份验证，也会保持可见。

仅当您的活跃 身份验证方法 是 claude.ai 订阅登录时，才会从 claude.ai 获取连接器。即使您之前运行过 /login，在以下情况下也不会加载它们：

  • ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN 或 apiKeyHelper 处于活跃状态
  • Amazon Bedrock 或 Google Cloud 的 Agent Platform 等第三方提供商处于活跃状态
  • ANTHROPIC_PROFILE、联合变量或活跃的 Anthropic 配置文件 提供凭证
  • CLAUDE_CODE_OAUTH_TOKEN 持有来自 claude setup-token 的令牌，该令牌只能进行模型请求

如果 /mcp 没有列出您添加的连接器，请运行 /status 以确认哪个身份验证方法处于活跃状态。取消设置该环境变量、删除 apiKeyHelper 设置或 关闭配置文件，然后运行 /login 以选择您的 claude.ai 账户。

如果临时网络问题导致连接器列表在会话启动时无法加载，Claude Code 会在后台重试最多三次，连接器会在重试成功后出现。如果它们仍未出现，请重启 Claude Code 以再次获取列表。

如果 /mcp 显示连接器为 connected · session token rejected，或其详细视图显示 claude.ai rejected the session token，则 claude.ai 拒绝了来自您的 Claude Code 登录的令牌，通常是因为登录已过期且无法刷新。再次授权连接器不会清除此状态，因为被拒绝的不是连接器在 claude.ai 中的自身授权。要清除它：

  1. 运行 /login 以重新登录。
  2. 从 /mcp 重新连接连接器。

在 v2.1.222 之前，Claude Code 将连接器标记为需要身份验证，授权它们无法解决此问题。

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

某些 Anthropic 托管的连接器（如 Microsoft 365、Gmail 和 Google Calendar）不支持来自 Claude Code 的本地 OAuth，因为上游身份提供商仅接受 claude.ai 注册的重定向 URL。当您使用 claude mcp add 或在 .mcp.json 中添加的服务器指向这些主机之一，并且您从 /mcp 或使用 claude mcp login 登录时，Claude Code 会显示 is Anthropic-hosted and doesn't support local OAuth，指导您改为在 claude.ai/customize/connectors 连接服务。

使用 claude mcp remove <name> 删除您的条目并在 claude.ai 上连接服务后，连接器会自动出现在 Claude Code 中。

连接器如何到达 Claude Code

哪些设置控制 claude.ai 连接器取决于您的会话在哪里运行，因为只有某些会话本身从 claude.ai 获取连接器。下表中的每一行命名了连接器在一种会话中的到达方式以及在那里控制它们的内容。桌面应用的 WSL 会话 没有行，因为连接器在其中尚不可用。

会话运行的位置 连接器如何到达 什么控制它们
Terminal、VS Code、JetBrains 和 Agent SDK 会话 Claude Code 从 claude.ai 获取它们 本部分中的设置和 托管 MCP 配置
Cloud 会话 远程主机传入它们 您的 claude.ai 组织设置，加上到达会话的 allowlist 和 denylist 设置以及运行它的主机上的任何 managed-mcp.json
桌面应用 的本地和 SSH 会话 桌面应用在进程中传入它们 您的组织的 连接器工具控制 中的 blocked 条目

disableClaudeAiConnectors、ENABLE_CLAUDEAI_MCP_SERVERS 和 allowAllClaudeAiMcps 仅作用于第一行，即 Claude Code 本身获取的连接器。其他两行在这些方面与它不同：

  • Cloud 会话：到达会话的 allowedMcpServers 和 deniedMcpServers 条目（例如通过 服务器管理的设置）也会过滤传入的连接器。会话的代理会重写每个连接器的 URL，因此为连接器自身 URL 编写的 serverUrl 模式不会匹配它。要在自托管环境中的 URL allowlist 旁边允许传入的连接器，请添加 连接器流量离开您的网络 下列出的 serverUrl 条目。当运行会话的主机上存在 managed-mcp.json 时（例如 自托管运行器主机），Claude Code 会删除传入的连接器，无论您是否设置 allowAllClaudeAiMcps。
  • 桌面应用本地和 SSH 会话：桌面应用将连接器注册为进程内 type: "sdk" 服务器，没有 MCP 设置或 managed-mcp.json 到达它们。用户通过在 claude.ai/customize/connectors 断开连接器来将其排除在自己的会话之外。组织可以阻止连接器的 工具 或完全 关闭桌面应用中的 Claude Code。

连接器工具的组织控制

您的组织可以在 claude.ai 连接器 上设置每个工具的控制。Claude Code 在启动时读取这些设置并在本地强制执行它们，除了在桌面应用的 本地和 SSH 会话 中。在那里，桌面应用在传入连接器之前扣留 blocked 工具，ask 设置不会到达 Claude Code，因此它将会话的普通 权限规则 应用于这些工具，而不是在每次调用时提示。在 Claude Code 本身获取连接器的会话中，运行 /mcp 以查看哪个设置适用于连接器上的每个工具。

  • 工具设置为 ask：Claude Code 在每次调用时提示，原因是 Your organization requires approval for this tool。即使在 acceptEdits、auto 和 bypassPermissions 权限模式 中，提示也会出现，并且从不提供记住您的选择的选项。匹配工具的 Allow 规则 也不会跳过提示。在从不提示的 dontAsk 模式中，Claude Code 会改为拒绝调用。
  • 工具设置为 blocked：Claude Code 在 Claude 看到它之前过滤掉工具，因此它永远不会出现在工具列表中。桌面应用和 claude.ai 聊天应用相同的 blocked 设置，因此 Claude 也无法在那里使用该工具，您无法从桌面应用的会话中扣留工具，同时在聊天中保持其可用。桌面应用会跳过其所有工具都被阻止的连接器。

禁用 claude.ai 连接器

Claude Code 仅将 disableClaudeAiConnectors 应用于它 本身获取 的连接器，而不是云主机或桌面应用传入的连接器。要关闭它获取的连接器，请在任何设置范围中将设置设置为 true：

{
  "disableClaudeAiConnectors": true
}

此设置使用任何源为真的语义：任何设置源中的 true 优先。已检入的项目 .claude/settings.json 可以选择退出 Claude Code 本身获取的连接器，但项目级别的 false 无法重新启用用户或策略级别的 true 已禁用的连接器。通过 --mcp-config 显式传递的服务器不受影响。

您也可以将 ENABLE_CLAUDEAI_MCP_SERVERS 环境变量设置为 false，这对当前 shell 会话具有相同的效果：

ENABLE_CLAUDEAI_MCP_SERVERS=false claude

要阻止单个 claude.ai 连接器而不是全部，请按名称或 URL 模式将它们添加到 deniedMcpServers。例如，serverName 条目 "claude.ai Slack" 会阻止 Slack 连接器。您也可以运行 /mcp 以仅为当前项目切换 Claude Code 获取的任何连接器的开关。

将 Claude Code 用作 MCP 服务器

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

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

该命令启动时不会打印任何内容。stdio MCP 服务器通过 stdin 和 stdout 进行通信，因此沉默的、被阻止的终端意味着服务器正在运行并等待客户端连接。

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

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

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 限制
  • 超过限制：当没有图像内容的结果超过限制时，Claude Code 会将其保存到文件中，并在对话中用一条消息替换它，该消息指定文件路径，以便 Claude 在需要内容时读取该文件。该文件位于会话的 tool-results 目录中，在 ~/.claude/projects/ 下。

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

export MAX_MCP_OUTPUT_TOKENS=50000
claude

为特定工具提高限制

如果您正在构建 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 服务器将工具的输入模式声明为 JSON Schema 联合，在模式的顶级使用 anyOf、oneOf 或 allOf。Claude API 不接受这些关键字在模式根部。它接受嵌套在 properties 内的组合器，Claude Code 会原样发送这些组合器。

具有根级组合器的工具保持可用。在将工具发送到 API 之前，Claude Code 将模式展平为单个对象，并在工具描述前面添加一句话，告诉 Claude 哪些参数组属于一起：

  • allOf：来自每个分支的属性被合并，每个分支的 required 列表仍然适用
  • anyOf 和 oneOf：来自每个分支的属性被合并，每个分支的 required 列表在工具描述中描述，而不是由模式强制执行

您的服务器接收 Claude 选择的任何参数，因此请继续在服务器端验证组合。

当 Claude Code 无法生成 API 接受的模式，或在未收到启用重写的远程配置的部署上时，它会跳过该工具，在服务器日志中记录原因，并保持服务器的其他工具可用。早于 v2.1.195 的版本会跳过其输入模式具有根级 anyOf、oneOf 或 allOf 的每个工具。

具有无效输入架构的工具

Claude API 检查请求中每个工具的输入架构，当任何一个架构失败时会拒绝整个请求，因此单个 MCP 工具的格式错误的架构会导致包含它的每个请求都以 400 错误失败。Claude Code 在加载服务器的工具时自己运行 API 的两个检查，并排除每个会失败的工具，这样服务器的其他工具可以继续工作：

  • 顶级属性名称必须为 1 到 64 个字符长，并且只能使用 ASCII 字母和数字、_、. 和 -
  • 架构必须对 JSON Schema draft 2020-12 元架构有效。Claude Code 对未声明 $schema 的架构和声明 draft 2020-12 的架构应用此检查。声明任何其他方言的架构会跳过此检查，尽管上面的属性名称检查仍然适用

Claude Code 在 根级组合器重写 之后运行检查，对它实际会发送的架构进行检查。

当 Claude Code 排除一个工具时，它会在服务器的日志中记录原因，并告诉 Claude 它排除了哪些工具以及原因，这样你可以询问 Claude 为什么工具缺失。如果你修复了服务器上的架构，下次 Claude Code 加载服务器的工具时该工具就会回来。

Claude Code 通过从 Anthropic 获取的功能标志打开排除。在 禁用标志获取的部署 上，或在标志从未到达的机器上（例如隔离的机器），Claude Code 仍然运行检查并在服务器的日志中记录哪个工具会被拒绝，但仍然将工具的架构发送到 API。API 拒绝包含该架构的请求，并 以 400 错误按其位置命名工具。在 v2.1.216 之前，没有部署运行这些检查。

根级组合器处理 是独立的，当标志获取关闭或标志从未到达时保持其自己的行为。

要求对特定工具进行批准

如果你正在构建 MCP 服务器，可以通过在工具的 tools/list 响应条目中将 _meta["anthropic/requiresUserInteraction"] 设置为 true 来标记工具需要在每次调用时获得明确批准。该值必须是 JSON 布尔值 true；任何其他值都会被忽略。

Claude Code 会在每次调用时显示该工具的权限提示，即使在 acceptEdits、auto 和 bypassPermissions 权限模式中也是如此，并且不会为其提供"不再询问"选项。与该工具匹配的 允许规则也不会跳过提示。在 dontAsk 模式中（从不提示），Claude Code 会拒绝该调用。

提示必须到达一个人。在非交互模式下使用 --permission-prompt-tool，来自提示工具的标记工具的 allow 结果会被转换为拒绝，消息为 MCP tool requires user interaction; not supported via --permission-prompt-tool。Agent SDK 的 canUseTool 回调确实会接收这些调用并可以批准它们，因为你的 SDK 应用程序应该将它们显示给用户。

将此用于权限提示本身就是目的的工具，例如同意或访问授予步骤，其中自动批准意味着没有人类曾经同意。来自同一服务器的其他工具保持其正常的权限行为。

以下 tools/list 条目将一个工具标记为始终需要批准。

{
  "name": "grant_access",
  "description": "Requests access to a protected resource",
  "_meta": {
    "anthropic/requiresUserInteraction": true
  }
}

anthropic/requiresUserInteraction 注解需要 Claude Code v2.1.199 或更高版本。早期版本会忽略它并应用标准权限流程。

某些界面，例如 Remote Control 和基于 Agent SDK 构建的应用程序，通常允许你通过一次点击来批准工具调用。对于使用此注解标记的工具，Claude Code 会禁用一次点击操作并显示工具的完整权限提示，因此批准仍然来自回答提示的人，而不是点击。

Claude Code 对任何只有终端对话框才能完整呈现的权限请求（例如带有安全警告或远程界面无法显示的始终允许选项的请求）也会以相同方式禁用一次点击批准。你在终端对话框中回答该请求，而不是从 Remote Control 中回答。需要 Claude Code v2.1.214 或更高版本。

响应 MCP 引出请求

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

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

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

在 URL 模式中，Claude Code 将 URL 作为命令行参数传递给系统的 URL 处理程序，并限制该参数的长度。当 URL 在为命令行转义后超过该限制时，你只能拒绝该请求。每个需要转义的字符，例如 % 或 &，都会计为上限的四倍：其自身字符加上三个转义字符。没有这些字符的 URL 在大约 8,000 个字符处达到上限。主要由百分比转义组成的 URL，其中每三个字符中有一个是 %，在大约 4,000 处达到上限。

要在不显示对话框的情况下自动响应引出请求，请使用 Elicitation hook。

如果你正在构建使用引出功能的 MCP 服务器，请参阅 MCP 引出规范 了解协议详情和架构示例。

使用 MCP 资源

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

工具搜索通过延迟加载工具定义直到 Claude 需要时，来保持 MCP 上下文使用量较低。只有工具名称和服务器说明在会话开始时加载，因此添加更多 MCP 服务器对您的上下文窗口的影响最小。Claude Code 不会对每个服务器施加固定的工具上限；实际限制是您的上下文窗口预算。

对于 MCP 服务器作者

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

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

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

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

工具搜索默认启用：MCP 工具被延迟并按需发现。当 ANTHROPIC_BASE_URL 指向非第一方主机时，Claude Code 会禁用它，因为大多数代理不转发 tool_reference 块。设置 ENABLE_TOOL_SEARCH 显式覆盖该回退。

设置 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS 保持工具搜索关闭。您无法通过自己设置 ENABLE_TOOL_SEARCH 来覆盖它。您的组织可以通过 managed settings 在 Claude Code v2.1.227 或更高版本上保持工具搜索开启。禁用预发布功能 涵盖了覆盖应用的位置以及变量剥离的内容。

工具搜索需要支持 tool_reference 块的模型：Claude Sonnet 4.5、Claude Haiku 4.5、Claude Opus 4.5 及更高版本的模型。有关当前列表，请参阅 API 文档中的模型兼容性。

在 Google Cloud 的 Agent Platform 上，Claude Code 按模型代数决定：

  • Claude Opus 4.5、Sonnet 4.5、Haiku 4.5 及更高版本：工具搜索默认开启，与 Anthropic API 上相同。
  • 早期 Agent Platform 模型：Claude Code 预先加载所有 MCP 工具，因为它们的服务堆栈拒绝所需的 beta 标头。ENABLE_TOOL_SEARCH=true 不会覆盖此设置。

在 v2.1.221 之前，Claude Code 在 Google Cloud 的 Agent Platform 上为所有模型禁用工具搜索，除非您设置 ENABLE_TOOL_SEARCH=true。

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

值 行为
(未设置) 所有 MCP 工具延迟并按需加载。在 Google Cloud 的 Agent Platform 早于 Claude 4.5 代的模型上、当 ANTHROPIC_BASE_URL 是非第一方主机时、或在 Microsoft Foundry 部署在 Azure 上时回退到预先加载
true 所有 MCP 工具延迟，除了在 Microsoft Foundry 部署在 Azure 上，其中服务器端拒绝仍然强制预先加载，以及在 Google Cloud 的 Agent Platform 早于 Claude 4.5 代的模型上，Claude Code 保持预先加载工具。Claude Code 通过代理发送 beta 标头，在不支持 tool_reference 块的代理上请求失败
auto 阈值模式：Claude Code 预先加载它本来会延迟的工具，同时它们的定义总计少于上下文窗口的 10%，一旦定义达到 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 字段在所有服务器类型上都可用。MCP 服务器也可以通过在工具的 _meta 对象中包含 "anthropic/alwaysLoad": true 来标记单个工具为始终加载，这对该工具只有相同的效果。

设置 alwaysLoad: true 也会使启动等待服务器的工具，上限为标准 5 秒连接超时，因为它们必须在构建第一个提示时存在。具有有效 cached 条目 的远程服务器从缓存提供其工具而无需连接，因此它不会延迟启动。其他服务器默认在后台连接；设置 MCP_CONNECTION_NONBLOCKING=0 也使启动等待它们。

将 MCP 提示用作命令

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

执行 MCP 提示

1

发现可用的提示

输入 / 以查看可用的命令，包括来自 MCP 服务器的命令。Claude Code 将每个 MCP 提示列为 /servername:promptname (MCP)。输入 /mcp__servername__promptname 也可以运行它。

2

执行没有参数的提示

/mcp__github__list_prs
3

执行带有参数的提示

许多提示接受参数。在命令后面用空格分隔传递它们。Claude Code 在空格处分割参数，因此每个参数是单个令牌：

/mcp__github__pr_review 456

/mcp__jira__create_issue login-bug high

托管 MCP 配置

对于需要集中控制用户可以连接到哪些 MCP 服务器的组织，请参阅托管 MCP 配置。它涵盖使用 managed-mcp.json 部署固定服务器集、使用 managedMcpServers 为每个用户提供服务器、使用 allowedMcpServers 和 deniedMcpServers 限制服务器，以及当服务器被阻止时用户看到的内容。