通过 MCP 连接 Claude Code 与外部工具¶

了解如何通过 Model Context Protocol 将 Claude Code 接入你的工具生态。

MCP 是连接 Claude Code 与外部工具的开放协议标准。 Claude Code 可以通过 Model Context Protocol (MCP) 连接数百种外部工具和数据源。MCP server 让 Claude Code 能直接访问你的工具、数据库和 API。

当你发现自己不断从其他工具（如问题追踪器、监控面板）复制数据粘贴到对话中时，就应该考虑接入 MCP server。接入后，Claude 可以直接读取和操作这些系统，不再依赖你手动粘贴。

如果你是第一次接入 MCP server，建议先看 MCP 快速开始 的手把手教程。本文是完整参考文档。

MCP 能做什么¶

接入 MCP server 后，Claude Code 可以直接操作外部系统完成复杂任务。 你可以这样用：

查找和构建 MCP Server¶

Anthropic 官方目录提供经过审核的 MCP 连接器，也支持自建。 在 Anthropic Directory 浏览已审核的连接器。目录中的远程 server 与 Claude Code 使用相同的 MCP 基础设施，你可以直接用 claude mcp add 添加。

警告： 接入前请确认你信任该 server。获取外部内容的 server 可能带来 prompt 注入风险。

要自建 MCP server，参见 MCP server 构建指南（协议基础）和 Claude 连接器构建文档（认证、测试和目录提交）。

也可以让 Claude 用官方 mcp-server-dev 插件 帮你脚手架搭建一个 server：

步骤 1：安装插件

在 Claude Code 会话中运行：

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

如果提示 marketplace 找不到，先运行 /plugin marketplace add anthropics/claude-plugins-official，再重试安装。安装完成后运行 /reload-plugins 在当前会话激活。

步骤 2：运行构建技能

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

Claude 会询问你的使用场景，然后搭建一个远程 HTTP 或本地 stdio server。

安装 MCP Server¶

MCP server 有多种安装方式，根据需求选择不同传输协议。

方式一：添加远程 HTTP server¶

HTTP 是连接远程 MCP server 的推荐方式， 也是云端服务最广泛支持的传输协议。

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

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

# 带 Bearer token 的示例
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 配置中，type 字段接受 streamable-http 作为 http 的别名。MCP 规范中使用 streamable-http 这个名称，所以从 server 文档复制的配置无需修改即可使用。

如果 JSON 条目有 url 但没有 type，则属于配置错误——因为 Claude Code 将无 type 的条目视为 stdio server。此时 Claude Code 跳过该 server 并报告 MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry。v2.1.202 之前，此类错误报告为 command: expected string, received undefined。

方式二：添加远程 SSE server¶

警告： SSE（Server-Sent Events）传输协议已弃用，优先使用 HTTP server。

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

方式三：添加本地 stdio server¶

stdio server 以本地进程运行，适合需要直接系统访问或自定义脚本的场景。

Claude Code 会在启动的 server 环境中设置 CLAUDE_PROJECT_DIR 变量，指向项目根目录，让你的 server 能解析项目相对路径而无需依赖工作目录。这和 hooks 收到的 CLAUDE_PROJECT_DIR 是同一个目录。在 server 内部读取即可，例如 Node 中用 process.env.CLAUDE_PROJECT_DIR，Python 中用 os.environ["CLAUDE_PROJECT_DIR"]。

CLAUDE_PROJECT_DIR 是稳定的项目根目录，在会话中添加或移除工作目录时不会变化。如果 server 需要限制自身文件系统访问范围到一组允许的目录，应实现 MCP roots/list 请求。Claude Code 对 roots/list 返回会话的启动目录加上你通过 --add-dir、/add-dir 或 additionalDirectories 设置授权的所有额外工作目录。当这组目录发生变化时，Claude Code 发送 notifications/roots/list_changed。v2.1.203 之前，roots/list 仅返回启动目录，且 Claude Code 不发送 notifications/roots/list_changed。

该变量设置在 server 的环境中，而不是 Claude Code 自身的环境中。因此在项目级或用户级 .mcp.json 的 command 或 args 中通过 ${VAR} 展开引用时需要设默认值，如 ${CLAUDE_PROJECT_DIR:-.}。插件提供的 MCP 配置会直接替换 ${CLAUDE_PROJECT_DIR}，不需要默认值。

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

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

重要：用 -- 分隔 server 参数

对于 stdio server，--（双短线）将 Claude 自身的选项（如 --transport、--env、--scope）与 server 的命令和参数分开。-- 之后的所有内容原样传递给 server。

示例：
- claude mcp add --transport stdio myserver -- npx server → 运行 npx server
- claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080 → 在环境变量 KEY=value 下运行 python server.py --port 8080

如果不加 --，Claude Code 会尝试将 server 的参数（如上面的 --port）解析为自身的选项。

--env 接受多个 KEY=value 对。如果 server 名称紧跟 --env 后面，CLI 会将其读取为另一个键值对并报错，所以要在 --env 和 server 名称之间放至少一个其他选项（如示例所示）。

方式四：添加远程 WebSocket server¶

WebSocket 保持持久双向连接，适合需要主动推送事件的远程 MCP server。 如果你的 server 只是响应请求，应优先使用 HTTP（HTTP 支持 OAuth 和 claude mcp add --transport 标志，WebSocket 不支持）。

