戰(zhàn)教程：用 TaoToken 統(tǒng)一 Key 從零搭建你的第一個(gè) AI Agent 工具服務(wù))
1. 為什么你的第一個(gè) AI Agent 工具服務(wù)卡在了“工具接不進(jìn)去”MCPModel Context Protocol說白了就是 AI 模型和外部工具之間的“USB 接口”。以前你寫一個(gè) AI Agent想讓它查天氣、讀數(shù)據(jù)庫、調(diào)內(nèi)部接口每個(gè)模型廠商都得自己寫一套 Function Calling 的適配層現(xiàn)在有了 MCP 這個(gè)開放協(xié)議工具服務(wù)寫一次Claude、支持 MCP 的客戶端都能直接掛載調(diào)用。這篇要交付的東西很具體用 Python 從零寫一個(gè)可被 Claude 調(diào)用的 MCP Server把模型請(qǐng)求統(tǒng)一走 TaoToken 的 Key/API 通道最后給你一份能直接復(fù)制的config.toml和settings.json骨架跑通一次真實(shí)的工具調(diào)用。適合誰看如果你已經(jīng)會(huì)一點(diǎn) Python聽過 MCP 但沒真正跑起來過或者你手上有一堆內(nèi)部 API 想包成 Agent 工具這篇就是給你寫的。整個(gè)過程我建議你跟著敲不要只復(fù)制因?yàn)?MCP 的坑基本都在配置路徑和啟動(dòng)命令上光看是看不出來的。先說清楚一個(gè)容易混的點(diǎn)MCP Server 本身不負(fù)責(zé)“思考”它只負(fù)責(zé)暴露工具Tool、資源Resource、提示模板Prompt這三類能力。真正決定“什么時(shí)候調(diào)用哪個(gè)工具”的是模型側(cè)也就是 Claude 這類客戶端。所以你的 Server 寫得再花哨如果客戶端配置里沒掛上模型根本看不見它。這也是為什么很多人寫完server.py一運(yùn)行終端啥也不輸出以為寫錯(cuò)了——其實(shí) stdio 模式下它就是在等客戶端通過標(biāo)準(zhǔn)輸入發(fā)消息不是給你打印日志用的。我試過最省事的路徑是Python 3.12 uv 管理依賴 FastMCP 裝飾器寫法。uv 比 pip 快很多而且uv run能直接帶著虛擬環(huán)境跑腳本省掉激活環(huán)境的步驟。下面所有命令你都可以直接粘。2. 用 TaoToken 統(tǒng)一 Key 接入 MCP 工具服務(wù)的前置準(zhǔn)備在寫代碼之前先把“模型通道”這件事定下來。MCP Server 是工具側(cè)但你要驗(yàn)證工具能不能被調(diào)用總得有個(gè)模型客戶端去發(fā)起請(qǐng)求。這里用 TaoToken 做統(tǒng)一入口的好處是一個(gè) Key 走通模型對(duì)話和后續(xù)的 Agent 調(diào)用不用在多個(gè)平臺(tái)之間來回切配置。官網(wǎng)入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 。你需要準(zhǔn)備三樣?xùn)|西第一Python 3.10 以上推薦 3.12。低版本在async和類型注解上會(huì)有些別扭。第二uv 包管理器。安裝命令分平臺(tái)# macOS / Linux curl -LsSf https://astral.sh/uv/install.sh | sh # Windows PowerShell powershell -c irm https://astral.sh/uv/install.ps1 | iex第三一個(gè) TaoToken 的 API Key。去控制臺(tái)創(chuàng)建路徑是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content Key 的管理頁在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。拿到之后先別急著寫進(jìn)代碼用環(huán)境變量存后面配置里引用變量名避免 Key 硬編碼進(jìn) Git。初始化項(xiàng)目uv init mcp-server-demo cd mcp-server-demo uv add mcp anthropic這里mcp是官方 SDKanthropic包在你需要寫一個(gè)“模型側(cè)客戶端”做本地驗(yàn)證時(shí)會(huì)用到。如果你只打算用 Claude Desktop 掛載anthropic可以先不加但建議留著方便后面寫自動(dòng)化測(cè)試。關(guān)于模型 IDTaoToken 通道里常用的對(duì)話模型你可以先在模型對(duì)話頁確認(rèn)一下當(dāng)前可用的名稱地址是 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。配置里我會(huì)用占位符your-model-id你替換成實(shí)際值即可。這一步別跳過模型 ID 寫錯(cuò)是最常見的 404 來源。3. 可復(fù)制的 config.toml 與 settings.json 配置骨架這一節(jié)是全文最該收藏的部分。MCP 的配置分散在兩個(gè)地方一個(gè)是客戶端掛載 Server 的配置Claude Desktop 用claude_desktop_config.json很多 CLI 工具用config.toml另一個(gè)是模型通道的配置常見于settings.json或auth.json。我把兩套骨架都給你路徑和字段名保持和實(shí)際一致。先寫server.py這是工具服務(wù)的核心# server.py from mcp.server.fastmcp import FastMCP mcp FastMCP(weather-server) mcp.tool() async def get_weather(city: str) - str: 獲取指定城市的天氣信息 mock_data { 北京: 晴28°C濕度 45%, 上海: 多云26°C濕度 65%, 深圳: 雷陣雨30°C濕度 80%, } return mock_data.get(city, f{city}暫無數(shù)據(jù)) mcp.tool() async def list_cities() - str: 返回支持查詢的城市列表 return 北京、上海、深圳 if __name__ __main__: mcp.run(transportstdio)mcp.tool()裝飾器會(huì)自動(dòng)把函數(shù)注冊(cè)成工具函數(shù)的 docstring 就是工具描述模型靠這段描述判斷什么時(shí)候調(diào)用。所以 docstring 別寫廢話寫清楚“這個(gè)工具干什么、參數(shù)是什么”。然后是config.toml用于支持 TOML 配置的 MCP 客戶端# config.toml [mcp_servers.weather] command uv args [run, python, server.py] cwd /Users/yourname/projects/mcp-server-demo env { TAOTOKEN_API_KEY ${TAOTOKEN_API_KEY} } [model] base_url https://taotoken.net/api api_key ${TAOTOKEN_API_KEY} model_id your-model-id注意cwd必須寫絕對(duì)路徑相對(duì)路徑在客戶端啟動(dòng)子進(jìn)程時(shí)經(jīng)常解析失敗這是踩過的坑里排前三的。env里引用環(huán)境變量別把 Key 明文寫進(jìn)去。再給一份settings.json適合 Claude Code 這類用 JSON 配置的工具{ mcpServers: { weather: { command: uv, args: [run, python, server.py], cwd: /Users/yourname/projects/mcp-server-demo, env: { TAOTOKEN_API_KEY: ${TAOTOKEN_API_KEY} } } }, model: { baseUrl: https://taotoken.net/api, apiKey: ${TAOTOKEN_API_KEY}, modelId: your-model-id } }如果你用的是 Claude Desktop配置文件路徑是# macOS ~/Library/Application Support/Claude/claude_desktop_config.json # Windows %APPDATA%\Claude\claude_desktop_config.json把上面settings.json里mcpServers那段貼進(jìn)去即可。三件套記住Base URL 填https://taotoken.net/apiKey 填你的 TaoToken KeyModel ID 填實(shí)際模型名。這三樣缺一個(gè)模型側(cè)就調(diào)不通。4. 啟動(dòng) MCP 服務(wù)并驗(yàn)證一次真實(shí)工具調(diào)用配置寫完先單獨(dú)驗(yàn)證 Server 能不能起來。在項(xiàng)目目錄執(zhí)行uv run python server.pystdio 模式下它不會(huì)打印任何東西光標(biāo)停住就是正常。如果你看到報(bào)錯(cuò)多半是mcp包沒裝好或者 Python 版本太低。按CtrlC退出。接著做一次本地調(diào)用驗(yàn)證。寫一個(gè)client_test.py用官方 SDK 以 stdio 方式連上你的 Server列出工具并調(diào)用一次# client_test.py import asyncio from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client async def main(): params StdioServerParameters( commanduv, args[run, python, server.py], ) async with stdio_client(params) as (read, write): async with ClientSession(read, write) as session: await session.initialize() tools await session.list_tools() print(可用工具, [t.name for t in tools.tools]) result await session.call_tool(get_weather, {city: 北京}) print(調(diào)用結(jié)果, result.content[0].text) asyncio.run(main())運(yùn)行uv run python client_test.py正常輸出應(yīng)該是可用工具 [get_weather, list_cities] 調(diào)用結(jié)果 晴28°C濕度 45%看到這兩行說明你的 MCP Server 已經(jīng)能被標(biāo)準(zhǔn)客戶端發(fā)現(xiàn)并調(diào)用了。這一步是整個(gè)教程的分水嶺——工具側(cè)通了剩下的就是把模型側(cè)接上。模型側(cè)驗(yàn)證用 TaoToken 通道發(fā)一次請(qǐng)求確認(rèn) Key 和模型 ID 沒問題。你可以直接在模型對(duì)話頁 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里問一句“北京天氣怎么樣”前提是客戶端已經(jīng)掛載了你的 weather Server。如果模型回復(fù)里出現(xiàn)了“晴28°C”說明從模型到工具再到返回的整條鏈路打通了。如果你更想用命令行驗(yàn)證可以用curl直接打 APIcurl https://taotoken.net/api/v1/messages \ -H x-api-key: $TAOTOKEN_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: your-model-id, max_tokens: 256, messages: [{role: user, content: 你好}] }返回里有content字段就說明通道正常。這一步和 MCP 無關(guān)但它是排查“到底是工具問題還是模型通道問題”的關(guān)鍵分界線。5. 本篇常見報(bào)錯(cuò)排查401、local proxy failed、reading choices、OAuth配置跑不通的時(shí)候報(bào)錯(cuò)信息往往很含糊。我把幾個(gè)高頻錯(cuò)誤和對(duì)應(yīng)原因列出來你對(duì)著改。401 UnauthorizedKey 沒傳進(jìn)去或者傳了但格式不對(duì)。檢查三處環(huán)境變量TAOTOKEN_API_KEY是否在當(dāng)前 shell 里export過config.toml/settings.json里引用變量名的寫法是否正確${VAR}和$VAR在不同客戶端里支持度不一樣不確定就寫死測(cè)試一次請(qǐng)求頭字段名對(duì)不對(duì)Anthropic 風(fēng)格是x-api-keyOpenAI 風(fēng)格是Authorization: Bearer。TaoToken 的 API 基址是https://taotoken.net/api別多加/v1也別少加路徑拼錯(cuò)也會(huì)返回 401 或 404。local proxy failed / connection refused客戶端啟動(dòng) MCP Server 子進(jìn)程失敗。九成是cwd路徑不對(duì)或者command找不到。uv如果不在系統(tǒng) PATH 里客戶端就起不來。解決辦法是把command換成uv的絕對(duì)路徑用which uv查出來填進(jìn)去。另外 Windows 上路徑反斜杠要轉(zhuǎn)義建議統(tǒng)一用正斜杠。reading choices of undefined這是 OpenAI 兼容格式的響應(yīng)解析錯(cuò)誤通常出現(xiàn)在你把 Anthropic 格式的響應(yīng)喂給了期望 OpenAI 格式的客戶端或者反過來。檢查你的客戶端到底走哪種協(xié)議。TaoToken 的/api基址下Anthropic 風(fēng)格走/v1/messagesOpenAI 風(fēng)格走/v1/chat/completions別混用。OAuth 相關(guān)報(bào)錯(cuò)如果你用的是 Claude Code 這類帶 OAuth 登錄的工具它可能優(yōu)先走官方登錄態(tài)而不是你的 API Key。這時(shí)候要在配置里顯式指定apiKey和baseUrl覆蓋掉默認(rèn)的 OAuth 流程。Claude Code 的配置里如果同時(shí)存在 OAuth token 和 API Key行為取決于版本建議清掉舊的登錄緩存再試。工具列表為空客戶端連上了 Server但list_tools返回空。檢查mcp.tool()裝飾器有沒有漏寫函數(shù)是不是async以及mcp.run()的 transport 是不是和客戶端一致stdio 對(duì) stdio。還有一點(diǎn)Server 啟動(dòng)時(shí)如果有 import 錯(cuò)誤進(jìn)程會(huì)直接退出客戶端那邊表現(xiàn)就是“連上了但沒工具”實(shí)際去看 Server 的 stderr 才能看到真實(shí)報(bào)錯(cuò)。排查順序建議固定成先uv run python server.py確認(rèn) Server 能起再client_test.py確認(rèn)工具能列能調(diào)最后才去查模型側(cè)配置。這樣能把問題范圍一步步縮小不至于一上來就懷疑 Key。6. 把工具服務(wù)接進(jìn)長(zhǎng)期編碼流下一步怎么走跑通第一個(gè)工具之后你大概率會(huì)想加更多工具讀本地文件、查數(shù)據(jù)庫、調(diào)內(nèi)部 HTTP 接口。MCP 的擴(kuò)展方式很直接繼續(xù)用mcp.tool()往server.py里加函數(shù)就行每個(gè)函數(shù)一個(gè)職責(zé)docstring 寫清楚參數(shù)含義。Resource 和 Prompt 也可以加上mcp.resource(config://app) async def get_config(): 返回應(yīng)用配置信息 return {version: 1.0, debug: False} mcp.prompt() async def weather_report(city: str) - str: 生成天氣報(bào)告的提示模板 return f請(qǐng)根據(jù)以下信息為 {city} 生成一份簡(jiǎn)潔的天氣報(bào)告包含出行建議。Resource 讓模型能讀你的數(shù)據(jù)Prompt 讓你能定義標(biāo)準(zhǔn)化的交互模板。這兩個(gè)不是必須的但加上之后 Agent 的能力邊界會(huì)寬很多。如果你打算把 MCP 工具服務(wù)用在日常編碼和 Agent 工作流里長(zhǎng)期跑的話建議了解一下 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 它更適合持續(xù)性的編碼場(chǎng)景。接入文檔在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 遇到配置字段不確定的時(shí)候直接查文檔比猜快。最后一個(gè)實(shí)用建議把server.py里的 mock 數(shù)據(jù)換成真實(shí) API 調(diào)用時(shí)記得加超時(shí)和異常捕獲。MCP 工具調(diào)用是同步等待的你的工具卡住模型側(cè)也會(huì)卡住。給每個(gè)外部請(qǐng)求設(shè) 5 到 10 秒超時(shí)失敗時(shí)返回明確的錯(cuò)誤字符串而不是拋異常這樣模型能根據(jù)錯(cuò)誤信息決定要不要重試或換工具。這個(gè)細(xì)節(jié)在 demo 階段無所謂但一旦上生產(chǎn)就是穩(wěn)定性的分水嶺。 MCP 實(shí)戰(zhàn)教程：用 TaoToken 統(tǒng)一 Key 從零搭建你的第一個(gè) AI Agent 工具服務(wù)
1. 為什么你的第一個(gè) AI Agent 工具服務(wù)卡在了“工具接不進(jìn)去”MCPModel Context Protocol說白了就是 AI 模型和外部工具之間的“USB 接口”。以前你寫一個(gè) AI Agent想讓它查天氣、讀數(shù)據(jù)庫、調(diào)內(nèi)部接口每個(gè)模型廠商都得自己寫一套 Function Calling 的適配層現(xiàn)在有了 MCP 這個(gè)開放協(xié)議工具服務(wù)寫一次Claude、支持 MCP 的客戶端都能直接掛載調(diào)用。這篇要交付的東西很具體用 Python 從零寫一個(gè)可被 Claude 調(diào)用的 MCP Server把模型請(qǐng)求統(tǒng)一走 TaoToken 的 Key/API 通道最后給你一份能直接復(fù)制的config.toml和settings.json骨架跑通一次真實(shí)的工具調(diào)用。適合誰看如果你已經(jīng)會(huì)一點(diǎn) Python聽過 MCP 但沒真正跑起來過或者你手上有一堆內(nèi)部 API 想包成 Agent 工具這篇就是給你寫的。整個(gè)過程我建議你跟著敲不要只復(fù)制因?yàn)?MCP 的坑基本都在配置路徑和啟動(dòng)命令上光看是看不出來的。先說清楚一個(gè)容易混的點(diǎn)MCP Server 本身不負(fù)責(zé)“思考”它只負(fù)責(zé)暴露工具Tool、資源Resource、提示模板Prompt這三類能力。真正決定“什么時(shí)候調(diào)用哪個(gè)工具”的是模型側(cè)也就是 Claude 這類客戶端。所以你的 Server 寫得再花哨如果客戶端配置里沒掛上模型根本看不見它。這也是為什么很多人寫完server.py一運(yùn)行終端啥也不輸出以為寫錯(cuò)了——其實(shí) stdio 模式下它就是在等客戶端通過標(biāo)準(zhǔn)輸入發(fā)消息不是給你打印日志用的。我試過最省事的路徑是Python 3.12 uv 管理依賴 FastMCP 裝飾器寫法。uv 比 pip 快很多而且uv run能直接帶著虛擬環(huán)境跑腳本省掉激活環(huán)境的步驟。下面所有命令你都可以直接粘。2. 用 TaoToken 統(tǒng)一 Key 接入 MCP 工具服務(wù)的前置準(zhǔn)備在寫代碼之前先把“模型通道”這件事定下來。MCP Server 是工具側(cè)但你要驗(yàn)證工具能不能被調(diào)用總得有個(gè)模型客戶端去發(fā)起請(qǐng)求。這里用 TaoToken 做統(tǒng)一入口的好處是一個(gè) Key 走通模型對(duì)話和后續(xù)的 Agent 調(diào)用不用在多個(gè)平臺(tái)之間來回切配置。官網(wǎng)入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 。你需要準(zhǔn)備三樣?xùn)|西第一Python 3.10 以上推薦 3.12。低版本在async和類型注解上會(huì)有些別扭。第二uv 包管理器。安裝命令分平臺(tái)# macOS / Linux curl -LsSf https://astral.sh/uv/install.sh | sh # Windows PowerShell powershell -c irm https://astral.sh/uv/install.ps1 | iex第三一個(gè) TaoToken 的 API Key。去控制臺(tái)創(chuàng)建路徑是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content Key 的管理頁在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。拿到之后先別急著寫進(jìn)代碼用環(huán)境變量存后面配置里引用變量名避免 Key 硬編碼進(jìn) Git。初始化項(xiàng)目uv init mcp-server-demo cd mcp-server-demo uv add mcp anthropic這里mcp是官方 SDKanthropic包在你需要寫一個(gè)“模型側(cè)客戶端”做本地驗(yàn)證時(shí)會(huì)用到。如果你只打算用 Claude Desktop 掛載anthropic可以先不加但建議留著方便后面寫自動(dòng)化測(cè)試。關(guān)于模型 IDTaoToken 通道里常用的對(duì)話模型你可以先在模型對(duì)話頁確認(rèn)一下當(dāng)前可用的名稱地址是 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。配置里我會(huì)用占位符your-model-id你替換成實(shí)際值即可。這一步別跳過模型 ID 寫錯(cuò)是最常見的 404 來源。3. 可復(fù)制的 config.toml 與 settings.json 配置骨架這一節(jié)是全文最該收藏的部分。MCP 的配置分散在兩個(gè)地方一個(gè)是客戶端掛載 Server 的配置Claude Desktop 用claude_desktop_config.json很多 CLI 工具用config.toml另一個(gè)是模型通道的配置常見于settings.json或auth.json。我把兩套骨架都給你路徑和字段名保持和實(shí)際一致。先寫server.py這是工具服務(wù)的核心# server.py from mcp.server.fastmcp import FastMCP mcp FastMCP(weather-server) mcp.tool() async def get_weather(city: str) - str: 獲取指定城市的天氣信息 mock_data { 北京: 晴28°C濕度 45%, 上海: 多云26°C濕度 65%, 深圳: 雷陣雨30°C濕度 80%, } return mock_data.get(city, f{city}暫無數(shù)據(jù)) mcp.tool() async def list_cities() - str: 返回支持查詢的城市列表 return 北京、上海、深圳 if __name__ __main__: mcp.run(transportstdio)mcp.tool()裝飾器會(huì)自動(dòng)把函數(shù)注冊(cè)成工具函數(shù)的 docstring 就是工具描述模型靠這段描述判斷什么時(shí)候調(diào)用。所以 docstring 別寫廢話寫清楚“這個(gè)工具干什么、參數(shù)是什么”。然后是config.toml用于支持 TOML 配置的 MCP 客戶端# config.toml [mcp_servers.weather] command uv args [run, python, server.py] cwd /Users/yourname/projects/mcp-server-demo env { TAOTOKEN_API_KEY ${TAOTOKEN_API_KEY} } [model] base_url https://taotoken.net/api api_key ${TAOTOKEN_API_KEY} model_id your-model-id注意cwd必須寫絕對(duì)路徑相對(duì)路徑在客戶端啟動(dòng)子進(jìn)程時(shí)經(jīng)常解析失敗這是踩過的坑里排前三的。env里引用環(huán)境變量別把 Key 明文寫進(jìn)去。再給一份settings.json適合 Claude Code 這類用 JSON 配置的工具{ mcpServers: { weather: { command: uv, args: [run, python, server.py], cwd: /Users/yourname/projects/mcp-server-demo, env: { TAOTOKEN_API_KEY: ${TAOTOKEN_API_KEY} } } }, model: { baseUrl: https://taotoken.net/api, apiKey: ${TAOTOKEN_API_KEY}, modelId: your-model-id } }如果你用的是 Claude Desktop配置文件路徑是# macOS ~/Library/Application Support/Claude/claude_desktop_config.json # Windows %APPDATA%\Claude\claude_desktop_config.json把上面settings.json里mcpServers那段貼進(jìn)去即可。三件套記住Base URL 填https://taotoken.net/apiKey 填你的 TaoToken KeyModel ID 填實(shí)際模型名。這三樣缺一個(gè)模型側(cè)就調(diào)不通。4. 啟動(dòng) MCP 服務(wù)并驗(yàn)證一次真實(shí)工具調(diào)用配置寫完先單獨(dú)驗(yàn)證 Server 能不能起來。在項(xiàng)目目錄執(zhí)行uv run python server.pystdio 模式下它不會(huì)打印任何東西光標(biāo)停住就是正常。如果你看到報(bào)錯(cuò)多半是mcp包沒裝好或者 Python 版本太低。按CtrlC退出。接著做一次本地調(diào)用驗(yàn)證。寫一個(gè)client_test.py用官方 SDK 以 stdio 方式連上你的 Server列出工具并調(diào)用一次# client_test.py import asyncio from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client async def main(): params StdioServerParameters( commanduv, args[run, python, server.py], ) async with stdio_client(params) as (read, write): async with ClientSession(read, write) as session: await session.initialize() tools await session.list_tools() print(可用工具, [t.name for t in tools.tools]) result await session.call_tool(get_weather, {city: 北京}) print(調(diào)用結(jié)果, result.content[0].text) asyncio.run(main())運(yùn)行uv run python client_test.py正常輸出應(yīng)該是可用工具 [get_weather, list_cities] 調(diào)用結(jié)果 晴28°C濕度 45%看到這兩行說明你的 MCP Server 已經(jīng)能被標(biāo)準(zhǔn)客戶端發(fā)現(xiàn)并調(diào)用了。這一步是整個(gè)教程的分水嶺——工具側(cè)通了剩下的就是把模型側(cè)接上。模型側(cè)驗(yàn)證用 TaoToken 通道發(fā)一次請(qǐng)求確認(rèn) Key 和模型 ID 沒問題。你可以直接在模型對(duì)話頁 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里問一句“北京天氣怎么樣”前提是客戶端已經(jīng)掛載了你的 weather Server。如果模型回復(fù)里出現(xiàn)了“晴28°C”說明從模型到工具再到返回的整條鏈路打通了。如果你更想用命令行驗(yàn)證可以用curl直接打 APIcurl https://taotoken.net/api/v1/messages \ -H x-api-key: $TAOTOKEN_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: your-model-id, max_tokens: 256, messages: [{role: user, content: 你好}] }返回里有content字段就說明通道正常。這一步和 MCP 無關(guān)但它是排查“到底是工具問題還是模型通道問題”的關(guān)鍵分界線。5. 本篇常見報(bào)錯(cuò)排查401、local proxy failed、reading choices、OAuth配置跑不通的時(shí)候報(bào)錯(cuò)信息往往很含糊。我把幾個(gè)高頻錯(cuò)誤和對(duì)應(yīng)原因列出來你對(duì)著改。401 UnauthorizedKey 沒傳進(jìn)去或者傳了但格式不對(duì)。檢查三處環(huán)境變量TAOTOKEN_API_KEY是否在當(dāng)前 shell 里export過config.toml/settings.json里引用變量名的寫法是否正確${VAR}和$VAR在不同客戶端里支持度不一樣不確定就寫死測(cè)試一次請(qǐng)求頭字段名對(duì)不對(duì)Anthropic 風(fēng)格是x-api-keyOpenAI 風(fēng)格是Authorization: Bearer。TaoToken 的 API 基址是https://taotoken.net/api別多加/v1也別少加路徑拼錯(cuò)也會(huì)返回 401 或 404。local proxy failed / connection refused客戶端啟動(dòng) MCP Server 子進(jìn)程失敗。九成是cwd路徑不對(duì)或者command找不到。uv如果不在系統(tǒng) PATH 里客戶端就起不來。解決辦法是把command換成uv的絕對(duì)路徑用which uv查出來填進(jìn)去。另外 Windows 上路徑反斜杠要轉(zhuǎn)義建議統(tǒng)一用正斜杠。reading choices of undefined這是 OpenAI 兼容格式的響應(yīng)解析錯(cuò)誤通常出現(xiàn)在你把 Anthropic 格式的響應(yīng)喂給了期望 OpenAI 格式的客戶端或者反過來。檢查你的客戶端到底走哪種協(xié)議。TaoToken 的/api基址下Anthropic 風(fēng)格走/v1/messagesOpenAI 風(fēng)格走/v1/chat/completions別混用。OAuth 相關(guān)報(bào)錯(cuò)如果你用的是 Claude Code 這類帶 OAuth 登錄的工具它可能優(yōu)先走官方登錄態(tài)而不是你的 API Key。這時(shí)候要在配置里顯式指定apiKey和baseUrl覆蓋掉默認(rèn)的 OAuth 流程。Claude Code 的配置里如果同時(shí)存在 OAuth token 和 API Key行為取決于版本建議清掉舊的登錄緩存再試。工具列表為空客戶端連上了 Server但list_tools返回空。檢查mcp.tool()裝飾器有沒有漏寫函數(shù)是不是async以及mcp.run()的 transport 是不是和客戶端一致stdio 對(duì) stdio。還有一點(diǎn)Server 啟動(dòng)時(shí)如果有 import 錯(cuò)誤進(jìn)程會(huì)直接退出客戶端那邊表現(xiàn)就是“連上了但沒工具”實(shí)際去看 Server 的 stderr 才能看到真實(shí)報(bào)錯(cuò)。排查順序建議固定成先uv run python server.py確認(rèn) Server 能起再client_test.py確認(rèn)工具能列能調(diào)最后才去查模型側(cè)配置。這樣能把問題范圍一步步縮小不至于一上來就懷疑 Key。6. 把工具服務(wù)接進(jìn)長(zhǎng)期編碼流下一步怎么走跑通第一個(gè)工具之后你大概率會(huì)想加更多工具讀本地文件、查數(shù)據(jù)庫、調(diào)內(nèi)部 HTTP 接口。MCP 的擴(kuò)展方式很直接繼續(xù)用mcp.tool()往server.py里加函數(shù)就行每個(gè)函數(shù)一個(gè)職責(zé)docstring 寫清楚參數(shù)含義。Resource 和 Prompt 也可以加上mcp.resource(config://app) async def get_config(): 返回應(yīng)用配置信息 return {version: 1.0, debug: False} mcp.prompt() async def weather_report(city: str) - str: 生成天氣報(bào)告的提示模板 return f請(qǐng)根據(jù)以下信息為 {city} 生成一份簡(jiǎn)潔的天氣報(bào)告包含出行建議。Resource 讓模型能讀你的數(shù)據(jù)Prompt 讓你能定義標(biāo)準(zhǔn)化的交互模板。這兩個(gè)不是必須的但加上之后 Agent 的能力邊界會(huì)寬很多。如果你打算把 MCP 工具服務(wù)用在日常編碼和 Agent 工作流里長(zhǎng)期跑的話建議了解一下 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 它更適合持續(xù)性的編碼場(chǎng)景。接入文檔在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 遇到配置字段不確定的時(shí)候直接查文檔比猜快。最后一個(gè)實(shí)用建議把server.py里的 mock 數(shù)據(jù)換成真實(shí) API 調(diào)用時(shí)記得加超時(shí)和異常捕獲。MCP 工具調(diào)用是同步等待的你的工具卡住模型側(cè)也會(huì)卡住。給每個(gè)外部請(qǐng)求設(shè) 5 到 10 秒超時(shí)失敗時(shí)返回明確的錯(cuò)誤字符串而不是拋異常這樣模型能根據(jù)錯(cuò)誤信息決定要不要重試或換工具。這個(gè)細(xì)節(jié)在 demo 階段無所謂但一旦上生產(chǎn)就是穩(wěn)定性的分水嶺。