服务器状态、运行时与插件服务器

版本要求与措辞以官方为准。

服务器状态

claude mcp add 成功时打印 Added ...，表示配置已写入；若打印 was not saved 则见错误参考。claude mcp list 在每个服务器旁显示健康状态，如 ✔ Connected、! Needs authentication、✘ Failed to connect——失败状态表示 Claude Code 连不上那个服务器，而不是 list 命令本身失败。下面这些状态报告的是配置决定而不是连接尝试，Claude Code 不去连接就打印：

• ⏸ Pending approval (run claude to approve)：来自 .mcp.json 的项目范围服务器，你还没批准；在 list 和 get 里都显示，交互运行 claude 来评审并批准。
• ✘ Rejected (see disabledMcpjsonServers in settings)：被 disabledMcpjsonServers 条目拒绝的 .mcp.json 服务器（只在 claude mcp get 里显示）。
• ⊘ Disabled for this project (re-enable via /mcp)：被该项目的 disabledMcpServers 列表点名的服务器。

WebSocket 服务器不出现在 claude mcp list 输出里，要用 claude mcp get <名称> 或 /mcp 面板检查。项目服务器审批与工作区信任：自 v2.1.196 起，claude mcp list/get 只从未被检入仓库的设置文件读取 .mcp.json 的批准，直到你在该工作区运行 claude 并接受信任对话框；在未信任的文件夹里仍然生效的批准来自：你的用户 ~/.claude/settings.json、托管设置、--settings 传入的设置；未被跟踪的 .claude/settings.local.json 也适用，但 Claude Code 只在受信文件夹里运行 git 来检查该文件是否被跟踪；任何设置文件里的 disabledMcpjsonServers 条目仍然拒绝该服务器。

状态详情：/mcp 和 /plugin 管理器里，曾用过的远程 HTTP 或 SSE 服务器可显示 cached 状态，如 cached 2h ago · connects on first use · 5 tools——Claude Code 在第一次工具调用时才连接它，而不是启动时；发现缓存默认关闭，除非逐步放量对你的账号启用，设 MCP_DISCOVERY_CACHE=1 开启、0 保持关闭；在 /mcp 菜单里选 Disable 或 Clear authentication 也会丢弃该服务器的缓存条目。服务器 ✘ Failed to connect 时，claude mcp list 把失败详情附在状态行后，claude mcp get <名称> 在 Issue: 行显示 HTTP 状态或错误码及服务器返回的错误文本；认证完成后连接仍失败时，Claude Code 在消息里加上错误码和服务器 URL 的来源（origin）——路径和查询串不会出现，${VAR} 引用按配置里写的样子显示不展开，没有状态或错误码的失败只显示错误文本。配置里 url 为空的远程服务器在 /mcp、claude mcp list、/plugin 里显示为 not configured，不尝试连接。

配置警告：隐藏的首尾空白（常来自粘贴带尾部换行的令牌，会检查 command、url、每个 args 条目和 env 值等）；同名服务器在多个范围里用了不同端点（在 claude mcp list 和 /mcp 里警告冲突）；保留名称（Claude Code 内置服务器的名字，如 workspace、claude-in-chrome、computer-use、Claude Preview、Claude Browser）；缺失环境变量（${VAR} 引用的变量没设置且没有 :-default）。工具可用性：/mcp 面板在每个已连接服务器旁显示工具数，并标出声明了 tools 能力却没有暴露任何工具的服务器。你的请求需要仍在后台连接的服务器的工具时，Claude 会等它：启用工具搜索（默认）时等待发生在 ToolSearch 调用里；没有工具搜索（自定义 ANTHROPIC_BASE_URL、ENABLE_TOOL_SEARCH=false、Agent Platform 上早于 Claude 4.5 一代的模型等）时 Claude 改用 WaitForMcpServers 工具；Azure 上托管的 Microsoft Foundry 部署则直接走工具搜索路径。启用工具搜索时，某服务器在 Claude 工作期间连好，Claude Code 会在同一回合的下一次请求里把它的工具名列给 Claude。

不删除地禁用服务器

