1. 從一次 MCP 連接失敗說起McpClientManager 到底管什么如果你最近在折騰 Gemini cli 的 MCP 工具鏈大概率遇到過這種場景配置文件里明明寫了三四個 MCP server啟動后卻只有一兩個工具能用日志里飄著Error during discovery for server xxx或者干脆連mcp-client-update事件都沒觸發(fā)。這類問題十有八九不是 MCP server 本身寫錯了而是McpClientManager在配置加載、權(quán)限校驗、異步發(fā)現(xiàn)這幾個環(huán)節(jié)里做了取舍。McpClientManager是 Gemini cli 里負責 MCP 客戶端全生命周期的核心類位置在packages/core/src/tools/mcp-client-manager.ts。它要做的事情可以拆成四塊把配置里的 MCP server 拉起來、連接并發(fā)現(xiàn)工具、把工具注冊進ToolRegistry、在擴展加載/卸載時動態(tài)增刪客戶端。它同時管本地子進程stdio 方式和遠程 MCP 服務(wù)器SSE/HTTP 方式所以你在配置里寫的command、args、url、httpUrl這些字段最終都是被它讀進去決定怎么連的。對本地開發(fā)調(diào)試來說理解它的行為有兩個直接好處。第一你能判斷“配置沒生效”到底是文件路徑不對、字段名寫錯還是被isAllowedMcpServer攔了。第二你能把 MCP server 的 endpoint 統(tǒng)一改到一個穩(wěn)定的 API 通道上比如把遠程 MCP 的 base URL 指向 TaoToken 的 API 入口這樣 Key 和調(diào)用通道集中管理排查連接問題時不用在多個服務(wù)之間來回切換。我試過在同一個項目里同時掛本地 stdio server 和遠程 HTTP server結(jié)果遠程那個一直 discovery 失敗最后發(fā)現(xiàn)是isTrustedFolder()返回 false 導致startConfiguredMcpServers直接 return 了。這個坑很典型下面按源碼結(jié)構(gòu)一步步拆。2. TaoToken 前置準備統(tǒng)一 Key 與 API 通道在動 Gemini cli 的 MCP 配置之前先把上游 API 通道準備好。TaoToken 在這里的角色是統(tǒng)一的模型/API 入口你可以在它的控制臺里生成 Key然后把 MCP server 或 Gemini cli 自身的模型請求都指到同一個 base URL減少“這個 Key 對哪個服務(wù)”的混亂。需要提前拿到的三樣東西后面配置里會反復用到Base URLhttps://taotoken.net/apiAPI Key在控制臺創(chuàng)建形如sk-...Model ID按你實際要調(diào)的模型填比如claude-sonnet-4-5這類標識控制臺入口在這里創(chuàng)建 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如果你只是想先驗證模型通道是否通可以用模型對話頁面直接發(fā)一條消息確認 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這里要強調(diào)一點TaoToken 是正常的 API 服務(wù)入口不是所謂“中轉(zhuǎn)”或灰色通道配置時按官方文檔的 base URL 和鑒權(quán)頭寫就行。MCP server 如果本身要調(diào)模型就把它的OPENAI_BASE_URL或ANTHROPIC_BASE_URL指向https://taotoken.net/apiKey 用同一個這樣McpClientManager在 discovery 階段觸發(fā)的工具調(diào)用和 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的對應(yīng)關(guān)系要說清楚。commandargs走的是本地子進程分支McpClient會用 stdio 起進程httpUrl走遠程分支連接時用 HTTP 傳輸。env里的變量會注入到子進程環(huán)境所以本地 server 要調(diào)模型時API_BASE_URL和API_KEY從這里傳最省事。如果你用的是 TOML 風格的配置部分版本或擴展里會出現(xiàn)等價寫法如下[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里會先調(diào)populateMcpServerCommand把getMcpServerCommand()的命令行覆蓋合并進配置。也就是說如果你啟動 Gemini cli 時帶了--mcp-server之類的參數(shù)它會覆蓋文件里的同名 server。調(diào)試時先確認沒有命令行覆蓋否則你會以為配置文件沒被讀取。另外isAllowedMcpServer的白名單/黑名單邏輯要留意。如果getAllowedMcpServers()返回了非空數(shù)組那么只有數(shù)組里的名字才會被連接其他全部進blockedMcpServers。所以配置里 server 的 key 名要和白名單完全一致大小寫敏感。4. 驗證請求確認連接與工具發(fā)現(xiàn)成功配置寫完后不要直接上復雜任務(wù)先用最小步驟驗證McpClientManager是否真的把 server 連上并發(fā)現(xiàn)了工具。第一步啟動 Gemini cli 并打開 debug 日志。McpClientManager里大量使用debugLogger.log和debugLogger.warn開啟后能看到Loading extension: xxx、Error stopping client這類輸出。DEBUG* gemini --debug第二步觀察 discovery 狀態(tài)。McpClientManager內(nèi)部有MCPDiscoveryState從NOT_STARTED到IN_PROGRESS再到COMPLETED。如果一直停在IN_PROGRESS說明某個 server 的connect()或discover()卡住了常見原因是遠程httpUrl不可達或鑒權(quán)失敗。第三步用一次實際工具調(diào)用驗證。在 Gemini cli 里讓它列一下當前可用工具或者直接觸發(fā)一個 MCP 工具。成功的話ToolRegistry里會多出對應(yīng)工具mcp-client-update事件也會帶著更新后的clientsMap 發(fā)出。如果你想繞過 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數(shù)組就說明通道沒問題。這一步能幫你把“MCP 連接失敗”和“上游 API 鑒權(quán)失敗”區(qū)分開——前者看McpClientManager日志后者看 HTTP 狀態(tài)碼。第四步檢查工具是否注冊成功。McpClientManager在disconnectClient和 discovery 完成后都會調(diào)geminiClient.setTools()前提是geminiClient.isInitialized()為 true。如果工具沒出現(xiàn)先確認 Gemini 客戶端已經(jīng)初始化再看toolRegistry里有沒有對應(yīng)條目。5. 常見錯誤排查401、local proxy failed、reading choices、OAuth這一節(jié)按真實報錯來對照都是McpClientManager場景下高頻出現(xiàn)的。401 Unauthorized遠程 MCP server 的headers.Authorization沒帶或 Key 失效。檢查Bearer sk-...是否完整Key 是否在 TaoToken 控制臺被刪除或過期。本地 stdio server 如果自己調(diào)模型檢查env.API_KEY是否注入成功可以在 server 啟動日志里打印process.env.API_KEY的前幾位確認。local proxy failed這個通常出現(xiàn)在本地 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 節(jié)的 curl 先驗證一次。OAuth 相關(guān)錯誤部分遠程 MCP server 要求 OAuth 流程McpClientManager本身不處理 OAuth 交互它只負責連接和發(fā)現(xiàn)。如果 server 配置里需要 token 刷新得在 server 側(cè)或通過靜態(tài) header 解決。調(diào)試階段建議先用靜態(tài) Bearer token 跑通再考慮動態(tài)憑證。排查順序建議固定成先看isTrustedFolder()是否為 true再看isAllowedMcpServer是否放行然后看connect()是否成功最后看discover()是否返回工具。這四步對應(yīng)McpClientManager里maybeDiscoverMcpServer的主流程按順序查能省很多時間。6. 把通道固定下來長期編碼與 Agent 場景的配置建議如果你打算長期用 Gemini cli 跑編碼或 Agent 任務(wù)MCP server 數(shù)量會越來越多這時候統(tǒng)一通道的價值就體現(xiàn)出來了。所有需要調(diào)模型的 MCP server 都指向同一個 TaoToken base URLKey 只維護一份McpClientManager的 discovery 日志里出現(xiàn)鑒權(quán)問題時也只需要查一個來源。對于需要長時間運行的編碼任務(wù)可以用 Coding Plan 把模型調(diào)用額度固定下來避免調(diào)試到一半 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的行為是確定性的配置對了它就能連上連不上一定是某個字段或權(quán)限環(huán)節(jié)出了問題按第 5 節(jié)的順序查就行。 Gemini cli 源碼分析之工具篇-McpClientManager 的 MCP 連接與配置拆解
1. 從一次 MCP 連接失敗說起McpClientManager 到底管什么如果你最近在折騰 Gemini cli 的 MCP 工具鏈大概率遇到過這種場景配置文件里明明寫了三四個 MCP server啟動后卻只有一兩個工具能用日志里飄著Error during discovery for server xxx或者干脆連mcp-client-update事件都沒觸發(fā)。這類問題十有八九不是 MCP server 本身寫錯了而是McpClientManager在配置加載、權(quán)限校驗、異步發(fā)現(xiàn)這幾個環(huán)節(jié)里做了取舍。McpClientManager是 Gemini cli 里負責 MCP 客戶端全生命周期的核心類位置在packages/core/src/tools/mcp-client-manager.ts。它要做的事情可以拆成四塊把配置里的 MCP server 拉起來、連接并發(fā)現(xiàn)工具、把工具注冊進ToolRegistry、在擴展加載/卸載時動態(tài)增刪客戶端。它同時管本地子進程stdio 方式和遠程 MCP 服務(wù)器SSE/HTTP 方式所以你在配置里寫的command、args、url、httpUrl這些字段最終都是被它讀進去決定怎么連的。對本地開發(fā)調(diào)試來說理解它的行為有兩個直接好處。第一你能判斷“配置沒生效”到底是文件路徑不對、字段名寫錯還是被isAllowedMcpServer攔了。第二你能把 MCP server 的 endpoint 統(tǒng)一改到一個穩(wěn)定的 API 通道上比如把遠程 MCP 的 base URL 指向 TaoToken 的 API 入口這樣 Key 和調(diào)用通道集中管理排查連接問題時不用在多個服務(wù)之間來回切換。我試過在同一個項目里同時掛本地 stdio server 和遠程 HTTP server結(jié)果遠程那個一直 discovery 失敗最后發(fā)現(xiàn)是isTrustedFolder()返回 false 導致startConfiguredMcpServers直接 return 了。這個坑很典型下面按源碼結(jié)構(gòu)一步步拆。2. TaoToken 前置準備統(tǒng)一 Key 與 API 通道在動 Gemini cli 的 MCP 配置之前先把上游 API 通道準備好。TaoToken 在這里的角色是統(tǒng)一的模型/API 入口你可以在它的控制臺里生成 Key然后把 MCP server 或 Gemini cli 自身的模型請求都指到同一個 base URL減少“這個 Key 對哪個服務(wù)”的混亂。需要提前拿到的三樣東西后面配置里會反復用到Base URLhttps://taotoken.net/apiAPI Key在控制臺創(chuàng)建形如sk-...Model ID按你實際要調(diào)的模型填比如claude-sonnet-4-5這類標識控制臺入口在這里創(chuàng)建 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如果你只是想先驗證模型通道是否通可以用模型對話頁面直接發(fā)一條消息確認 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這里要強調(diào)一點TaoToken 是正常的 API 服務(wù)入口不是所謂“中轉(zhuǎn)”或灰色通道配置時按官方文檔的 base URL 和鑒權(quán)頭寫就行。MCP server 如果本身要調(diào)模型就把它的OPENAI_BASE_URL或ANTHROPIC_BASE_URL指向https://taotoken.net/apiKey 用同一個這樣McpClientManager在 discovery 階段觸發(fā)的工具調(diào)用和 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的對應(yīng)關(guān)系要說清楚。commandargs走的是本地子進程分支McpClient會用 stdio 起進程httpUrl走遠程分支連接時用 HTTP 傳輸。env里的變量會注入到子進程環(huán)境所以本地 server 要調(diào)模型時API_BASE_URL和API_KEY從這里傳最省事。如果你用的是 TOML 風格的配置部分版本或擴展里會出現(xiàn)等價寫法如下[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里會先調(diào)populateMcpServerCommand把getMcpServerCommand()的命令行覆蓋合并進配置。也就是說如果你啟動 Gemini cli 時帶了--mcp-server之類的參數(shù)它會覆蓋文件里的同名 server。調(diào)試時先確認沒有命令行覆蓋否則你會以為配置文件沒被讀取。另外isAllowedMcpServer的白名單/黑名單邏輯要留意。如果getAllowedMcpServers()返回了非空數(shù)組那么只有數(shù)組里的名字才會被連接其他全部進blockedMcpServers。所以配置里 server 的 key 名要和白名單完全一致大小寫敏感。4. 驗證請求確認連接與工具發(fā)現(xiàn)成功配置寫完后不要直接上復雜任務(wù)先用最小步驟驗證McpClientManager是否真的把 server 連上并發(fā)現(xiàn)了工具。第一步啟動 Gemini cli 并打開 debug 日志。McpClientManager里大量使用debugLogger.log和debugLogger.warn開啟后能看到Loading extension: xxx、Error stopping client這類輸出。DEBUG* gemini --debug第二步觀察 discovery 狀態(tài)。McpClientManager內(nèi)部有MCPDiscoveryState從NOT_STARTED到IN_PROGRESS再到COMPLETED。如果一直停在IN_PROGRESS說明某個 server 的connect()或discover()卡住了常見原因是遠程httpUrl不可達或鑒權(quán)失敗。第三步用一次實際工具調(diào)用驗證。在 Gemini cli 里讓它列一下當前可用工具或者直接觸發(fā)一個 MCP 工具。成功的話ToolRegistry里會多出對應(yīng)工具mcp-client-update事件也會帶著更新后的clientsMap 發(fā)出。如果你想繞過 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數(shù)組就說明通道沒問題。這一步能幫你把“MCP 連接失敗”和“上游 API 鑒權(quán)失敗”區(qū)分開——前者看McpClientManager日志后者看 HTTP 狀態(tài)碼。第四步檢查工具是否注冊成功。McpClientManager在disconnectClient和 discovery 完成后都會調(diào)geminiClient.setTools()前提是geminiClient.isInitialized()為 true。如果工具沒出現(xiàn)先確認 Gemini 客戶端已經(jīng)初始化再看toolRegistry里有沒有對應(yīng)條目。5. 常見錯誤排查401、local proxy failed、reading choices、OAuth這一節(jié)按真實報錯來對照都是McpClientManager場景下高頻出現(xiàn)的。401 Unauthorized遠程 MCP server 的headers.Authorization沒帶或 Key 失效。檢查Bearer sk-...是否完整Key 是否在 TaoToken 控制臺被刪除或過期。本地 stdio server 如果自己調(diào)模型檢查env.API_KEY是否注入成功可以在 server 啟動日志里打印process.env.API_KEY的前幾位確認。local proxy failed這個通常出現(xiàn)在本地 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 節(jié)的 curl 先驗證一次。OAuth 相關(guān)錯誤部分遠程 MCP server 要求 OAuth 流程McpClientManager本身不處理 OAuth 交互它只負責連接和發(fā)現(xiàn)。如果 server 配置里需要 token 刷新得在 server 側(cè)或通過靜態(tài) header 解決。調(diào)試階段建議先用靜態(tài) Bearer token 跑通再考慮動態(tài)憑證。排查順序建議固定成先看isTrustedFolder()是否為 true再看isAllowedMcpServer是否放行然后看connect()是否成功最后看discover()是否返回工具。這四步對應(yīng)McpClientManager里maybeDiscoverMcpServer的主流程按順序查能省很多時間。6. 把通道固定下來長期編碼與 Agent 場景的配置建議如果你打算長期用 Gemini cli 跑編碼或 Agent 任務(wù)MCP server 數(shù)量會越來越多這時候統(tǒng)一通道的價值就體現(xiàn)出來了。所有需要調(diào)模型的 MCP server 都指向同一個 TaoToken base URLKey 只維護一份McpClientManager的 discovery 日志里出現(xiàn)鑒權(quán)問題時也只需要查一個來源。對于需要長時間運行的編碼任務(wù)可以用 Coding Plan 把模型調(diào)用額度固定下來避免調(diào)試到一半 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的行為是確定性的配置對了它就能連上連不上一定是某個字段或權(quán)限環(huán)節(jié)出了問題按第 5 節(jié)的順序查就行。