通过 .mcp.json 或 claude mcp add-json 配置 WebSocket server：

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 字段。认证仅通过 header 实现，可以在 headers 中传递静态 token，或用 headersHelper 在连接时动态生成。claude mcp add --transport 标志不接受 ws。

管理 Server¶

安装后的 server 通过命令行统一管理。

# 列出所有配置的 server
claude mcp list

# 查看指定 server 详情
claude mcp get notion

# 删除一个 server
claude mcp remove notion

# （在 Claude Code 内部）检查 server 状态
/mcp

claude mcp add 成功后会打印 Added ... 一行，表示配置已写入。claude mcp list 在每个 server 旁显示健康状态，如 ✔ Connected、! Needs authentication 或 ✘ Failed to connect。failure 状态表示 Claude Code 无法连接该 server，而非 list 命令本身失败。

项目级 .mcp.json 中等待审批的 server 在 claude mcp list 和 claude mcp get <name> 中显示为 ⏸ Pending approval (run `claude` to approve)。需要进入 Claude Code 交互模式审核并批准。claude mcp get <name> 对已拒绝的 server 显示 ✘ Rejected (see disabledMcpjsonServers in settings)。

WebSocket server 不出现在 claude mcp list 输出中。用 claude mcp get <name> 或 /mcp 面板查看。

从 v2.1.196 起，claude mcp list 和 claude mcp get 只从未纳入版本控制的 settings 文件读取 .mcp.json 审批，直到你通过运行 claude 并接受工作区信任对话框来信任该工作区。克隆的仓库无法自行批准其 server：提交到项目 .claude/settings.json 中的 enableAllProjectMcpServers 或 enabledMcpjsonServers 在不受信任的文件夹中被忽略，server 保持 ⏸ Pending approval 状态而不会被连接和健康检查。

以下来源的审批在不受信任的文件夹中仍然生效：

• 用户级 ~/.claude/settings.json
• 托管配置（managed settings）
• 通过 --settings 传递的配置

未跟踪的 .claude/settings.local.json 中的审批也生效，但仅在你接受了该文件夹或其父目录的信任对话框之后：Claude Code 通过 git 检查文件是否被跟踪，而该检查仅在受信任的文件夹中执行。在从未信任过的文件夹中，该文件的审批等待信任对话框，除非该文件夹是你自己的配置主目录：你的 home 目录，或 .claude 被设为 CLAUDE_CONFIG_DIR 的目录。v2.1.207 之前，未跟踪的 .claude/settings.local.json 在从未信任的文件夹中也能批准 server。

任何 settings 文件中的 disabledMcpjsonServers 条目仍会拒绝该 server。

/mcp 面板在每个已连接 server 旁显示工具数量，并标记声明了 tools 能力但未暴露任何工具的 server。

配置了空 url 的远程 server 在 /mcp、claude mcp list 和 /plugin 管理器中显示为 not configured，Claude Code 不尝试连接。插件可以包含这种占位条目用于后续配置的连接器，Claude Code 不会将其报告为错误或安装问题。该 server 在 /mcp 的详情视图中显示 No URL configured for this server；设置 url 即可连接。v2.1.208 之前，Claude Code 将空 url 报告为配置问题并提示重连。

如果你的请求需要用到某个仍在后台连接的 server 的工具，Claude 会等待该 server 连接完成。开启 工具搜索 时（默认开启），等待发生在 ToolSearch 调用内部。在不支持工具搜索的配置中（如 Google Cloud Agent Platform、自定义 ANTHROPIC_BASE_URL、或 ENABLE_TOOL_SEARCH=false），Claude 改用 WaitForMcpServers 工具。Microsoft Foundry 的 Azure 托管部署 走工具搜索路径而非 WaitForMcpServers，因为 Claude Code 只能从 API 发现该部署的服务端拒绝；当 Claude Code 将该部署切换为预加载后，后续连接完成的 server 的工具在 Claude 下一次请求时可用。

部分 server 名称为 Claude Code 内置 server 保留：workspace、claude-in-chrome、computer-use、Claude Preview 和 Claude Browser。如果你的配置定义了使用保留名称的 server，Claude Code 在加载时跳过它并显示重命名警告。claude mcp add 对保留名称报错拒绝。

Claude Preview 和 Claude Browser 都是 Claude Code 桌面应用预览面板 使用的内置 server 名称。v2.1.205 之前，Claude Browser 未被保留，用户配置的 server 可以使用该名称注册。

禁用但不移除 Server¶

在 /mcp 面板中切换 server 为关闭状态，可以在不丢失配置的情况下阻止 Claude Code 连接。Claude Code 仍在 /mcp 中列出该 server，标记为已禁用。

切换 server 时，Claude Code 将选择按项目记录在 ~/.claude.json 中，使用两个互不重叠的列表：

• disabledMcpServers：用户配置的 server、插件 server、claude.ai 连接器和默认开启的内置 server 的退出列表。Claude Code 不连接此列表中的 server。通过 /mcp 的项目级切换禁用 claude.ai 连接器时（见禁用 claude.ai 连接器），Claude Code 将其以显示名称写入此列表，例如 claude.ai Slack。
• enabledMcpServers：默认关闭的内置 server（如 computer-use）的启用列表。Claude Code 仅在此列表中列出时才连接默认关闭的 server。

Claude Code 对每个 server 仅查询其中一个列表，两个列表互不覆盖。将普通 server 添加到 enabledMcpServers，或将默认关闭的内置 server 添加到 disabledMcpServers，Claude Code 会忽略该条目。

