1. 為什么你的 MCP 智能體越跑越貴從工具定義膨脹說起如果你最近在折騰 Anthropic 的 MCPModel Context Protocol大概率會遇到一個很反直覺的現象工具接得越多智能體反而越笨、越慢、越燒錢。我一開始也以為是模型能力問題后來把請求日志拉出來一看才發(fā)現真正的元兇是上下文窗口被工具定義和中間結果塞爆了。MCP 是 Anthropic 在 2024 年 11 月推出的開放標準目標是讓智能體用一套通用協(xié)議連接外部系統(tǒng)不用再為每個工具寫一遍膠水代碼。這個愿景很好社區(qū)也確實建了成千上萬個 MCP Server主流語言都有 SDK。但問題在于大多數 MCP 客戶端的默認行為是在對話開始前把所有已連接 Server 的工具定義一次性預加載進上下文。你連了 5 個 Server、每個 Server 20 個工具那就是 100 份工具描述光這些描述就可能吃掉幾萬 token模型還沒開始讀你的問題上下文已經用掉一大半。更隱蔽的坑是中間結果。舉個典型場景你讓智能體“把 Google Drive 里的會議紀要讀出來寫進 Salesforce 的潛在客戶記錄”。傳統(tǒng)直接調用模式下模型會先調gdrive.getDocument返回的完整紀要文本進入上下文然后模型再調salesforce.updateRecord把這段完整文本又寫一遍進上下文。一份兩小時的會議紀要可能 5 萬 token等于同一份數據在上下文里流了兩遍。文檔再大一點直接超上下文窗口工作流當場斷掉。Anthropic 那篇《Code execution with MCP: Building more efficient agents》給出的解法很工程化別讓模型直接調工具讓模型寫代碼去調工具。把 MCP Server 包裝成代碼 API工具定義以文件樹形式存在文件系統(tǒng)里模型按需讀取它當前任務真正需要的那幾個文件中間數據在執(zhí)行環(huán)境里先過濾、聚合、裁剪只把最終需要的那幾行結果返回給模型。官方給的數字是從 15 萬 token 降到 2000 token省了 98.7% 的成本和時間。這篇就沿著這個思路用一個 TypeScript 項目 Demo把代碼執(zhí)行型 MCP 智能體從零跑通。中間會用到 TaoToken 的統(tǒng)一 Key 和 API 通道來接入 Anthropic 模型這樣你不用在多個平臺之間來回切 Key一個通道就能把 MCP 工具鏈和模型調用串起來。適合已經了解 MCP 基本概念、想把它真正落到代碼執(zhí)行場景的開發(fā)者。2. TaoToken 統(tǒng)一 Key 接入把 Anthropic 模型通道先打通在寫 MCP Server 和智能體代碼之前得先把模型通道準備好。代碼執(zhí)行型智能體的核心是“模型生成代碼 → 執(zhí)行環(huán)境跑代碼 → 結果回傳模型”這個循環(huán)里模型調用會非常頻繁如果 Key 管理混亂、通道不穩(wěn)定調試成本會成倍上升。我用 TaoToken 的統(tǒng)一 Key 來收口這件事一個 Key 走通 Anthropic 模型調用省去多平臺切換的麻煩。先說清楚它在這里扮演的角色TaoToken 提供統(tǒng)一的 API 通道你拿到的 Key 可以用于調用 Anthropic 系列模型Base URL 指向https://taotoken.net/api。注意 API 地址不帶任何查詢參數保持干凈。官網入口是https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content注冊和查看文檔都從這里進。拿 Key 的路徑很直接進官網后找到控制臺在 API Keys 頁面創(chuàng)建一個新 Key。建議按項目維度建 Key比如這個 MCP Demo 單獨一個方便后面排查問題時定位是哪個項目在消耗額度。創(chuàng)建完把 Key 復制出來形如sk-開頭的一串字符先存到環(huán)境變量里別硬編碼進代碼。# .env 文件放在項目根目錄 TAOTOKEN_API_KEYsk-你的實際Key TAOTOKEN_BASE_URLhttps://taotoken.net/api這里有個容易踩的坑Base URL 到底要不要帶/v1。不同 SDK 對路徑的處理不一樣Anthropic 官方 SDK 默認會在 Base URL 后面拼/v1/messages所以你的 Base URL 填到https://taotoken.net/api就行不要再手動加/v1否則會變成/api/v1/v1/messages直接 404。我第一次配的時候就栽在這報錯信息還比較隱晦排查了半天。模型 ID 這塊代碼執(zhí)行場景建議用 Claude 系列里支持工具調用和長上下文能力較好的型號。具體可用型號以 TaoToken 控制臺或文檔里列出的為準因為模型列表會更新我不在這里寫死。你在控制臺能看到當前可用的 Model ID復制那個字符串填到配置里。如果你同時還在用 Claude Code 做日常編碼TaoToken 的 Coding Plan 可以把編碼場景和這個 MCP Demo 的調用分開管理額度互不干擾。接入文檔在官網的 doc 頁面里面有各語言 SDK 的配置示例遇到路徑或鑒權問題時對著文檔核對一遍最快。把 Key 和 Base URL 準備好之后先別急著寫 MCP 邏輯用一段最小代碼驗證通道是否通。這一步很重要因為后面 MCP 報錯時你得能區(qū)分是模型通道的問題還是 MCP 配置的問題。驗證代碼用 Anthropic 官方 SDK// verify-channel.ts import Anthropic from anthropic-ai/sdk; import dotenv/config; const client new Anthropic({ apiKey: process.env.TAOTOKEN_API_KEY, baseURL: process.env.TAOTOKEN_BASE_URL, }); async function main() { const msg await client.messages.create({ model: 你的Model ID, max_tokens: 128, messages: [{ role: user, content: 只回復兩個字通了 }], }); console.log(msg.content); } main().catch(console.error);跑npx tsx verify-channel.ts如果輸出里能看到模型返回的內容說明通道沒問題。如果報 401檢查 Key 是否復制完整、有沒有多余空格如果報連接錯誤檢查 Base URL 是否寫成了帶/v1的形式。這一步過了再往下搭 MCP 才有意義。3. 可復制的 MCP Server 配置與代碼執(zhí)行環(huán)境搭建通道驗證通過后進入核心部分把 MCP Server 包裝成代碼 API并搭好代碼執(zhí)行環(huán)境。這一節(jié)會給出可直接復制的配置文件片段和 TypeScript 代碼路徑和原文保持一致你照著建目錄就行。先規(guī)劃項目結構。核心思路是每個 MCP Server 對應一個目錄每個工具對應一個.ts文件文件里導出一個函數函數內部通過統(tǒng)一的callMCPTool去真正調用 MCP 工具。模型通過瀏覽文件系統(tǒng)來發(fā)現工具只讀它需要的文件。mcp-code-agent/ ├── .env ├── package.json ├── tsconfig.json ├── client.ts # MCP 客戶端封裝提供 callMCPTool ├── servers/ │ ├── google-drive/ │ │ ├── getDocument.ts │ │ ├── getSheet.ts │ │ └── index.ts │ └── salesforce/ │ ├── updateRecord.ts │ ├── query.ts │ └── index.ts ├── skills/ │ └── save-sheet-as-csv.ts └── agent.ts # 智能體主循環(huán)client.ts是整個方案的地基它負責和 MCP Server 建立連接并把工具調用封裝成一個泛型函數。這里用 MCP 官方 SDK 的客戶端能力連接方式支持 stdio 和 SSEDemo 里用 stdio 最省事。// client.ts import { Client } from modelcontextprotocol/sdk/client/index.js; import { StdioClientTransport } from modelcontextprotocol/sdk/client/stdio.js; const clients new Mapstring, Client(); export async function getClient(serverName: string): PromiseClient { if (clients.has(serverName)) return clients.get(serverName)!; const transport new StdioClientTransport({ command: npx, args: [-y, modelcontextprotocol/server-${serverName}], }); const client new Client( { name: code-exec-agent, version: 1.0.0 }, { capabilities: {} } ); await client.connect(transport); clients.set(serverName, client); return client; } export async function callMCPToolT( toolName: string, input: Recordstring, unknown ): PromiseT { // toolName 形如 google_drive__get_document const [serverPart, ...rest] toolName.split(__); const serverName serverPart.replace(/_/g, -); const client await getClient(serverName); const result await client.callTool({ name: rest.join(__), arguments: input, }); return result.content as T; }然后是具體工具文件。以servers/google-drive/getDocument.ts為例它只做一件事聲明輸入輸出類型然后轉調callMCPTool。模型讀這個文件就能知道工具怎么用不需要預加載全部工具定義。// servers/google-drive/getDocument.ts import { callMCPTool } from ../../client.js; interface GetDocumentInput { documentId: string; } interface GetDocumentResponse { content: string; } /* 從 Google Drive 讀取文檔內容 */ export async function getDocument( input: GetDocumentInput ): PromiseGetDocumentResponse { return callMCPToolGetDocumentResponse( google_drive__get_document, input ); }servers/google-drive/index.ts做統(tǒng)一導出方便模型用import * as gdrive from ./servers/google-drive這種方式引用// servers/google-drive/index.ts export { getDocument } from ./getDocument.js; export { getSheet } from ./getSheet.js;Salesforce 那邊同理updateRecord.ts和query.ts各管一個工具。這里不重復貼結構完全一致你照著改工具名和參數類型即可。接下來是 MCP Server 的配置文件。如果你用的是支持 MCP 配置的客戶端比如 Claude Desktop 或 Cline配置片段長這樣注意路徑要換成你本地的絕對路徑{ mcpServers: { google-drive: { command: npx, args: [-y, modelcontextprotocol/server-google-drive], env: { GOOGLE_DRIVE_CREDENTIALS: /path/to/credentials.json } }, salesforce: { command: npx, args: [-y, modelcontextprotocol/server-salesforce], env: { SALESFORCE_TOKEN: your-token } } } }如果你用的是 Cline 的 MCP 配置格式類似但字段名可能略有差異以 Cline 文檔為準。關鍵點在于每個 Server 的command和args要能獨立跑起來你可以先在終端手動執(zhí)行npx -y modelcontextprotocol/server-google-drive確認它能啟動再寫進配置。代碼執(zhí)行環(huán)境這塊Demo 里用 Node.js 的child_process起一個受限的沙箱進程來跑模型生成的代碼。生產環(huán)境建議上更嚴格的沙箱方案比如容器隔離或isolated-vmDemo 為了跑通流程先用簡單方式。// executor.ts import { execFile } from child_process; import { promisify } from util; const execFileAsync promisify(execFile); export async function runCode(code: string): Promisestring { const { stdout, stderr } await execFileAsync( npx, [tsx, -e, code], { timeout: 30000, maxBuffer: 1024 * 1024 * 10 } ); return stderr ? ${stdout}\n[stderr] ${stderr} : stdout; }到這里MCP Server 配置、工具文件、執(zhí)行環(huán)境三件套就齊了。下一節(jié)把智能體主循環(huán)串起來跑一個端到端的真實任務。4. 端到端驗證讓智能體寫代碼完成 Drive 到 Salesforce 的數據流轉環(huán)境搭好后最關鍵的一步是驗證整個鏈路真的能跑通。這一節(jié)用一個具體任務走完全流程從 Google Drive 讀一份表格過濾出待處理訂單寫進 Salesforce。你會看到模型如何生成代碼、代碼如何調用 MCP 工具、結果如何回傳。先寫智能體主循環(huán)agent.ts。它的職責是把系統(tǒng)提示詞和用戶任務發(fā)給模型模型返回代碼執(zhí)行代碼把執(zhí)行結果回傳模型循環(huán)直到模型給出最終答復。系統(tǒng)提示詞里要明確告訴模型你可以通過寫 TypeScript 代碼來調用工具工具定義在./servers/目錄下用import引入即可。// agent.ts import Anthropic from anthropic-ai/sdk; import dotenv/config; import { runCode } from ./executor.js; const client new Anthropic({ apiKey: process.env.TAOTOKEN_API_KEY, baseURL: process.env.TAOTOKEN_BASE_URL, }); const SYSTEM_PROMPT 你是一個代碼執(zhí)行型智能體。你可以通過編寫 TypeScript 代碼來調用 MCP 工具。 工具定義位于 ./servers/ 目錄每個工具是一個導出函數。 寫代碼時用 import 引入需要的工具例如 import * as gdrive from ./servers/google-drive; import * as salesforce from ./servers/salesforce; 執(zhí)行環(huán)境會運行你的代碼并把 stdout 返回給你。 只寫代碼不要寫解釋。代碼要能直接執(zhí)行。 ; async function runAgent(task: string) { const messages: Anthropic.MessageParam[] [ { role: user, content: task }, ]; for (let i 0; i 10; i) { const resp await client.messages.create({ model: 你的Model ID, max_tokens: 4096, system: SYSTEM_PROMPT, messages, }); const textBlock resp.content.find((b) b.type text); if (!textBlock || textBlock.type ! text) break; const code textBlock.text; console.log(--- 第 ${i 1} 輪生成的代碼 ---\n${code}); const output await runCode(code); console.log(--- 執(zhí)行結果 ---\n${output}); messages.push({ role: assistant, content: code }); messages.push({ role: user, content: 執(zhí)行結果\n${output}\n如果任務完成回復 DONE。, }); if (output.includes(DONE)) break; } } runAgent(讀取 Google Drive 表格 abc123找出 Status 為 pending 的訂單只打印前 5 條。);跑起來后模型第一輪大概率會生成類似這樣的代碼import * as gdrive from ./servers/google-drive; const allRows await gdrive.getSheet({ sheetId: abc123 }); const pendingOrders allRows.filter((row) row[Status] pending); console.log(找到了 ${pendingOrders.length} 個待處理訂單); console.log(pendingOrders.slice(0, 5));注意這里的關鍵差異傳統(tǒng)直接調用模式下getSheet返回的 10000 行會全部進入模型上下文而代碼執(zhí)行模式下10000 行只在執(zhí)行環(huán)境里存在模型最終看到的只有console.log輸出的那 5 行。這就是 token 節(jié)省的來源。執(zhí)行結果回傳后模型看到“找到了 N 個待處理訂單”和 5 行樣本會判斷任務是否完成。如果任務要求寫入 Salesforce它會生成第二輪代碼import * as gdrive from ./servers/google-drive; import * as salesforce from ./servers/salesforce; const allRows await gdrive.getSheet({ sheetId: abc123 }); const pendingOrders allRows.filter((row) row[Status] pending); for (const row of pendingOrders) { await salesforce.updateRecord({ objectType: Order, recordId: row.salesforceId, data: { Status: processing, Notes: row.notes }, }); } console.log(DONE 更新了 ${pendingOrders.length} 條訂單);看到DONE后主循環(huán)退出。整個過程中模型上下文里只有代碼和精簡后的執(zhí)行結果沒有原始的大數據集。實測下來一個萬行表格的任務token 消耗從直接調用模式的十幾萬降到幾千響應速度也快了一個數量級。驗證時建議先用小數據集跑通確認callMCPTool能正確連上 Server、工具函數能正常返回數據再換大數據集測 token 節(jié)省效果。如果第一輪代碼就報錯把錯誤信息回傳給模型它通常能自己修正這也是代碼執(zhí)行模式的一個好處錯誤處理邏輯可以寫在代碼里不用模型反復介入。5. 常見報錯排查401、local proxy failed 與 reading choices跑通之后你可能會在不同環(huán)節(jié)遇到報錯。這一節(jié)把幾個高頻錯誤和排查路徑列出來都是我在實際調試中踩過的。401 Unauthorized最常見基本是 Key 或 Base URL 的問題。先確認.env里的TAOTOKEN_API_KEY沒有多余空格或換行復制時容易帶上。再確認TAOTOKEN_BASE_URL是https://taotoken.net/api沒有手動加/v1。如果 Key 是從控制臺新創(chuàng)建的確認它處于啟用狀態(tài)。還有一種情況是環(huán)境變量沒被正確加載dotenv/config要在文件頂部第一行 import晚于 SDK 初始化就會讀到 undefined。local proxy failed / connection refused這個報錯通常出現在 MCP Server 啟動階段說明StdioClientTransport沒能拉起子進程。排查順序是先在終端手動執(zhí)行配置里的command和args看能不能啟動如果手動能啟動但代碼里不行檢查command是不是用了相對路徑改成絕對路徑或確保npx在 PATH 里。另外某些 Server 需要額外的環(huán)境變量比如憑證文件路徑漏配會導致啟動即退出表現為連接失敗。reading choices of undefined這個報錯一般出現在模型響應解析環(huán)節(jié)說明返回結構不符合預期。可能原因是 Model ID 填錯了或者 Base URL 路徑不對導致請求打到了非預期端點。先確認 Model ID 是從 TaoToken 控制臺復制的當前可用型號再確認 Base URL 沒有多余路徑。如果用的是 OpenAI 兼容格式的 SDK 去調 Anthropic 模型響應結構會不一樣注意 SDK 和模型要匹配。OAuth 相關報錯如果你接的 MCP Server 需要 OAuth 授權比如某些 Google 服務報錯信息里會出現OAuth、token expired、invalid_grant等關鍵詞。這類問題不在模型通道側而在 MCP Server 的授權配置。檢查憑證文件是否過期、授權范圍是否包含所需 API、回調地址是否配置正確。Demo 里為了簡化用了 token 方式生產環(huán)境建議走完整的 OAuth 流程。工具調用返回空結果代碼執(zhí)行成功但callMCPTool返回空先確認工具名拼寫。toolName的格式是server_name__tool_name中間是雙下劃線Server 名里的連字符要轉成下劃線。比如google-drive對應google_drive。這個轉換在callMCPTool里做了但如果你手動傳工具名容易漏掉。排查時有個通用技巧把callMCPTool的原始返回打出來看不要只看封裝后的結果。很多時候問題出在數據格式和預期不一致比如返回的是{ content: [...] }而不是直接的數組加一行console.log(JSON.stringify(result, null, 2))就能看清。6. 把代碼執(zhí)行型智能體接到你的工作流里跑通 Demo 只是起點真正有價值的是把它接到日常開發(fā)流程里。這里說幾個我實際用下來覺得值得做的方向。第一把常用操作沉淀成skills/目錄下的可復用函數。比如“把表格導出成 CSV”這個操作第一次讓模型寫代碼實現后把代碼保存到skills/save-sheet-as-csv.ts下次直接 import 調用不用模型重新生成。時間長了你會積累一個自己的工具庫模型的能力邊界也隨之擴展。這跟 Anthropic 提的 Skills 概念是一致的可復用的指令、腳本和資源文件夾。第二給代碼執(zhí)行環(huán)境加上資源限制和監(jiān)控。Demo 里用了 30 秒超時和 10MB 輸出上限生產環(huán)境還要加內存限制、網絡訪問控制、文件系統(tǒng)讀寫范圍限制。模型生成的代碼不可全信沙箱是必須的。如果任務涉及敏感數據可以在執(zhí)行環(huán)境里做 token 化讓真實數據不進入模型上下文只讓模型看到占位符。第三把 MCP 通道和模型通道的額度分開管理。TaoToken 的 Coding Plan 適合長期編碼和 Agent 場景和按量調用的 API Key 分開這樣你能清楚知道每個項目消耗了多少?？刂婆_里可以按 Key 維度看用量排查異常消耗時很方便。第四漸進式披露工具定義。當你的servers/目錄下工具數量超過幾十個時可以考慮加一個search_tools工具讓模型先搜索再加載具體工具文件而不是遍歷整個目錄。這樣即使工具規(guī)模繼續(xù)增長上下文消耗也能保持可控。最后說一個實際經驗代碼執(zhí)行模式不是銀彈它引入了沙箱、監(jiān)控、錯誤處理這些額外復雜度。如果你的智能體只連兩三個工具、數據量也不大直接調用模式反而更簡單。但當工具數量上到幾十個、單次任務涉及大數據集流轉時代碼執(zhí)行帶來的 token 節(jié)省和延遲改善是實打實的。判斷標準很簡單看你的上下文窗口里工具定義和中間結果占了多少比例超過三成就該考慮切到代碼執(zhí)行模式了。接入文檔和 API Keys 都在 TaoToken 官網可以找到模型對話入口適合先驗證通道Coding Plan 適合把編碼類 Agent 長期跑起來。先把 Demo 跑通再按自己的場景逐步替換工具和數據源這條路走下來比一上來就搭大框架要穩(wěn)得多。