在 /mcp 面板里把服务器切换为关闭，就让 Claude Code 不再连接它而保留配置（仍在 /mcp 里列出并标为禁用）。你的选择按项目记录在 ~/.claude.json，分两个不相交的列表：disabledMcpServers（对用户配置的服务器、插件服务器、组织通过托管设置提供的服务器、Claude Code 自己拉取的 claude.ai 连接器等的「退出」列表）和 enabledMcpServers（对默认关闭的内置服务器如 computer-use 的「加入」列表，只有列在这里才连接）。Claude Code 对每个服务器只查其中一个列表，互不覆盖；把普通服务器加进 enabledMcpServers 或把默认关闭的内置服务器加进 disabledMcpServers，该条目会被忽略。这两个列表与控制 .mcp.json 批准的 enabledMcpjsonServers/disabledMcpjsonServers 设置无关。

MCP 客户端运行时

Claude Code 通过两种客户端运行时之一连接 MCP 服务器：v1 基于 MCP TypeScript SDK 1.x，v2 是同一份代码换成 SDK 2.0（新增对 MCP 较新协议修订的支持）。每次启动时选定一个并保持到退出：能拉取功能开关的会话里在 v2.1.232 及以上用 v2；不拉取功能开关的会话里，v2.1.274 及以上在这些情形默认用 v2：Bedrock、Claude Platform on AWS、Agent Platform、Foundry 上的会话（除非嵌入宿主设置了 CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST），通过 Claude apps gateway 登录的会话，以及你关闭了遥测或功能开关拉取的会话。v2 上 Claude Code 还会：询问 HTTP 服务器是否支持较新修订并对支持的使用它（在拉取开关的会话里对 claude.ai 连接器服务器也询问；要让它也询问 stdio 服务器或所有会话里的连接器，设 MCP_PROTOCOL_NEGOTIATION=auto）；通过它持有的打开流接收较新修订服务器的 list_changed 通知；不注册协商到较新修订的 channel 服务器（该修订不能承载 channel 消息）；对授权响应里点名了意外签发者的 MCP OAuth 登录判为失败；只向 HTTPS 或 localhost/127.0.0.1/::1 的令牌端点发送 MCP OAuth 凭证（令牌端点在别处是明文 http:// 的服务器登录会失败）。想自己选择运行时设 MCP_SDK_GENERATION 为 v1 或 v2；决定是否询问设 MCP_PROTOCOL_NEGOTIATION 为 auto 或 legacy。

动态工具更新与自动重连

Claude Code 支持 MCP 的 list_changed 通知：服务器可以动态更新它的工具、提示和资源，无需断开重连；刷新请求失败时 Claude Code 保留先前发现的内容直到之后某次刷新成功（v2.1.214 之前瞬时错误会替换掉它们）。v2 运行时里，接收 list_changed 的流关闭时会重新打开，有两条限制：10 秒内再次关闭则最多重开三次然后对该连接停止；流保持超过 10 秒后才关闭（无服务器主机常见），一小时内重开五次之后要等约六小时才再重开；这期间保留服务器最后获取的内容，想更快拾取变化就在 /mcp 里重连。

自动重连：Claude Code 重连会话中途掉线的远程服务器，并在瞬时错误后重试 HTTP 或 SSE 服务器的首次连接；stdio 是本地进程，不自动重连。掉线的远程服务器用指数退避重连：最多五次、起始延迟一秒、每次翻倍；交互会话里 /mcp 在重连期间显示该服务器为 pending，五次失败后标为失败（需要重新授权则标为需要认证）；claude -p 和 Agent SDK 会话按同一时间表重连但没有面板可看。首次连接遇到瞬时错误（5xx、连接被拒、超时）时重试最多三次，仍失败就标为失败；不重试的情形：WebSocket 服务器的首次连接，以及认证或未找到错误（需要改配置才能解决；headersHelper 是 Authorization 头唯一来源时见认证页）。服务器连接后发出的能力发现请求（tools/list、prompts/list、resources/list）在瞬时网络或服务器错误后用短退避重试最多三次。Claude 如何得知服务器失败：启用工具搜索（默认）时，Claude Code 告诉 Claude 哪个服务器失败及其连接错误，Claude 会在回复里报告，并在找不到匹配工具的 ToolSearch 结果里附同样信息；没有工具搜索的配置里，Claude Code 不向 Claude 报告失败的服务器连接。