disabledMcpServers 和 enabledMcpServers 与 enabledMcpjsonServers 和 disabledMcpjsonServers 无关，后者控制项目 .mcp.json 中定义的 server 的审批。

动态工具更新¶

Claude Code 支持 MCP list_changed 通知。 MCP server 可以动态更新可用工具、prompts 和资源，无需断开再重连。当 server 发送 list_changed 通知时，Claude Code 自动刷新该 server 的可用能力。

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

自动重连¶

HTTP 和 SSE server 断线后会自动指数退避重连。 最多 5 次尝试，从 1 秒延迟开始每次翻倍。重连期间 server 在 /mcp 中显示为 pending 状态。5 次失败后标记为 failed，可从 /mcp 手动重试。stdio server 是本地进程，不会自动重连。

初始启动连接失败时也适用相同退避策略。从 v2.1.121 起，初始连接在瞬时错误（5xx 响应、连接拒绝、超时）时最多重试 3 次，之后标记 failed。认证错误和 not-found 错误不重试，因为需要修改配置才能解决。

当配置的 server 连接失败时，Claude Code 会将失败的 server 名称和连接错误告知 Claude，包括在 ToolSearch 结果中找不到匹配工具时报告，让 Claude 在回复中说明连接失败情况。此功能需要工具搜索（默认开启）。在不支持工具搜索的配置中（如自定义 ANTHROPIC_BASE_URL、ENABLE_TOOL_SEARCH=false、不支持工具搜索的模型），以及 Amazon Bedrock、Google Cloud Agent Platform 和 Microsoft Foundry 上，Claude Code 不向 Claude 报告连接失败。v2.1.205 之前，Claude Code 不将连接错误传递给 Claude，Claude 可能表现得好像失败 server 的工具从未被配置。

从 v2.1.191 起，成功连接后的能力发现请求（如 tools/list、prompts/list、resources/list）也对瞬时网络和服务器错误进行最多 3 次短退避重试。认证错误、4xx 响应和请求超时不重试。

通过 Channel 推送消息¶

MCP server 可以主动向会话推送消息，让 Claude 响应 CI 结果、监控告警或聊天消息等外部事件。 要启用此功能，server 需声明 claude/channel 能力，启动时用 --channels 标志选择加入。详见 Channels（使用官方支持的 channel）或 Channels 参考（自建 channel）。

实用提示¶

每个 server 的 timeout 是每次工具调用的硬性时间上限，server 的 progress 通知不会延长。低于 1000 的值会被忽略并回退到 MCP_TOOL_TIMEOUT，若该变量也未设置则默认约 28 小时。对于 HTTP、SSE 或 claude.ai 连接器 server，还有第二个每请求计时器，覆盖到 server 首字节响应的每个请求。该计时器默认 60 秒，除非设置了 timeout 或 MCP_TOOL_TIMEOUT；设为 60 秒或更高会将该计时器提升到对应值，更低的值不会缩短它，未设置 MCP_TOOL_TIMEOUT 时的 28 小时默认值不会传递给它。stdio 和 WebSocket server 没有每请求计时器。v2.1.162 之前低于 1000 的值会被下限为 1 秒。

timeout 值至少为 1000 时还作为下方空闲超时的下限：Claude Code 不会在早于该 server 的 timeout 时因空闲而中止其工具调用。需要 Claude Code v2.1.203 或更高版本。

如果 MCP server 的工具调用在空闲窗口内既无响应也无 progress 通知，将中止并报错，而不是等到时间上限。空闲超时需要 Claude Code v2.1.187 或更高版本。适用于除 IDE server 和 SDK 进程内 server 之外的所有 server 类型。空闲窗口默认值：HTTP、SSE、WebSocket 和 claude.ai 连接器 server 为 5 分钟，stdio server 为 30 分钟。v2.1.203 之前，stdio server 不受空闲超时限制。

通过 CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT 环境变量设置空闲窗口（毫秒），设为 0 可禁用。

这些超时限制工具调用的运行时长，但不一定意味着阻塞会话：Claude Code v2.1.212 或更高版本中，主对话中超过两分钟的调用会先移到后台任务。详见长时间工具调用自动后台化。

长时间工具调用自动后台化¶

主对话中运行超过两分钟的 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 server 的调用
• 非交互模式中的调用，除非 CLAUDE_AUTO_BACKGROUND_TASKS 设为 1（因为一次性运行可能在结果到达前结束）

等待打开的 elicitation 对话框 的调用在对话框打开期间不会被后台化——server 被你的输入阻塞而非运行缓慢，所以 Claude Code 推迟移动直到对话框关闭。

插件提供的 MCP Server¶

插件 可以捆绑 MCP server，启用插件时自动提供工具和集成。 插件 MCP server 的工作方式与用户手动配置的完全一致。

工作原理：
- 插件在根目录的 .mcp.json 或 plugin.json 内联定义 MCP server
- 插件启用后，其 MCP server 自动启动
- 插件 MCP 工具与手动配置的 MCP 工具并列显示
- 通过安装或卸载插件管理 server，不通过 /mcp 命令。你仍可在 /mcp 中切换已安装的插件 server 为关闭状态，这会阻止 Claude Code 连接它但不移除插件

示例配置：

插件根目录的 .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 server：

# 在 Claude Code 内查看所有 MCP server（包括插件的）
/mcp

插件 server 在列表中带有来源标识。

插件 MCP 工具命名：

