1. 從零理解 MCPPython 手寫一個(gè)可調(diào)試的 MCP Server 到底在做什么MCPModel Context Protocol說白了就是一套“讓模型調(diào)用外部工具”的約定。你可以把它想成模型和你的代碼之間的一份菜單模型看到菜單上有哪些工具、每個(gè)工具要什么參數(shù)然后決定點(diǎn)哪道菜你的 MCP Server 負(fù)責(zé)把這道菜做出來再把結(jié)果端回去。Python 實(shí)現(xiàn)一個(gè)簡單的 MCP核心就三件事注冊(cè)工具、路由請(qǐng)求、把結(jié)果按協(xié)議格式返回。很多人第一次接觸 MCP 會(huì)以為它很玄其實(shí)底層交互非常樸素。以常見的客戶端為例你在對(duì)話框里提問客戶端把你的問題連同“當(dāng)前可用的 tools 列表”一起發(fā)給模型模型分析后決定調(diào)用哪個(gè) tool并給出參數(shù)客戶端通過 MCP Server 執(zhí)行這個(gè) tool執(zhí)行結(jié)果回傳給模型模型再用自然語言把結(jié)果組織成回答展示給你。整條鏈路里MCP Server 就是那個(gè)“真正干活”的角色。這篇面向的是想自己動(dòng)手寫一個(gè)最小可用 MCP Server 的 Python 開發(fā)者。你不需要先精通協(xié)議細(xì)節(jié)只要會(huì)寫異步函數(shù)、懂一點(diǎn)類型注解就能跟著把 server.py 骨架搭起來注冊(cè)兩個(gè)工具本地跑通再把 endpoint 切到 TaoToken 完成一次真實(shí)的工具調(diào)用驗(yàn)證。適合誰適合正在做 Agent、想讓模型調(diào)用自己業(yè)務(wù)接口、又不想被復(fù)雜框架綁住的人。我試過用官方 SDK 的 FastMCP 類來搭體驗(yàn)是它用 Python 的 type hints 和 docstring 自動(dòng)生成 tool definition省掉了手寫 JSON Schema 的麻煩。你只要寫一個(gè)帶類型注解的 async 函數(shù)加個(gè)裝飾器它就能被模型識(shí)別。下面從環(huán)境準(zhǔn)備開始一步步來。2. TaoToken 前置準(zhǔn)備Python MCP Server 接入大模型 API 的 Base URL 與 Key 配置在寫 Server 之前先把“模型側(cè)”的接入準(zhǔn)備好。MCP Server 本身只負(fù)責(zé)執(zhí)行工具真正決定調(diào)用哪個(gè)工具的是模型所以你需要一個(gè)能訪問模型 API 的入口。這里用 TaoToken 來做模型接入它的接口兼容主流協(xié)議Base URL 和 Key 配好之后客戶端或你的調(diào)試腳本就能直接調(diào)模型。先拿到 API Key。打開 https://taotoken.net/api-keys 登錄后創(chuàng)建一個(gè) Key復(fù)制保存。注意 Key 只在創(chuàng)建時(shí)完整顯示一次丟了就重新建一個(gè)。這個(gè) Key 后面會(huì)寫進(jìn)配置里別硬編碼進(jìn) Git 倉庫。Base URL 用 https://taotoken.net/api 這是接口根地址不要在后面亂加斜杠。模型 ID 按你實(shí)際要用的填比如 claude 系列或 gpt 系列的模型標(biāo)識(shí)具體以控制臺(tái)模型列表為準(zhǔn)。你可以到 https://taotoken.net/console 查看可用模型和額度情況。如果你用的是 Claude Code 這類工具配置方式略有不同可以參考接入文檔 https://taotoken.net/doc 里的說明。文檔里對(duì) Base URL、Key、Model ID 三件套的填法講得比較清楚。對(duì)于本篇的 MCP 調(diào)試我們主要用 Python 腳本直接請(qǐng)求所以只要保證 Base URL 和 Key 正確即可。這里要強(qiáng)調(diào)一個(gè)容易踩的點(diǎn)MCP Server 和模型 API 是兩個(gè)獨(dú)立的東西。Server 負(fù)責(zé)執(zhí)行工具模型 API 負(fù)責(zé)決策。很多人把兩者混在一起結(jié)果調(diào)試時(shí)不知道是工具沒注冊(cè)成功還是模型沒調(diào)通。分開驗(yàn)證問題就好定位。先把模型 API 用 curl 或 Python 請(qǐng)求通再回來調(diào) MCP 工具鏈路。3. 可復(fù)制配置server.py 骨架、依賴清單與 MCP 工具注冊(cè)這一節(jié)是核心直接給可復(fù)制的代碼和配置。先建項(xiàng)目目錄用 uv 管理環(huán)境用 conda 也行命令自行替換。uv init mcp-demo cd mcp-demo uv venv # Windows 激活 .venv\Scripts\activate # macOS/Linux 激活 source .venv/bin/activate uv add mcp[cli] httpx依賴清單里mcp[cli] 提供 FastMCP 和命令行調(diào)試能力httpx 用來發(fā)異步 HTTP 請(qǐng)求。裝完后新建 server.py寫入下面的骨架from typing import Any import httpx from mcp.server.fastmcp import FastMCP # 初始化 FastMCP server名字會(huì)出現(xiàn)在客戶端工具列表里 mcp FastMCP(demo-server) # 模型 API 配置實(shí)際使用時(shí)從環(huán)境變量讀取更安全 TAOTOKEN_BASE_URL https://taotoken.net/api TAOTOKEN_API_KEY sk-你的Key async def call_model(prompt: str) - str: 調(diào)用 TaoToken 模型接口返回文本結(jié)果。 headers { Authorization: fBearer {TAOTOKEN_API_KEY}, Content-Type: application/json, } payload { model: 你的模型ID, messages: [{role: user, content: prompt}], } async with httpx.AsyncClient() as client: resp await client.post( f{TAOTOKEN_BASE_URL}/v1/chat/completions, headersheaders, jsonpayload, timeout60.0, ) resp.raise_for_status() data resp.json() return data[choices][0][message][content] mcp.tool() async def echo(text: str) - str: 原樣返回輸入文本用于驗(yàn)證工具鏈路是否打通。 Args: text: 任意字符串 return fecho: {text} mcp.tool() async def ask_model(question: str) - str: 把問題轉(zhuǎn)發(fā)給 TaoToken 模型并返回回答。 Args: question: 要問模型的問題 try: return await call_model(question) except Exception as e: return f調(diào)用模型失敗: {e} if __name__ __main__: mcp.run(transportstdio)這段代碼里mcp.tool()裝飾器把普通 async 函數(shù)注冊(cè)成 MCP 工具函數(shù)名就是工具名docstring 會(huì)成為工具描述參數(shù)類型注解會(huì)生成參數(shù) schema。echo用來做鏈路自檢ask_model演示在工具內(nèi)部再調(diào)模型 API這是很多 Agent 場(chǎng)景的典型結(jié)構(gòu)。如果你用 Cline 或 Claude Code 這類客戶端配置通常是一個(gè) JSON 片段路徑和字段名要對(duì)齊。以常見的 MCP 客戶端配置為例{ mcpServers: { demo-server: { command: uv, args: [run, server.py], env: { TAOTOKEN_API_KEY: sk-你的Key } } } }注意 Base URL、Key、Model ID 三件套要齊全Base URL 是 https://taotoken.net/api Key 從 API Keys 頁面拿Model ID 按控制臺(tái)實(shí)際模型填。少任何一個(gè)工具調(diào)用都會(huì)失敗。4. 驗(yàn)證請(qǐng)求本地啟動(dòng) MCP Server 并完成一次工具調(diào)用代碼寫好后先本地跑起來。用官方 CLI 調(diào)試最方便uv run mcp dev server.py這會(huì)啟動(dòng)一個(gè)調(diào)試界面能看到已注冊(cè)的工具列表。如果echo和ask_model都出現(xiàn)了說明注冊(cè)成功。接著在調(diào)試界面里調(diào)用echo輸入hello應(yīng)該返回echo: hello。這一步驗(yàn)證的是 MCP 協(xié)議鏈路本身不涉及模型。然后驗(yàn)證ask_model。調(diào)用它并傳入用一句話解釋什么是 MCP如果返回一段模型生成的解釋說明工具內(nèi)部調(diào)用 TaoToken 模型 API 也通了。這一步同時(shí)驗(yàn)證了兩條鏈路MCP 工具執(zhí)行 模型 API 請(qǐng)求。如果你想用腳本方式驗(yàn)證可以寫一個(gè)簡單的 stdio 客戶端或者直接用 curl 先單獨(dú)測(cè)模型 APIcurl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d {model:你的模型ID,messages:[{role:user,content:ping}]}返回里有choices字段就說明模型側(cè)沒問題。再回到 MCP 調(diào)試界面調(diào)ask_model成功結(jié)果應(yīng)該是一段自然語言回答。實(shí)測(cè)下來把兩條鏈路分開驗(yàn)證排錯(cuò)效率高很多。成功結(jié)果長這樣調(diào)試界面顯示工具調(diào)用狀態(tài)為 completed返回內(nèi)容是你問的問題的模型回答。如果echo通了但ask_model不通問題一定在模型 API 配置上而不是 MCP 協(xié)議。5. 本篇常見錯(cuò)排查401、local proxy failed、reading choices 與 OAuth 報(bào)錯(cuò)調(diào)試 MCP Server 時(shí)報(bào)錯(cuò)基本集中在幾類。下面按真實(shí)報(bào)錯(cuò)對(duì)照排查。第一類401 Unauthorized。這通常是 Key 不對(duì)或沒帶上。檢查Authorization頭是不是Bearer sk-xxx格式Key 有沒有多余空格環(huán)境變量有沒有真的傳進(jìn)去。如果你在客戶端配置里寫了env確認(rèn)字段名和代碼里讀取的變量名一致。第二類local proxy failed或連接被拒。這多半是 Base URL 寫錯(cuò)比如多加了/v1或結(jié)尾斜杠。Base URL 就用 https://taotoken.net/api 路徑拼接交給代碼。另外確認(rèn)本機(jī)網(wǎng)絡(luò)能正常訪問該地址公司網(wǎng)絡(luò)限制也可能導(dǎo)致連接失敗。第三類reading choices相關(guān)報(bào)錯(cuò)比如KeyError: choices或list index out of range。這說明請(qǐng)求返回了但結(jié)構(gòu)不是預(yù)期的 chat completions 格式。常見原因是 Model ID 填錯(cuò)或者請(qǐng)求體字段名不對(duì)。打印完整響應(yīng)體再定位別只看異常信息。第四類OAuth 相關(guān)報(bào)錯(cuò)。如果你用的是 Claude Code 這類帶 OAuth 流程的工具報(bào)錯(cuò)可能出現(xiàn)在授權(quán)環(huán)節(jié)。這時(shí)候檢查接入文檔里的配置步驟確認(rèn) Base URL 和 Key 的填法符合要求。OAuth 和 API Key 是兩種不同的鑒權(quán)方式別混用。還有一個(gè)隱蔽的坑MCP Server 用 stdio 傳輸時(shí)任何print輸出都會(huì)污染協(xié)議流導(dǎo)致客戶端解析失敗。調(diào)試信息一律用sys.stderr或日志文件別用print。這個(gè)坑我踩過排查了半天才發(fā)現(xiàn)是調(diào)試打印惹的禍。6. 語義一致 CTA把 MCP Server 接到真實(shí)模型與長期編碼場(chǎng)景工具鏈路跑通后下一步就是把它接到真實(shí)使用場(chǎng)景。如果你主要做模型對(duì)話驗(yàn)證可以到 https://taotoken.net/chat 直接體驗(yàn)?zāi)Ｐ蛯?duì)話確認(rèn)模型側(cè)行為符合預(yù)期。如果你要把 MCP 用在長期編碼或 Agent 任務(wù)里建議看 Coding Plan https://taotoken.net/coding-plan 它更適合持續(xù)性的開發(fā)場(chǎng)景。接入文檔在 https://taotoken.net/doc 里面覆蓋了 Base URL、Key、Model ID 的完整配置說明遇到鑒權(quán)或路徑問題先查這里。API Key 管理在 https://taotoken.net/api-keys Key 泄露或額度異常時(shí)及時(shí)輪換?？刂婆_(tái) https://taotoken.net/console 可以看用量和模型列表?；氐酱a本身一個(gè)實(shí)用的技巧是把call_model里的模型 ID 和 Base URL 抽成環(huán)境變量這樣本地調(diào)試和線上部署用同一份代碼只換配置。另外給工具函數(shù)加超時(shí)和重試模型 API 偶爾抖動(dòng)時(shí)不會(huì)直接把整個(gè) MCP 調(diào)用拖死。最后工具描述docstring寫清楚模型選工具的準(zhǔn)確率會(huì)明顯提升這比調(diào)參管用。