channel 推送

MCP 服务器可以把消息直接推进你的会话，让 Claude 对 CI 结果、监控告警、聊天消息等外部事件作出反应：服务器声明 claude/channel 能力并由你选择启用（详见 channel 页）。v2 运行时里，设置了 MCP_PROTOCOL_NEGOTIATION=auto 且 channel 服务器协商到 MCP 协议修订 2026-07-28 时，它无法送达 channel 消息，Claude Code 不注册它。

超时与自动转后台

每个服务器的 timeout 是每次工具调用的硬墙钟上限（见安装页）。另有空闲超时：对一次既无响应也无进度通知持续一个空闲窗口的 MCP 工具调用，会以错误中止而不是等到墙钟上限；它适用于除 IDE 服务器和 SDK 服务器之外的每种服务器类型，用 CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT（毫秒）调整窗口，设为 0 关闭检查。这些超时限定的是调用能运行多久，不总是它阻塞会话多久：主对话里运行超过两分钟的 MCP 工具调用会先转为后台任务，Claude 立刻收到任务 ID 并继续工作，结果作为任务通知到达；任务出现在 /tasks 里（可在那里停止），退出会话后不保留，条目显示服务器报告的最新进度；调用在后台运行时每调用限制仍适用。用 CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS 改阈值或设 0 关闭自动转后台（CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 也会关闭）。有些调用从不转后台：子智能体的调用（只有主对话调用会转）、对 IDE 服务器的调用、非交互模式里的调用（除非 CLAUDE_AUTO_BACKGROUND_TASKS=1，因为一次性运行可能在结果到达前就结束）；等待打开着的 elicitation 对话框的调用在对话框打开期间也不转后台（服务器在等你输入而不是慢），对话框关闭后才推迟转移。

插件提供的 MCP 服务器

插件可以打包 MCP 服务器，在你启用插件时提供工具和集成，工作方式与用户配置的服务器完全一致：插件在其根目录的 .mcp.json 或 plugin.json 里内联定义；启用插件时 Claude Code 自动启动其服务器；插件 MCP 工具与手动配置的并列提供；通过安装或卸载插件来添加或移除插件服务器，而不是用 /mcp 命令（仍可在 /mcp 里把已安装的插件服务器切换为关闭）。

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

生命周期：会话启动时自动连接已启用插件的服务器（曾用过的远程插件服务器可能显示 cached 状态）；会话中启用或禁用插件时，变更生效时连接或断开其服务器；重载时配置未变的插件服务器保持活连接；用 /cd 移动会话（v2.1.246+）时，连接新目录设置所启用插件的服务器并断开不再启用的；云会话里对尚未连接的插件服务器的 MCP 调用（如空闲会话刚唤醒）会按需启动该服务器并等它连上。路径占位符：${CLAUDE_PLUGIN_ROOT} 解析为插件的安装目录，${CLAUDE_PLUGIN_DATA} 为其持久状态目录，${CLAUDE_PROJECT_DIR} 为项目根；字段：stdio 服务器用 command、args、env，http/sse/ws 服务器用 url、headers、headersHelper；插件服务器可访问与手动配置的服务器同样的用户环境变量，支持 stdio、SSE、HTTP、WebSocket 多种传输（视服务器而定）。插件服务器在 /mcp 里带插件来源标记。对插件的 stdio 服务器，claude mcp get 打印 Command: stdio、空的 Args: 行，每个环境变量显示为 NAME=[REDACTED]（可能带凭证所以隐藏）。插件 MCP 工具名包含插件名和服务器键：完整形式 mcp__plugin_<插件名>_<服务器键>__<工具名>，其中 A-Z、a-z、0-9、_、- 之外的字符被替换为 _，如 mcp__plugin_my-plugin_database-tools__query；在权限规则、Skill 的 allowed-tools、子智能体的 tools 字段或 Hook matcher 里引用该工具时用这个完整名称；服务器本身以带作用域的名称 plugin:<插件名>:<服务器键>（如 plugin:my-plugin:database-tools）注册，在需要已配置服务器名的地方（如 mcp_tool Hook 的 server 字段）用它。