来自插件捆绑 MCP server 的工具名称包含插件名和 server key。完整格式为 mcp__plugin_<plugin-name>_<server-name>__<tool-name>，其中 A-Z、a-z、0-9、_、- 之外的字符替换为 _。例如 my-plugin 插件的 database-tools server 中的 query 工具，全名为：

mcp__plugin_my-plugin_database-tools__query

在 权限规则、skill 的 allowed-tools 列表、子代理的 tools 字段 或 hook 匹配器 中引用工具时使用此全名。针对裸 server key 编写的 hook 匹配器（如 mcp__database-tools__.*）永远不会对插件捆绑的 server 触发。

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

插件 MCP server 的优势：
- 工具和 server 捆绑分发
- 无需手动 MCP 配置即可自动设置
- 团队成员安装插件后获得一致的工具集

详见 插件组件参考。

MCP 安装作用域¶

MCP server 可在三个作用域配置，决定加载范围和团队共享方式。 管理员还可以通过 托管配置 在企业层面部署。

Local 作用域¶

Local 是默认作用域。 server 仅在添加它的项目中加载，对你私有。Claude Code 将其存储在 ~/.claude.json 中该项目路径下，不会出现在其他项目中。适用于个人开发 server、实验性配置，或带有不想纳入版本控制的凭证的 server。

注意： MCP server 的 "local scope" 与一般的 local settings 不同。MCP local 作用域 server 存储在 ~/.claude.json（用户主目录），而一般 local settings 使用 .claude/settings.local.json（项目目录）。详见 Settings。

# 添加 local 作用域 server（默认）
claude mcp add --transport http stripe https://mcp.stripe.com

# 显式指定 local 作用域
claude mcp add --transport http stripe --scope local https://mcp.stripe.com

命令将 server 写入 ~/.claude.json 中当前项目的条目下。在 /path/to/your/project 目录运行后的结果：

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

Project 作用域¶

Project 作用域通过 .mcp.json 实现团队协作。 配置存储在项目根目录的 .mcp.json 文件中，适合纳入版本控制以确保团队成员使用相同的 MCP 工具和服务。

# 添加 project 作用域 server
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 中的 project 作用域 server 前会请求审批。如需重置审批选择，使用 claude mcp reset-project-choices 命令。

User 作用域¶

User 作用域 server 跨项目可用。 存储在 ~/.claude.json 中，对你所有项目可用但保持私有。适合常用的个人工具和服务。

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

作用域层级和优先级¶

同一 server 在多处定义时，Claude Code 使用最高优先级来源的定义，不会跨作用域合并字段。

1. Local 作用域
2. Project 作用域
3. User 作用域
4. 插件提供的 server
5. claude.ai 连接器

三个作用域按名称匹配重复项。插件和连接器按 endpoint 匹配，指向相同 URL 或命令的视为重复。

如果你在 桌面应用的 Code 标签 中打开本地会话，且 ~/.claude.json 顶层（user 作用域）和 .mcp.json 中有同名 stdio server，Code 标签使用 ~/.claude.json 的定义。

.mcp.json 中的环境变量展开¶

Claude Code 支持在 .mcp.json 中展开环境变量。 团队可以共享配置同时保留机器特定路径和 API key 等敏感值的灵活性。

支持的语法：
- ${VAR}：展开为环境变量 VAR 的值
- ${VAR:-default}：VAR 有值时使用其值，否则使用 default

展开位置： command（server 可执行路径）、args（命令行参数）、env（传递给 server 的环境变量）、url（HTTP server）、headers（HTTP server 认证）

带变量展开的示例：

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

如果引用的环境变量未设置且没有默认值，配置仍能加载：Claude Code 在 claude mcp list 输出中为该 server 报告缺失变量警告，并原样使用未展开的 ${VAR} 文本。设置变量或添加 :-default 回退值以确保 server 以你预期的值启动。

实用示例¶

示例：用 Sentry 监控错误¶

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

用 Sentry 账号认证：

/mcp

然后排查生产问题：

What are the most common errors in the last 24 hours?

Show me the stack trace for error ID abc123

Which deployment introduced these new errors?

示例：连接 GitHub 做代码审查¶

GitHub 远程 MCP server 通过 header 传递 personal access token 认证。 打开 GitHub token 设置，生成一个有目标仓库权限的 fine-grained token，然后添加 server：

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

然后操作 GitHub：

Review PR #456 and suggest improvements

Create a new issue for the bug we just found

Show me all open PRs assigned to me

示例：查询 PostgreSQL 数据库¶

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:[email protected]:5432/analytics"

然后自然语言查询：

What's our total revenue this month?

Show me the schema for the orders table

Find customers who haven't made a purchase in 90 days

远程 MCP Server 认证¶

许多云端 MCP server 需要认证，Claude Code 支持 OAuth 2.0 安全连接。

当远程 server 响应 401 Unauthorized 或 403 Forbidden 时，Claude Code 将其标记为需要认证。对未登录的 server，任一状态码都会在 /mcp 中标记以便完成 OAuth 流程。

对已登录的 OAuth server，当请求返回 401 Unauthorized 时，Claude Code 刷新存储的 token、重连并重试一次。仅在重试也失败时才在 /mcp 中标记。v2.1.206 之前，因瞬时原因（如网络错误）导致的 token 刷新失败会在整个会话期间将 OAuth server 标记为需要认证，即使其 refresh token 仍然有效。

