1. 从一次 MCP 连接失败说起McpClientManager 到底管什么如果你最近在折腾 Gemini cli 的 MCP 工具链大概率遇到过这种场景配置文件里明明写了三四个 MCP server启动后却只有一两个工具能用日志里飘着Error during discovery for server xxx或者干脆连mcp-client-update事件都没触发。这类问题十有八九不是 MCP server 本身写错了而是McpClientManager在配置加载、权限校验、异步发现这几个环节里做了取舍。McpClientManager是 Gemini cli 里负责 MCP 客户端全生命周期的核心类位置在packages/core/src/tools/mcp-client-manager.ts。它要做的事情可以拆成四块把配置里的 MCP server 拉起来、连接并发现工具、把工具注册进ToolRegistry、在扩展加载/卸载时动态增删客户端。它同时管本地子进程stdio 方式和远程 MCP 服务器SSE/HTTP 方式所以你在配置里写的command、args、url、httpUrl这些字段最终都是被它读进去决定怎么连的。对本地开发调试来说理解它的行为有两个直接好处。第一你能判断“配置没生效”到底是文件路径不对、字段名写错还是被isAllowedMcpServer拦了。第二你能把 MCP server 的 endpoint 统一改到一个稳定的 API 通道上比如把远程 MCP 的 base URL 指向 TaoToken 的 API 入口这样 Key 和调用通道集中管理排查连接问题时不用在多个服务之间来回切换。我试过在同一个项目里同时挂本地 stdio server 和远程 HTTP server结果远程那个一直 discovery 失败最后发现是isTrustedFolder()返回 false 导致startConfiguredMcpServers直接 return 了。这个坑很典型下面按源码结构一步步拆。2. TaoToken 前置准备统一 Key 与 API 通道在动 Gemini cli 的 MCP 配置之前先把上游 API 通道准备好。TaoToken 在这里的角色是统一的模型/API 入口你可以在它的控制台里生成 Key然后把 MCP server 或 Gemini cli 自身的模型请求都指到同一个 base URL减少“这个 Key 对哪个服务”的混乱。需要提前拿到的三样东西后面配置里会反复用到Base URLhttps://taotoken.net/apiAPI Key在控制台创建形如sk-...Model ID按你实际要调的模型填比如claude-sonnet-4-5这类标识控制台入口在这里创建 Key 的页面在 API Keys 里控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmcp_client_manager API Keyshttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmcp_client_manager如果你只是想先验证模型通道是否通可以用模型对话页面直接发一条消息确认 Key 和 base URL 没问题再去改 MCP 配置模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmcp_client_manager接入文档在 doc 页面里面有各语言 SDK 的 base URL 写法MCP 场景下主要看 HTTP/SSE 那部分接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmcp_client_manager这里要强调一点TaoToken 是正常的 API 服务入口不是所谓“中转”或灰色通道配置时按官方文档的 base URL 和鉴权头写就行。MCP server 如果本身要调模型就把它的OPENAI_BASE_URL或ANTHROPIC_BASE_URL指向https://taotoken.net/apiKey 用同一个这样McpClientManager在 discovery 阶段触发的工具调用和 Gemini cli 主流程用的是同一套凭证排查 401 时只需要看一个地方。3. 可复制配置MCP server 定义与 endpoint 改写Gemini cli 的 MCP 配置通常写在项目级或用户级的 settings 文件里McpClientManager通过cliConfig.getMcpServers()读取。下面给一份可直接复制的 JSON 片段包含一个本地 stdio server 和一个远程 HTTP server远程那个的 endpoint 指向 TaoToken API 通道。{ mcpServers: { local-filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, /Users/me/project], env: { API_BASE_URL: https://taotoken.net/api, API_KEY: sk-your-taotoken-key } }, remote-tools: { httpUrl: https://taotoken.net/api/mcp, headers: { Authorization: Bearer sk-your-taotoken-key, Content-Type: application/json }, env: { MODEL_ID: claude-sonnet-4-5 } } } }几个字段和McpClientManager的对应关系要说清楚。commandargs走的是本地子进程分支McpClient会用 stdio 起进程httpUrl走远程分支连接时用 HTTP 传输。env里的变量会注入到子进程环境所以本地 server 要调模型时API_BASE_URL和API_KEY从这里传最省事。如果你用的是 TOML 风格的配置部分版本或扩展里会出现等价写法如下[mcpServers.local-filesystem] command npx args [-y, modelcontextprotocol/server-filesystem, /Users/me/project] [mcpServers.local-filesystem.env] API_BASE_URL https://taotoken.net/api API_KEY sk-your-taotoken-key [mcpServers.remote-tools] httpUrl https://taotoken.net/api/mcp [mcpServers.remote-tools.headers] Authorization Bearer sk-your-taotoken-key Content-Type application/json这里有个容易踩的点McpClientManager在startConfiguredMcpServers里会先调populateMcpServerCommand把getMcpServerCommand()的命令行覆盖合并进配置。也就是说如果你启动 Gemini cli 时带了--mcp-server之类的参数它会覆盖文件里的同名 server。调试时先确认没有命令行覆盖否则你会以为配置文件没被读取。另外isAllowedMcpServer的白名单/黑名单逻辑要留意。如果getAllowedMcpServers()返回了非空数组那么只有数组里的名字才会被连接其他全部进blockedMcpServers。所以配置里 server 的 key 名要和白名单完全一致大小写敏感。4. 验证请求确认连接与工具发现成功配置写完后不要直接上复杂任务先用最小步骤验证McpClientManager是否真的把 server 连上并发现了工具。第一步启动 Gemini cli 并打开 debug 日志。McpClientManager里大量使用debugLogger.log和debugLogger.warn开启后能看到Loading extension: xxx、Error stopping client这类输出。DEBUG* gemini --debug第二步观察 discovery 状态。McpClientManager内部有MCPDiscoveryState从NOT_STARTED到IN_PROGRESS再到COMPLETED。如果一直停在IN_PROGRESS说明某个 server 的connect()或discover()卡住了常见原因是远程httpUrl不可达或鉴权失败。第三步用一次实际工具调用验证。在 Gemini cli 里让它列一下当前可用工具或者直接触发一个 MCP 工具。成功的话ToolRegistry里会多出对应工具mcp-client-update事件也会带着更新后的clientsMap 发出。如果你想绕过 CLI 直接验证 TaoToken 通道可以用 curl 打一次模型接口确认 Key 和 base URL 正确curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-your-taotoken-key \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-5, messages: [{role: user, content: ping}] }返回里能看到choices数组就说明通道没问题。这一步能帮你把“MCP 连接失败”和“上游 API 鉴权失败”区分开——前者看McpClientManager日志后者看 HTTP 状态码。第四步检查工具是否注册成功。McpClientManager在disconnectClient和 discovery 完成后都会调geminiClient.setTools()前提是geminiClient.isInitialized()为 true。如果工具没出现先确认 Gemini 客户端已经初始化再看toolRegistry里有没有对应条目。5. 常见错误排查401、local proxy failed、reading choices、OAuth这一节按真实报错来对照都是McpClientManager场景下高频出现的。401 Unauthorized远程 MCP server 的headers.Authorization没带或 Key 失效。检查Bearer sk-...是否完整Key 是否在 TaoToken 控制台被删除或过期。本地 stdio server 如果自己调模型检查env.API_KEY是否注入成功可以在 server 启动日志里打印process.env.API_KEY的前几位确认。local proxy failed这个通常出现在本地 stdio server 启动阶段command找不到或args路径错误。McpClientManager会捕获connect()的异常并通过coreEvents.emitFeedback报出来。先手动在终端跑一遍command args确认能启动再放回配置。reading choices 报错这是上游返回体解析失败多半是 base URL 拼错导致返回了 HTML 或空 body。确认API_BASE_URL是https://taotoken.net/api不要多写或少写/v1具体路径以接入文档为准。用第 4 节的 curl 先验证一次。OAuth 相关错误部分远程 MCP server 要求 OAuth 流程McpClientManager本身不处理 OAuth 交互它只负责连接和发现。如果 server 配置里需要 token 刷新得在 server 侧或通过静态 header 解决。调试阶段建议先用静态 Bearer token 跑通再考虑动态凭证。排查顺序建议固定成先看isTrustedFolder()是否为 true再看isAllowedMcpServer是否放行然后看connect()是否成功最后看discover()是否返回工具。这四步对应McpClientManager里maybeDiscoverMcpServer的主流程按顺序查能省很多时间。6. 把通道固定下来长期编码与 Agent 场景的配置建议如果你打算长期用 Gemini cli 跑编码或 Agent 任务MCP server 数量会越来越多这时候统一通道的价值就体现出来了。所有需要调模型的 MCP server 都指向同一个 TaoToken base URLKey 只维护一份McpClientManager的 discovery 日志里出现鉴权问题时也只需要查一个来源。对于需要长时间运行的编码任务可以用 Coding Plan 把模型调用额度固定下来避免调试到一半 Key 额度耗尽Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmcp_client_manager如果你在用 Claude Code 或类似的 Agent 工具链Anthropic 兼容通道的配置也在同一套体系里base URL 和 Key 复用即可ClaudeCodeAnthropichttps://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmcp_client_manager最后给一个实操建议把 MCP 配置里的 server 名、endpoint、Key 来源做成一张对照表贴在项目 README 里每次改配置先对表。McpClientManager的行为是确定性的配置对了它就能连上连不上一定是某个字段或权限环节出了问题按第 5 节的顺序查就行。 Gemini cli 源码分析之工具篇-McpClientManager 的 MCP 连接与配置拆解
1. 从一次 MCP 连接失败说起McpClientManager 到底管什么如果你最近在折腾 Gemini cli 的 MCP 工具链大概率遇到过这种场景配置文件里明明写了三四个 MCP server启动后却只有一两个工具能用日志里飘着Error during discovery for server xxx或者干脆连mcp-client-update事件都没触发。这类问题十有八九不是 MCP server 本身写错了而是McpClientManager在配置加载、权限校验、异步发现这几个环节里做了取舍。McpClientManager是 Gemini cli 里负责 MCP 客户端全生命周期的核心类位置在packages/core/src/tools/mcp-client-manager.ts。它要做的事情可以拆成四块把配置里的 MCP server 拉起来、连接并发现工具、把工具注册进ToolRegistry、在扩展加载/卸载时动态增删客户端。它同时管本地子进程stdio 方式和远程 MCP 服务器SSE/HTTP 方式所以你在配置里写的command、args、url、httpUrl这些字段最终都是被它读进去决定怎么连的。对本地开发调试来说理解它的行为有两个直接好处。第一你能判断“配置没生效”到底是文件路径不对、字段名写错还是被isAllowedMcpServer拦了。第二你能把 MCP server 的 endpoint 统一改到一个稳定的 API 通道上比如把远程 MCP 的 base URL 指向 TaoToken 的 API 入口这样 Key 和调用通道集中管理排查连接问题时不用在多个服务之间来回切换。我试过在同一个项目里同时挂本地 stdio server 和远程 HTTP server结果远程那个一直 discovery 失败最后发现是isTrustedFolder()返回 false 导致startConfiguredMcpServers直接 return 了。这个坑很典型下面按源码结构一步步拆。2. TaoToken 前置准备统一 Key 与 API 通道在动 Gemini cli 的 MCP 配置之前先把上游 API 通道准备好。TaoToken 在这里的角色是统一的模型/API 入口你可以在它的控制台里生成 Key然后把 MCP server 或 Gemini cli 自身的模型请求都指到同一个 base URL减少“这个 Key 对哪个服务”的混乱。需要提前拿到的三样东西后面配置里会反复用到Base URLhttps://taotoken.net/apiAPI Key在控制台创建形如sk-...Model ID按你实际要调的模型填比如claude-sonnet-4-5这类标识控制台入口在这里创建 Key 的页面在 API Keys 里控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmcp_client_manager API Keyshttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmcp_client_manager如果你只是想先验证模型通道是否通可以用模型对话页面直接发一条消息确认 Key 和 base URL 没问题再去改 MCP 配置模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmcp_client_manager接入文档在 doc 页面里面有各语言 SDK 的 base URL 写法MCP 场景下主要看 HTTP/SSE 那部分接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmcp_client_manager这里要强调一点TaoToken 是正常的 API 服务入口不是所谓“中转”或灰色通道配置时按官方文档的 base URL 和鉴权头写就行。MCP server 如果本身要调模型就把它的OPENAI_BASE_URL或ANTHROPIC_BASE_URL指向https://taotoken.net/apiKey 用同一个这样McpClientManager在 discovery 阶段触发的工具调用和 Gemini cli 主流程用的是同一套凭证排查 401 时只需要看一个地方。3. 可复制配置MCP server 定义与 endpoint 改写Gemini cli 的 MCP 配置通常写在项目级或用户级的 settings 文件里McpClientManager通过cliConfig.getMcpServers()读取。下面给一份可直接复制的 JSON 片段包含一个本地 stdio server 和一个远程 HTTP server远程那个的 endpoint 指向 TaoToken API 通道。{ mcpServers: { local-filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, /Users/me/project], env: { API_BASE_URL: https://taotoken.net/api, API_KEY: sk-your-taotoken-key } }, remote-tools: { httpUrl: https://taotoken.net/api/mcp, headers: { Authorization: Bearer sk-your-taotoken-key, Content-Type: application/json }, env: { MODEL_ID: claude-sonnet-4-5 } } } }几个字段和McpClientManager的对应关系要说清楚。commandargs走的是本地子进程分支McpClient会用 stdio 起进程httpUrl走远程分支连接时用 HTTP 传输。env里的变量会注入到子进程环境所以本地 server 要调模型时API_BASE_URL和API_KEY从这里传最省事。如果你用的是 TOML 风格的配置部分版本或扩展里会出现等价写法如下[mcpServers.local-filesystem] command npx args [-y, modelcontextprotocol/server-filesystem, /Users/me/project] [mcpServers.local-filesystem.env] API_BASE_URL https://taotoken.net/api API_KEY sk-your-taotoken-key [mcpServers.remote-tools] httpUrl https://taotoken.net/api/mcp [mcpServers.remote-tools.headers] Authorization Bearer sk-your-taotoken-key Content-Type application/json这里有个容易踩的点McpClientManager在startConfiguredMcpServers里会先调populateMcpServerCommand把getMcpServerCommand()的命令行覆盖合并进配置。也就是说如果你启动 Gemini cli 时带了--mcp-server之类的参数它会覆盖文件里的同名 server。调试时先确认没有命令行覆盖否则你会以为配置文件没被读取。另外isAllowedMcpServer的白名单/黑名单逻辑要留意。如果getAllowedMcpServers()返回了非空数组那么只有数组里的名字才会被连接其他全部进blockedMcpServers。所以配置里 server 的 key 名要和白名单完全一致大小写敏感。4. 验证请求确认连接与工具发现成功配置写完后不要直接上复杂任务先用最小步骤验证McpClientManager是否真的把 server 连上并发现了工具。第一步启动 Gemini cli 并打开 debug 日志。McpClientManager里大量使用debugLogger.log和debugLogger.warn开启后能看到Loading extension: xxx、Error stopping client这类输出。DEBUG* gemini --debug第二步观察 discovery 状态。McpClientManager内部有MCPDiscoveryState从NOT_STARTED到IN_PROGRESS再到COMPLETED。如果一直停在IN_PROGRESS说明某个 server 的connect()或discover()卡住了常见原因是远程httpUrl不可达或鉴权失败。第三步用一次实际工具调用验证。在 Gemini cli 里让它列一下当前可用工具或者直接触发一个 MCP 工具。成功的话ToolRegistry里会多出对应工具mcp-client-update事件也会带着更新后的clientsMap 发出。如果你想绕过 CLI 直接验证 TaoToken 通道可以用 curl 打一次模型接口确认 Key 和 base URL 正确curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-your-taotoken-key \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-5, messages: [{role: user, content: ping}] }返回里能看到choices数组就说明通道没问题。这一步能帮你把“MCP 连接失败”和“上游 API 鉴权失败”区分开——前者看McpClientManager日志后者看 HTTP 状态码。第四步检查工具是否注册成功。McpClientManager在disconnectClient和 discovery 完成后都会调geminiClient.setTools()前提是geminiClient.isInitialized()为 true。如果工具没出现先确认 Gemini 客户端已经初始化再看toolRegistry里有没有对应条目。5. 常见错误排查401、local proxy failed、reading choices、OAuth这一节按真实报错来对照都是McpClientManager场景下高频出现的。401 Unauthorized远程 MCP server 的headers.Authorization没带或 Key 失效。检查Bearer sk-...是否完整Key 是否在 TaoToken 控制台被删除或过期。本地 stdio server 如果自己调模型检查env.API_KEY是否注入成功可以在 server 启动日志里打印process.env.API_KEY的前几位确认。local proxy failed这个通常出现在本地 stdio server 启动阶段command找不到或args路径错误。McpClientManager会捕获connect()的异常并通过coreEvents.emitFeedback报出来。先手动在终端跑一遍command args确认能启动再放回配置。reading choices 报错这是上游返回体解析失败多半是 base URL 拼错导致返回了 HTML 或空 body。确认API_BASE_URL是https://taotoken.net/api不要多写或少写/v1具体路径以接入文档为准。用第 4 节的 curl 先验证一次。OAuth 相关错误部分远程 MCP server 要求 OAuth 流程McpClientManager本身不处理 OAuth 交互它只负责连接和发现。如果 server 配置里需要 token 刷新得在 server 侧或通过静态 header 解决。调试阶段建议先用静态 Bearer token 跑通再考虑动态凭证。排查顺序建议固定成先看isTrustedFolder()是否为 true再看isAllowedMcpServer是否放行然后看connect()是否成功最后看discover()是否返回工具。这四步对应McpClientManager里maybeDiscoverMcpServer的主流程按顺序查能省很多时间。6. 把通道固定下来长期编码与 Agent 场景的配置建议如果你打算长期用 Gemini cli 跑编码或 Agent 任务MCP server 数量会越来越多这时候统一通道的价值就体现出来了。所有需要调模型的 MCP server 都指向同一个 TaoToken base URLKey 只维护一份McpClientManager的 discovery 日志里出现鉴权问题时也只需要查一个来源。对于需要长时间运行的编码任务可以用 Coding Plan 把模型调用额度固定下来避免调试到一半 Key 额度耗尽Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmcp_client_manager如果你在用 Claude Code 或类似的 Agent 工具链Anthropic 兼容通道的配置也在同一套体系里base URL 和 Key 复用即可ClaudeCodeAnthropichttps://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmcp_client_manager最后给一个实操建议把 MCP 配置里的 server 名、endpoint、Key 来源做成一张对照表贴在项目 README 里每次改配置先对表。McpClientManager的行为是确定性的配置对了它就能连上连不上一定是某个字段或权限环节出了问题按第 5 节的顺序查就行。