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把模型請求統(tǒng)一走 TaoToken 的 Key/API 通道最后給你一份能直接復(fù)制的config.toml和settings.json骨架跑通一次真實(shí)的工具調(diào)用。適合誰看如果你已經(jīng)會一點(diǎn) Python聽過 MCP 但沒真正跑起來過或者你手上有一堆內(nèi)部 API 想包成 Agent 工具這篇就是給你寫的。整個(gè)過程我建議你跟著敲不要只復(fù)制因?yàn)?MCP 的坑基本都在配置路徑和啟動命令上光看是看不出來的。先說清楚一個(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ā)起請求。這里用 TaoToken 做統(tǒng)一入口的好處是一個(gè) Key 走通模型對話和后續(xù)的 Agent 調(diào)用不用在多個(gè)平臺之間來回切配置。官網(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和類型注解上會有些別扭。第二uv 包管理器。安裝命令分平臺# 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。去控制臺創(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í)會用到。如果你只打算用 Claude Desktop 掛載anthropic可以先不加但建議留著方便后面寫自動化測試。關(guān)于模型 IDTaoToken 通道里常用的對話模型你可以先在模型對話頁確認(rèn)一下當(dāng)前可用的名稱地址是 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。配置里我會用占位符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()裝飾器會自動把函數(shù)注冊成工具函數(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必須寫絕對路徑相對路徑在客戶端啟動子進(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. 啟動 MCP 服務(wù)并驗(yàn)證一次真實(shí)工具調(diào)用配置寫完先單獨(dú)驗(yàn)證 Server 能不能起來。在項(xiàng)目目錄執(zhí)行uv run python server.pystdio 模式下它不會打印任何東西光標(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ā)一次請求確認(rèn) Key 和模型 ID 沒問題。你可以直接在模型對話頁 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ò)誤和對應(yīng)原因列出來你對著改。401 UnauthorizedKey 沒傳進(jìn)去或者傳了但格式不對。檢查三處環(huán)境變量TAOTOKEN_API_KEY是否在當(dāng)前 shell 里export過config.toml/settings.json里引用變量名的寫法是否正確${VAR}和$VAR在不同客戶端里支持度不一樣不確定就寫死測試一次請求頭字段名對不對Anthropic 風(fēng)格是x-api-keyOpenAI 風(fēng)格是Authorization: Bearer。TaoToken 的 API 基址是https://taotoken.net/api別多加/v1也別少加路徑拼錯(cuò)也會返回 401 或 404。local proxy failed / connection refused客戶端啟動 MCP Server 子進(jìn)程失敗。九成是cwd路徑不對或者command找不到。uv如果不在系統(tǒng) PATH 里客戶端就起不來。解決辦法是把command換成uv的絕對路徑用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 對 stdio。還有一點(diǎn)Server 啟動時(shí)如果有 import 錯(cuò)誤進(jìn)程會直接退出客戶端那邊表現(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)長期編碼流下一步怎么走跑通第一個(gè)工具之后你大概率會想加更多工具讀本地文件、查數(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請根據(jù)以下信息為 {city} 生成一份簡潔的天氣報(bào)告包含出行建議。Resource 讓模型能讀你的數(shù)據(jù)Prompt 讓你能定義標(biāo)準(zhǔn)化的交互模板。這兩個(gè)不是必須的但加上之后 Agent 的能力邊界會寬很多。如果你打算把 MCP 工具服務(wù)用在日常編碼和 Agent 工作流里長期跑的話建議了解一下 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 它更適合持續(xù)性的編碼場景。接入文檔在 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è)也會卡住。給每個(gè)外部請求設(shè) 5 到 10 秒超時(shí)失敗時(shí)返回明確的錯(cuò)誤字符串而不是拋異常這樣模型能根據(jù)錯(cuò)誤信息決定要不要重試或換工具。這個(gè)細(xì)節(jié)在 demo 階段無所謂但一旦上生產(chǎn)就是穩(wěn)定性的分水嶺。