从 v2.1.195 起，当 token 刷新因 server 拒绝存储的 refresh token 而失败时，Claude Code 立即显示指向 /mcp 的提示。已连接 server 的菜单中提供"重新认证"选项，让你在下一次工具调用失败前重新登录。

返回 WWW-Authenticate header 指向授权服务器的自定义 server 也能自动发现。

Claude Code 在一个或多个配置的 server 需要认证时会显示启动提示，无需打开 /mcp 即可发现。此功能需要 v2.1.193 或更高版本。从 v2.1.218 起，仅计算可从 Claude Code 登录的 server；之前也计算未在 claude.ai 连接的 claude.ai 连接器（只能从 claude.ai 设置连接）。

非交互模式下没有 /mcp 面板，Claude Code 无法为你运行 OAuth 流程。从 v2.1.196 起，在开启工具搜索（默认开启）的 claude -p 或 Agent SDK 运行中，当配置的 server 需要认证时，Claude Code 告知 Claude 该 server 的工具不可用直到你授权。Claude 可以说明需要登录的 server 名称，而非表现得好像 server 未被配置。从交互会话用 /mcp 或 claude mcp login <name> 完成登录。

如果你配置了 headers.Authorization 但 server 拒绝了该 header，Claude Code 将连接报告为 failed 而非回退到 OAuth。检查 token 对 MCP endpoint 是否有效，或移除 header 使用 OAuth 流程。

步骤 1：添加需要认证的 server

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

步骤 2：在 Claude Code 中认证

/mcp

然后在浏览器中完成登录。

认证提示：
- token 安全存储并自动刷新
- 在 /mcp 菜单中用 "Clear authentication" 撤销访问
- 浏览器未自动打开时，复制 URL 手动打开
- 浏览器重定向失败时，将浏览器地址栏中的完整回调 URL 粘贴到 Claude Code 出现的 URL 提示中
- OAuth 认证适用于 HTTP server

从命令行认证¶

从 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 server 需要预注册的特定 redirect URI。 默认情况下 Claude Code 为 OAuth 回调选择随机可用端口。用 --callback-port 固定端口以匹配预注册的 http://localhost:PORT/callback 格式 redirect URI。

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

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

使用预配置的 OAuth 凭据¶

部分 MCP server 不支持动态客户端注册（Dynamic Client Registration）。 如果遇到 "Incompatible auth server: does not support dynamic client registration" 错误，说明 server 需要预配置凭据。Claude Code 也支持使用 Client ID Metadata Document (CIMD) 的 server 并能自动发现。自动发现失败时，先通过 server 的开发者门户注册 OAuth 应用，再提供凭据。

步骤 1：在 server 端注册 OAuth 应用

通过 server 的开发者门户创建应用，记下 client ID 和 client secret。如果需要 redirect URI，选择一个端口并注册 http://localhost:PORT/callback 格式的 URI，在下一步用相同端口。

步骤 2：添加 server 并提供凭据

方法一：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

方法三：仅固定回调端口（动态客户端注册）

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

方法四：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 中认证

运行 /mcp 并完成浏览器登录流程。

提示：
- client secret 安全存储在系统钥匙串（macOS）或凭据文件中，不在配置中
- 公开 OAuth 客户端无 secret 时，只用 --client-id 不加 --client-secret
- --callback-port 可以搭配或不搭配 --client-id 使用
- 这些标志仅适用于 HTTP 和 SSE 传输，对 stdio server 无效
- 用 claude mcp get <name> 验证 server 是否配置了 OAuth 凭据

覆盖 OAuth 元数据发现¶

用 authServerMetadataUrl 指向特定的 OAuth 授权服务器元数据 URL，跳过默认发现链。 当 MCP server 的标准 endpoint 出错，或想通过内部代理路由发现时使用。默认情况下 Claude Code 先检查 RFC 9728 Protected Resource Metadata (/.well-known/oauth-protected-resource)，再回退到 RFC 8414 授权服务器元数据 (/.well-known/oauth-authorization-server)。

在 .mcp.json 中 server 配置的 oauth 对象内设置：

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

URL 必须使用 https://。需要 Claude Code v2.1.64 或更高版本。元数据 URL 的 scopes_supported 会覆盖上游 server 声明的 scopes。

限制 OAuth Scopes¶

用 oauth.scopes 固定 Claude Code 在授权流程中请求的 scopes。 这是将 MCP server 限制为安全团队批准的子集的正式方式。值为空格分隔的字符串，匹配 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 和 server 在 /.well-known 发现的 scopes。不设置则由 MCP server 决定请求的 scope 集合。

从 v2.1.196 起，当 oauth.scopes 未设置时，Claude Code 请求 server 的 WWW-Authenticate header 或其 protected resource metadata 提供的 scope，当两者都未提供时不发送 scope 参数。不再从自动发现的授权服务器元数据请求完整的 scopes_supported 目录。请求该目录会导致声明了仅管理员或模板 scope 的身份提供商以 invalid_scope 错误拒绝授权请求。从配置的 authServerMetadataUrl 获取的元数据仍以其 scopes_supported 作为请求的 scopes。

如果授权服务器在 scopes_supported 中声明了 offline_access，Claude Code 会将其附加到固定 scopes，以便 access token 可以在无需新的浏览器登录的情况下刷新。

如果 server 后续对工具调用返回 403 insufficient_scope，Claude Code 使用相同固定 scopes 重新认证。需要固定集合之外的 scope 时，扩展 oauth.scopes。

使用动态 Header 进行自定义认证¶

