1. 从零理解 MCPPython 手写一个可调试的 MCP Server 到底在做什么MCPModel Context Protocol说白了就是一套“让模型调用外部工具”的约定。你可以把它想成模型和你的代码之间的一份菜单模型看到菜单上有哪些工具、每个工具要什么参数然后决定点哪道菜你的 MCP Server 负责把这道菜做出来再把结果端回去。Python 实现一个简单的 MCP核心就三件事注册工具、路由请求、把结果按协议格式返回。很多人第一次接触 MCP 会以为它很玄其实底层交互非常朴素。以常见的客户端为例你在对话框里提问客户端把你的问题连同“当前可用的 tools 列表”一起发给模型模型分析后决定调用哪个 tool并给出参数客户端通过 MCP Server 执行这个 tool执行结果回传给模型模型再用自然语言把结果组织成回答展示给你。整条链路里MCP Server 就是那个“真正干活”的角色。这篇面向的是想自己动手写一个最小可用 MCP Server 的 Python 开发者。你不需要先精通协议细节只要会写异步函数、懂一点类型注解就能跟着把 server.py 骨架搭起来注册两个工具本地跑通再把 endpoint 切到 TaoToken 完成一次真实的工具调用验证。适合谁适合正在做 Agent、想让模型调用自己业务接口、又不想被复杂框架绑住的人。我试过用官方 SDK 的 FastMCP 类来搭体验是它用 Python 的 type hints 和 docstring 自动生成 tool definition省掉了手写 JSON Schema 的麻烦。你只要写一个带类型注解的 async 函数加个装饰器它就能被模型识别。下面从环境准备开始一步步来。2. TaoToken 前置准备Python MCP Server 接入大模型 API 的 Base URL 与 Key 配置在写 Server 之前先把“模型侧”的接入准备好。MCP Server 本身只负责执行工具真正决定调用哪个工具的是模型所以你需要一个能访问模型 API 的入口。这里用 TaoToken 来做模型接入它的接口兼容主流协议Base URL 和 Key 配好之后客户端或你的调试脚本就能直接调模型。先拿到 API Key。打开 https://taotoken.net/api-keys 登录后创建一个 Key复制保存。注意 Key 只在创建时完整显示一次丢了就重新建一个。这个 Key 后面会写进配置里别硬编码进 Git 仓库。Base URL 用 https://taotoken.net/api 这是接口根地址不要在后面乱加斜杠。模型 ID 按你实际要用的填比如 claude 系列或 gpt 系列的模型标识具体以控制台模型列表为准。你可以到 https://taotoken.net/console 查看可用模型和额度情况。如果你用的是 Claude Code 这类工具配置方式略有不同可以参考接入文档 https://taotoken.net/doc 里的说明。文档里对 Base URL、Key、Model ID 三件套的填法讲得比较清楚。对于本篇的 MCP 调试我们主要用 Python 脚本直接请求所以只要保证 Base URL 和 Key 正确即可。这里要强调一个容易踩的点MCP Server 和模型 API 是两个独立的东西。Server 负责执行工具模型 API 负责决策。很多人把两者混在一起结果调试时不知道是工具没注册成功还是模型没调通。分开验证问题就好定位。先把模型 API 用 curl 或 Python 请求通再回来调 MCP 工具链路。3. 可复制配置server.py 骨架、依赖清单与 MCP 工具注册这一节是核心直接给可复制的代码和配置。先建项目目录用 uv 管理环境用 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 和命令行调试能力httpx 用来发异步 HTTP 请求。装完后新建 server.py写入下面的骨架from typing import Any import httpx from mcp.server.fastmcp import FastMCP # 初始化 FastMCP server名字会出现在客户端工具列表里 mcp FastMCP(demo-server) # 模型 API 配置实际使用时从环境变量读取更安全 TAOTOKEN_BASE_URL https://taotoken.net/api TAOTOKEN_API_KEY sk-你的Key async def call_model(prompt: str) - str: 调用 TaoToken 模型接口返回文本结果。 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: 原样返回输入文本用于验证工具链路是否打通。 Args: text: 任意字符串 return fecho: {text} mcp.tool() async def ask_model(question: str) - str: 把问题转发给 TaoToken 模型并返回回答。 Args: question: 要问模型的问题 try: return await call_model(question) except Exception as e: return f调用模型失败: {e} if __name__ __main__: mcp.run(transportstdio)这段代码里mcp.tool()装饰器把普通 async 函数注册成 MCP 工具函数名就是工具名docstring 会成为工具描述参数类型注解会生成参数 schema。echo用来做链路自检ask_model演示在工具内部再调模型 API这是很多 Agent 场景的典型结构。如果你用 Cline 或 Claude Code 这类客户端配置通常是一个 JSON 片段路径和字段名要对齐。以常见的 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 按控制台实际模型填。少任何一个工具调用都会失败。4. 验证请求本地启动 MCP Server 并完成一次工具调用代码写好后先本地跑起来。用官方 CLI 调试最方便uv run mcp dev server.py这会启动一个调试界面能看到已注册的工具列表。如果echo和ask_model都出现了说明注册成功。接着在调试界面里调用echo输入hello应该返回echo: hello。这一步验证的是 MCP 协议链路本身不涉及模型。然后验证ask_model。调用它并传入用一句话解释什么是 MCP如果返回一段模型生成的解释说明工具内部调用 TaoToken 模型 API 也通了。这一步同时验证了两条链路MCP 工具执行 模型 API 请求。如果你想用脚本方式验证可以写一个简单的 stdio 客户端或者直接用 curl 先单独测模型 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字段就说明模型侧没问题。再回到 MCP 调试界面调ask_model成功结果应该是一段自然语言回答。实测下来把两条链路分开验证排错效率高很多。成功结果长这样调试界面显示工具调用状态为 completed返回内容是你问的问题的模型回答。如果echo通了但ask_model不通问题一定在模型 API 配置上而不是 MCP 协议。5. 本篇常见错排查401、local proxy failed、reading choices 与 OAuth 报错调试 MCP Server 时报错基本集中在几类。下面按真实报错对照排查。第一类401 Unauthorized。这通常是 Key 不对或没带上。检查Authorization头是不是Bearer sk-xxx格式Key 有没有多余空格环境变量有没有真的传进去。如果你在客户端配置里写了env确认字段名和代码里读取的变量名一致。第二类local proxy failed或连接被拒。这多半是 Base URL 写错比如多加了/v1或结尾斜杠。Base URL 就用 https://taotoken.net/api 路径拼接交给代码。另外确认本机网络能正常访问该地址公司网络限制也可能导致连接失败。第三类reading choices相关报错比如KeyError: choices或list index out of range。这说明请求返回了但结构不是预期的 chat completions 格式。常见原因是 Model ID 填错或者请求体字段名不对。打印完整响应体再定位别只看异常信息。第四类OAuth 相关报错。如果你用的是 Claude Code 这类带 OAuth 流程的工具报错可能出现在授权环节。这时候检查接入文档里的配置步骤确认 Base URL 和 Key 的填法符合要求。OAuth 和 API Key 是两种不同的鉴权方式别混用。还有一个隐蔽的坑MCP Server 用 stdio 传输时任何print输出都会污染协议流导致客户端解析失败。调试信息一律用sys.stderr或日志文件别用print。这个坑我踩过排查了半天才发现是调试打印惹的祸。6. 语义一致 CTA把 MCP Server 接到真实模型与长期编码场景工具链路跑通后下一步就是把它接到真实使用场景。如果你主要做模型对话验证可以到 https://taotoken.net/chat 直接体验模型对话确认模型侧行为符合预期。如果你要把 MCP 用在长期编码或 Agent 任务里建议看 Coding Plan https://taotoken.net/coding-plan 它更适合持续性的开发场景。接入文档在 https://taotoken.net/doc 里面覆盖了 Base URL、Key、Model ID 的完整配置说明遇到鉴权或路径问题先查这里。API Key 管理在 https://taotoken.net/api-keys Key 泄露或额度异常时及时轮换。控制台 https://taotoken.net/console 可以看用量和模型列表。回到代码本身一个实用的技巧是把call_model里的模型 ID 和 Base URL 抽成环境变量这样本地调试和线上部署用同一份代码只换配置。另外给工具函数加超时和重试模型 API 偶尔抖动时不会直接把整个 MCP 调用拖死。最后工具描述docstring写清楚模型选工具的准确率会明显提升这比调参管用。