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