如果 MCP server 使用 OAuth 之外的认证方案（如 Kerberos、短期 token 或内部 SSO），用 headersHelper 在连接时动态生成 header。 Claude Code 运行该命令并将输出合并到连接 header 中。

{
  "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)\"'\"}'"
    }
  }
}

要求：
- 命令必须向 stdout 输出 JSON 对象（字符串键值对）
- 命令在 shell 中运行，10 秒超时，工作目录为会话当前工作目录。使用绝对路径或 PATH 上的命令
- 动态 header 覆盖同名的静态 headers

helper 在每次连接时（会话启动和重连）重新执行，不做缓存，token 复用由你的脚本负责。

从 v2.1.193 起，如果工具调用返回 401 Unauthorized 或 403 Forbidden，Claude Code 自动重新运行 helper、用新 header 重连并重试调用一次。仅在重试也失败时才在 /mcp 中标记 server 需要认证。

Claude Code 执行 helper 时设置以下环境变量：

用这些变量可以写一个 helper 脚本服务多个 MCP server。

对于插件提供的 server，helper 还以插件根目录作为工作目录运行，所以相对 headersHelper 路径解析到插件目录内而非会话工作目录。需要 Claude Code v2.1.195 或更高版本。

插件提供的 headersHelper 不能引用插件的 ${user_config.*} 值，因为命令通过 shell 运行。Claude Code 将 server 报告为配置错误并不替换该值。将 ${user_config.KEY} 放在 server 的 headers 字段中（不经过 shell 解析），或让 helper 脚本从自身环境或配置文件读取值。v2.1.207 之前，headersHelper 会替换 ${user_config.*} 值。

注意： headersHelper 执行任意 shell 命令。在 project 或 local 作用域定义时，仅在接受工作区信任对话框后才运行。

通过 JSON 配置添加 MCP Server¶

如果你有现成的 JSON 配置，可以直接导入。

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

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

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

# 示例：带预配置 OAuth 凭据的 HTTP server
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

提示：
- 确保 JSON 在 shell 中正确转义
- JSON 必须符合 MCP server 配置 schema
- 用 --scope user 添加到用户配置而非项目配置

从 Claude Desktop 导入 MCP Server¶

如果你已在 Claude Desktop 配置过 MCP server，可以一键导入。

# 导入
claude mcp add-from-claude-desktop

# 选择要导入的 server（交互式）
# 验证导入结果
claude mcp list

提示：
- 仅支持 macOS 和 Windows Subsystem for Linux (WSL)
- 从 Claude Desktop 标准配置路径读取
- 用 --scope user 添加到用户配置
- 保留 Claude Desktop 中的原始名称
- 同名 server 已存在时自动加数字后缀（如 server_1）

使用 claude.ai 的 MCP Server¶

如果用 claude.ai 账号登录了 Claude Code，在 claude.ai 添加的 MCP server 自动可用。

步骤 1： 在 claude.ai/customize/connectors 配置 MCP server。Team 和 Enterprise 计划仅管理员可添加。

步骤 2： 在 claude.ai 完成所有认证步骤。

步骤 3： 在 Claude Code 中用 /mcp 查看和管理。来自 claude.ai 的 server 带有来源标识。

从 v2.1.161 起，你从未登录的连接器折叠在 claude.ai 部分末尾的 Show unused connectors 行中，避免组织配置的长列表占满面板。选择该行展开。曾登录的连接器即使当前需要重新认证也保持可见。

claude.ai 连接器仅在活跃 认证方式 为 claude.ai 订阅登录时加载。当 ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN、apiKeyHelper 或第三方提供商（如 Amazon Bedrock 或 Google Cloud Agent Platform）激活时不加载，即使之前运行过 /login。当 CLAUDE_CODE_OAUTH_TOKEN 持有来自 claude setup-token 的 token 时也不加载（该 token 只能进行模型请求）。

如果 /mcp 未列出你添加的连接器，运行 /status 确认当前认证方式，取消设置相关环境变量或移除 apiKeyHelper，再运行 /login 选择 claude.ai 账号。

你在 Claude Code 中添加的 server 对指向相同 URL 的 claude.ai 连接器有 更高优先级。此时 /mcp 将连接器显示为 hidden 并说明如何移除重复项。

部分 Anthropic 托管的连接器（如 Microsoft 365、Gmail、Google Calendar）不支持从 Claude Code 本地 OAuth，因为上游身份提供商只接受 claude.ai 注册的 redirect URL。从 v2.1.162 起，在 /mcp 中认证这些主机时会提示前往 claude.ai 的 Settings → Connectors 连接。在那里连接后，连接器自动出现在 Claude Code 中。

组织对连接器工具的控制¶

你的组织可以对 claude.ai 连接器 设置逐工具控制。 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 Code v2.1.129 或更高版本。更早版本忽略这些设置并应用标准权限流程。

禁用 claude.ai 连接器¶

在任意 settings 作用域中设置 disableClaudeAiConnectors 为 true：

{
  "disableClaudeAiConnectors": true
}

此设置使用 any-source-true 语义：任何来源的 true 具有最高优先级。项目级 .claude/settings.json 可以选择退出云连接器，但项目级 false 无法重新启用被用户级或策略级 true 禁用的连接器。通过 --mcp-config 显式传递的 server 不受影响。

也可以设置环境变量，效果相同：

ENABLE_CLAUDEAI_MCP_SERVERS=false claude

要阻止单个连接器而非全部，将其添加到 deniedMcpServers 中（按名称或 URL 模式）。例如 serverName 条目 "claude.ai Slack" 阻止 Slack 连接器。要仅在当前项目切换连接器开关，使用 /mcp 面板。

注意： 这些客户端设置适用于本地 Claude Code 会话。在 Claude Code on the web 会话中，claude.ai 连接器由远程主机配置并作为显式 --mcp-config 条目到达，disableClaudeAiConnectors 不适用。连接器 URL 也通过会话代理重写，因此针对供应商 URL 的 deniedMcpServers serverUrl 模式不会匹配。从 claude.ai 组织设置管理云会话可用的连接器。

将 Claude Code 作为 MCP Server 使用¶

Claude Code 本身也可以作为 MCP server 供其他应用连接。

# 以 stdio MCP server 模式启动 Claude
claude mcp serve

在 Claude Desktop 的 claude_desktop_config.json 中添加配置：

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

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

查找完整路径：which claude

使用完整路径：
json { "mcpServers": { "claude-code": { "type": "stdio", "command": "/full/path/to/claude", "args": ["mcp", "serve"], "env": {} } } }

路径不正确会遇到 spawn claude ENOENT 错误。

提示：
- server 暴露 Claude 的工具如 View、Edit、LS 等
- 在 Claude Desktop 中可以让 Claude 读取目录文件、做编辑等
- 此 MCP server 仅向你的 MCP 客户端暴露 Claude Code 的工具，各工具调用的用户确认由你的客户端负责

MCP 输出限制和警告¶

当 MCP 工具产生大量输出时，Claude Code 帮助管理 token 用量以防上下文溢出。

export MAX_MCP_OUTPUT_TOKENS=50000
claude

适用于查询大数据集/数据库、生成详细报告/文档、处理大量日志的 MCP server。

提升单个工具的限制¶

如果你在构建 MCP server，可以通过 _meta["anthropic/maxResultSizeChars"] 让单个工具返回超过默认持久化阈值的结果。 Claude Code 将该工具的阈值提升到标注值，硬上限 500,000 字符。

适用于返回天然较大但必需输出的工具（如数据库 schema 或完整文件树）。不加标注时，超过默认阈值的结果会持久化到磁盘并在对话中替换为文件引用。

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

标注独立于 MAX_MCP_OUTPUT_TOKENS 作用于文本内容，用户无需为声明了该标注的工具提高环境变量。返回图片的工具仍受 token 限制。

警告： 如果你频繁遇到不受你控制的 MCP server 的输出警告，考虑提高 MAX_MCP_OUTPUT_TOKENS。也可以请求 server 作者添加 anthropic/maxResultSizeChars 标注或分页响应。该标注对返回图片的工具无效，对那些只能提高 MAX_MCP_OUTPUT_TOKENS。

根级组合器的工具输入 Schema¶

部分 MCP server 将工具的输入 schema 声明为 JSON Schema 联合类型，在 schema 顶层使用 anyOf、oneOf 或 allOf。Claude API 不接受这些关键字在 schema 根级别出现。嵌套在 properties 内的组合器不受影响，Claude Code 原样发送。

从 Claude Code v2.1.195 起，带有根级组合器的工具仍然可用。发送工具到 API 前，Claude Code 将 schema 扁平化为单个 object，并在工具描述开头添加一句说明哪些参数组属于一起：

• allOf：合并所有分支的 properties，每个分支的 required 列表仍然适用
• anyOf 和 oneOf：合并所有分支的 properties，每个分支的 required 列表在工具描述中说明而非由 schema 强制

你的 server 收到 Claude 选择的参数，所以仍需在服务端验证参数组合。

当 Claude Code 无法产生 API 接受的 schema，或在不接收启用重写的远程配置的部署上（如离线机器），它跳过该工具、在 server 日志中记录原因，其余工具保持可用。v2.1.195 之前的版本跳过所有输入 schema 中有根级 anyOf、oneOf 或 allOf 的工具。

要求特定工具需要批准¶

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

Claude Code 对该工具每次调用都显示权限提示，即使在 acceptEdits、auto 和 bypassPermissions 权限模式 中也是如此，且不提供"不再询问"选项。匹配该工具的 Allow 规则 也不能跳过提示。在从不提示的 dontAsk 模式中，Claude Code 拒绝调用。

该提示必须到达真人。在非交互模式下使用 --permission-prompt-tool 时，prompt tool 对标记工具返回的 allow 结果会被转换为 deny，消息为 MCP tool requires user interaction; not supported via --permission-prompt-tool。Agent SDK 的 canUseTool 回调 会收到这些调用并可以批准它们，因为你的 SDK 应用应当将其展示给用户。

适用于权限提示本身就是重点的工具，例如同意或授权步骤——自动批准意味着没有人类真正同意过。同一 server 的其他工具保持正常权限行为。

以下 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 对任何仅终端对话框才能完整渲染的权限请求（如带安全警告或远程界面无法显示的 always-allow 选项的请求）同样隐藏一键批准。你在终端对话框中回答该请求而非从 Remote Control。需要 Claude Code v2.1.214 或更高版本。

响应 MCP Elicitation 请求¶

MCP server 可以在任务执行中请求你的结构化输入。 当 server 需要自己无法获取的信息时，Claude Code 显示交互对话框并将你的回应传回 server。无需你做配置，对话框在 server 请求时自动出现。

server 可以通过两种方式请求输入：
- 表单模式： Claude Code 显示带有 server 定义字段的对话框（如用户名和密码），填写并提交
- URL 模式： Claude Code 打开浏览器 URL 进行认证或审批，在浏览器完成后在 CLI 确认

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

如果你在构建使用 elicitation 的 MCP server，参见 MCP elicitation 规范。

使用 MCP Resources¶

MCP server 可以暴露资源，你可以用 @ 提及来引用，类似引用文件。

引用 MCP 资源¶

步骤 1： 在 prompt 中输入 @ 查看所有已连接 MCP server 的可用资源。资源与文件一起出现在自动补全菜单中。

步骤 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： 单个 prompt 中可引用多个资源：

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

提示：
- 引用的资源自动获取并作为附件包含
- 资源路径在 @ 提及自动补全中可模糊搜索
- 当 server 支持时，Claude Code 自动提供列出和读取 MCP 资源的工具
- 资源可以包含任何类型的内容（文本、JSON、结构化数据等）

通过 MCP 工具搜索扩展规模¶

工具搜索通过延迟加载工具定义保持低 MCP 上下文占用。 会话启动时只加载工具名称和 server 说明，添加更多 MCP server 对上下文窗口的影响很小。Claude Code 不设固定的每 server 工具上限，实际限制取决于上下文窗口预算。

注意： Microsoft Foundry 的 Azure 托管部署 不支持工具搜索（服务端拒绝），Claude Code 检测到拒绝后改为预加载该部署的 MCP 工具。ENABLE_TOOL_SEARCH 无法覆盖，因为拒绝来自部署本身。

工作原理¶

工具搜索默认开启。 MCP 工具被延迟加载而非预先放入上下文，Claude 在任务需要时用搜索工具发现相关工具。只有实际使用的工具进入上下文。从你的角度看，MCP 工具的使用方式完全不变。

如果偏好基于阈值的加载方式，设置 ENABLE_TOOL_SEARCH=auto 在 schema 占用低于上下文窗口 10% 时预加载，溢出部分才延迟。详见 配置工具搜索。

MCP Server 作者须知¶

如果你在构建 MCP server，server instructions 字段在工具搜索启用时更加重要。 server instructions 帮助 Claude 理解何时搜索你的工具，类似 skills 的工作方式。

添加清晰的 server instructions 说明：
- 工具处理哪类任务
- Claude 何时应搜索你的工具
- server 提供的关键能力

Claude Code 将工具描述和 server instructions 各截断为 2KB。保持简洁避免截断，关键细节放在开头。

配置工具搜索¶

工具搜索默认开启，MCP 工具延迟加载按需发现。 Google Cloud Agent Platform 上默认禁用。当 ANTHROPIC_BASE_URL 指向非第一方主机时也禁用（多数代理不转发 tool_reference 块）。显式设置 ENABLE_TOOL_SEARCH 可覆盖回退行为。

设置 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS 会关闭工具搜索，ENABLE_TOOL_SEARCH 无法覆盖。该变量移除 defer_loading 工具定义和 tool_reference 内容块所需的 beta header。

工具搜索需要支持 tool_reference 块的模型：Claude Sonnet 4.5、Claude Haiku 4.5、Claude Opus 4.5 及更高版本。详见 API 文档中的模型兼容性。Google Cloud Agent Platform 上支持 Claude Sonnet 4.5 及更高、Claude Opus 4.5 及更高版本。

通过 ENABLE_TOOL_SEARCH 环境变量控制：

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

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

也可以在 settings.json 的 env 字段 中设置。

或在权限配置中禁用 ToolSearch 工具：

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

免除特定 Server 的延迟加载¶

如果某个 server 的工具需要始终对 Claude 可见（无需搜索步骤），设置 alwaysLoad 为 true。 该 server 的所有工具在会话启动时加载到上下文，不受 ENABLE_TOOL_SEARCH 设置影响。仅对少量每轮都需要的工具使用，因为预加载的工具会占用本来可用于对话的上下文。

.mcp.json 示例，免除一个 HTTP server 同时其他 server 保持延迟：

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

alwaysLoad 适用于所有 server 类型，需要 Claude Code v2.1.121 或更高版本。MCP server 也可以在工具的 _meta 对象中标记 "anthropic/alwaysLoad": true，对单个工具有相同效果。

设置 alwaysLoad: true 同时会阻塞启动直到 server 连接完成（标准 5 秒连接超时上限）。即使 MCP 启动本身默认非阻塞也是如此，因为首次 prompt 构建时这些工具必须就位。其他 server 继续在后台连接。

将 MCP Prompts 作为命令使用¶

MCP server 可以暴露 prompts，在 Claude Code 中作为命令使用。

执行 MCP Prompts¶

步骤 1： 输入 / 查看所有可用命令，包括 MCP server 的。MCP prompts 格式为 /mcp__servername__promptname。

步骤 2： 无参数执行：

/mcp__github__list_prs

步骤 3： 带参数执行（空格分隔）：

/mcp__github__pr_review 456

/mcp__jira__create_issue "Bug in login flow" high

提示：
- MCP prompts 从已连接 server 动态发现
- 参数根据 prompt 定义的参数解析
- prompt 结果直接注入对话
- server 和 prompt 名称经过规范化，空格转为下划线

托管 MCP 配置¶

对于需要集中控制用户可连接 MCP server 的组织， 参见 托管 MCP 配置。涵盖用 managed-mcp.json 部署固定 server 集合、用 allowedMcpServers 和 deniedMcpServers 限制 server，以及 server 被阻止时用户看到的提示。