1. 为什么 MCP 需要 Host、Client、Server 三个角色MCPModel Context Protocol是一套让大语言模型安全调用外部工具的开放协议它把模型决策和工具执行拆成三个独立角色Host 负责运行环境与安全网关Client 负责理解意图并做决策Server 负责提供具体能力。这套三角色架构最适合正在用 OpenAI 接口做 Agent 开发、又不想为每个工具重写胶水代码的工程师。我试过把天气查询、数据库读取、代码仓库检索分别封装成 Server再让同一个 Client 复用改动量比传统 function calling 少了一大半。传统做法里模型和工具是硬编码绑定的。你想让 GPT-4 查天气就得在 prompt 里塞工具描述在代码里写 if-else 分发工具一多就变成意大利面。MCP 的核心思路是语义化工具发现Server 用自然语言描述自己有哪些工具、参数是什么Host 把这些描述汇总后交给 ClientClient 像人翻说明书一样决定调哪个。这样工具一次开发、处处可用语言无关Python、Go、JavaScript 都能实现 Server。三角色的职责边界非常清晰。Server 是专业工具提供者只关心自己的领域逻辑比如查天气、读数据库、跑测试它通过 stdio、HTTP 或 SSH 暴露 JSON-RPC 接口。Client 是AI 决策大脑它不碰网络、不碰安全、不碰协议细节只做一件事拿到用户请求和可用工具列表输出结构化的工具调用决策。Host 是协议网关与安全代理它管理所有 Server 连接、做协议转换、执行权限控制、记录审计日志Client 想访问任何 Server 都必须经过 Host。用一个类比Host 像智能手机的操作系统Client 像你点开某个 App 时的意图识别层Server 像高德地图、微信支付这些具体 App 的后端服务。你点导航回家系统识别意图Client调用高德Server但整个过程受操作系统权限管理Host约束——位置权限要确认、调用要记日志。MCP 三角色就是这套关系缺了 Host安全模型就塌了。为什么不能 Client 直连 Server技术上可行一个能收发 JSON 的脚本就能直接跟 Server 通信。但生产环境里这等于让 AI 模型拿到生产系统的最高权限一旦被提示词诱导或出现幻觉后果不可控。Host 存在的意义就是强制依赖点所有外部访问必须经过它权限、审计、脱敏都在这一层做。这也是 MCP 架构设计的底线不是可选项。理解了三角色接下来要解决的是接入通道问题。本地开发时Client 需要调用 OpenAI 接口做决策Server 需要被 Host 拉起这些请求都要走一个稳定的 API 通道。下面用 TaoToken 统一 Key 和 API 通道把整条链路跑通。2. TaoToken 统一接入Key 与 API 通道准备在本地搭 MCP 调用链路最容易卡住的不是协议本身而是 API 通道。Client 要调 OpenAI 做决策Server 里可能也要调模型做二次处理如果每个组件各自配一套 Key 和 Base URL管理起来很乱还容易把 Key 硬编码进代码。TaoToken 的作用就是提供统一的 Key 和 API 通道让 Host、Client、Server 都指向同一个入口配置集中、切换方便。你需要先拿到一个可用的 API Key。登录 TaoToken 控制台在 API Keys 页面创建一个新 Key复制保存。这个 Key 后面会同时用于 Client 的模型调用和 Server 的模型调用所以不要泄露到前端或公开仓库。控制台地址是 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 。Base URL 统一用 https://taotoken.net/api 注意这个地址不带任何查询参数直接作为 OpenAI SDK 的 base_url 使用。模型 ID 根据你的场景选做 MCP Client 决策推荐用支持 function calling 的模型比如 gpt-4o 或 gpt-4o-mini如果只是做连通性验证gpt-4o-mini 足够且便宜。Model ID 的完整列表可以在模型对话页面查看https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。环境变量建议这样组织避免把 Key 写死在代码里export TAOTOKEN_API_KEYsk-你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api export TAOTOKEN_MODELgpt-4o-mini如果你用 Python 的 openai SDK初始化 Client 时这样写import os from openai import OpenAI client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL], )这样 Client 和 Server 都可以复用同一个环境变量Host 在拉起 Server 子进程时把环境变量透传下去即可。实测下来这种集中配置方式在调试阶段特别省事换模型只改一个变量不用翻遍代码找硬编码。有一点要注意TaoToken 是 API 通道不是编辑器替代品也不是 MCP Server 本身。它解决的是模型调用走哪里的问题MCP 三角色的职责划分和协议逻辑还是要在你的代码里实现。把这两件事分清楚配置才不会乱。Key 准备好之后下一步是把三角色用可复制的配置片段串起来。下面给出 Host、Client、Server 的最小可运行配置以及 settings 片段。3. 可复制配置Host、Client、Server 三角色 settings 片段这一节给出可以直接复制运行的配置。为了让结构清晰我用一个mcp_config.json管理 Server 注册信息用 Python 实现 Host 和 ClientServer 单独一个文件。所有模型调用都走 TaoToken 的 Base URL 和 Key。先看 Server 注册配置mcp_config.jsonHost 读这个文件来决定拉起哪些 Server{ servers: { weather-service: { command: [python, weather_server.py], env: { TAOTOKEN_API_KEY: ${TAOTOKEN_API_KEY}, TAOTOKEN_BASE_URL: https://taotoken.net/api } } } }这个 JSON 里command是 Host 拉起 Server 子进程的命令env是透传给子进程的环境变量。注意 Base URL 写的是不带 UTM 的 API 地址Key 用${TAOTOKEN_API_KEY}占位运行时从宿主环境读取避免明文写进配置文件。接下来是 Server 实现weather_server.py它通过 stdio 暴露tools/list和tools/call两个方法import json import sys TOOLS [{ name: get_current_weather, description: 获取指定城市的当前天气情况, inputSchema: { type: object, properties: { city: {type: string, description: 城市名称如北京、上海} }, required: [city] } }] def handle_weather(city): mock { 北京: {temp: 22°C, condition: 晴朗, humidity: 45%}, 上海: {temp: 25°C, condition: 多云, humidity: 65%} } return mock.get(city, {error: 城市不支持}) def process(request): method request.get(method) if method tools/list: return {jsonrpc: 2.0, result: {tools: TOOLS}, id: request.get(id)} if method tools/call: params request.get(params, {}) if params.get(name) get_current_weather: city params.get(arguments, {}).get(city, 北京) result handle_weather(city) return {jsonrpc: 2.0, result: {content: [{type: text, text: json.dumps(result)}]}, id: request.get(id)} return {jsonrpc: 2.0, error: 方法不支持, id: request.get(id)} for line in sys.stdin: line line.strip() if not line: continue req json.loads(line) resp process(req) sys.stdout.write(json.dumps(resp) \n) sys.stdout.flush()这个 Server 不依赖任何第三方库纯标准库实现方便你直接跑起来验证协议。真实场景里把handle_weather换成真实 API 调用即可。然后是 Host 实现host.py它负责拉起 Server、注册工具、转发调用import json import os import subprocess class MCPHost: def __init__(self): self.processes {} self.tool_registry {} def connect(self, name, command, envNone): full_env os.environ.copy() if env: full_env.update(env) proc subprocess.Popen( command, stdinsubprocess.PIPE, stdoutsubprocess.PIPE, stderrsubprocess.PIPE, textTrue, bufsize1, envfull_env ) req json.dumps({jsonrpc: 2.0, method: tools/list, id: 1}) proc.stdin.write(req \n) proc.stdin.flush() resp json.loads(proc.stdout.readline()) for tool in resp.get(result, {}).get(tools, []): self.tool_registry[tool[name]] {proc: proc, server: name} self.processes[name] proc print(f已连接 {name}工具: {list(self.tool_registry.keys())}) def call_tool(self, tool_name, arguments): if tool_name not in self.tool_registry: return {error: f工具 {tool_name} 未找到} proc self.tool_registry[tool_name][proc] req json.dumps({ jsonrpc: 2.0, method: tools/call, params: {name: tool_name, arguments: arguments}, id: 2 }) proc.stdin.write(req \n) proc.stdin.flush() return json.loads(proc.stdout.readline())Host 的核心是tool_registry它把工具名映射到对应的 Server 进程Client 只看到工具名不知道背后是哪个进程这就是强制依赖点的体现。最后是 Client 实现client.py它调用 TaoToken 的 OpenAI 兼容接口做决策import json import os from openai import OpenAI class MCPClient: def __init__(self): self.client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL], ) self.model os.environ.get(TAOTOKEN_MODEL, gpt-4o-mini) self.tools [] def set_tools(self, tool_names): self.tools tool_names def decide(self, user_query): messages [ {role: system, content: 你是一个可以查询天气的助手。}, {role: user, content: user_query} ] if self.tools: response self.client.chat.completions.create( modelself.model, messagesmessages, tools[{ type: function, function: { name: get_current_weather, description: 获取指定城市的当前天气情况, parameters: { type: object, properties: {city: {type: string}}, required: [city] } } }], tool_choiceauto ) msg response.choices[0].message if msg.tool_calls: tc msg.tool_calls[0] return {action: call_tool, tool_name: tc.function.name, arguments: json.loads(tc.function.arguments)} response self.client.chat.completions.create(modelself.model, messagesmessages) return {action: direct_response, content: response.choices[0].message.content}这三个文件加上mcp_config.json就是完整的三角色最小实现。Client 里的tools参数目前是硬编码的真实项目里应该从 Host 的tool_registry动态生成这里为了可读性做了简化。如果你用 Claude Code 或 Cline 这类工具它们的 MCP 配置通常写在settings.json或mcp.json里格式类似{ mcpServers: { weather-service: { command: python, args: [weather_server.py], env: { TAOTOKEN_API_KEY: sk-你的Key, TAOTOKEN_BASE_URL: https://taotoken.net/api } } } }注意这里 Base URL 同样不带 UTM 参数Key 建议用环境变量引用而不是明文。Codex 的auth.json里如果配了自定义 Base URL也要确保指向https://taotoken.net/apiModel ID 填你实际使用的模型名。这三件套——Base URL、Key、Model ID——在任何一个 MCP 客户端里都要对齐否则会出现认证失败或模型找不到的错误。4. 验证请求跑通完整调用链路配置写完之后最关键的一步是验证整条链路能不能跑通。我按先 Server、再 Host、最后 Client的顺序验证这样出错时容易定位是哪一层的问题。第一步单独验证 Server 能否正确响应tools/list。在终端里手动发一条 JSON-RPC 请求echo {jsonrpc:2.0,method:tools/list,id:1} | python weather_server.py预期输出是一行 JSON包含get_current_weather工具的描述{jsonrpc: 2.0, result: {tools: [{name: get_current_weather, description: 获取指定城市的当前天气情况, inputSchema: {type: object, properties: {city: {type: string, description: 城市名称如北京、上海}}, required: [city]}}]}, id: 1}如果这一步没输出检查 Python 版本和文件路径如果输出报错检查 JSON 格式是否合法。Server 层验证通过说明协议实现没问题。第二步验证 Host 能否拉起 Server 并注册工具。写一个简单的测试脚本from host import MCPHost host MCPHost() host.connect(weather-service, [python, weather_server.py]) result host.call_tool(get_current_weather, {city: 上海}) print(result)预期输出里能看到已连接 weather-service工具: [get_current_weather]以及工具调用返回的天气数据。如果 Host 报FileNotFoundError检查weather_server.py是否在当前目录如果卡住不返回检查 Server 的stdout.flush()是否加了stdio 模式下不 flush 会导致 Host 一直等。第三步验证 Client 能否通过 TaoToken 做出正确决策。运行完整链路import os from host import MCPHost from client import MCPClient host MCPHost() host.connect(weather-service, [python, weather_server.py]) client MCPClient() client.set_tools(list(host.tool_registry.keys())) decision client.decide(上海天气怎么样) print(决策:, decision) if decision[action] call_tool: result host.call_tool(decision[tool_name], decision[arguments]) print(工具结果:, result)预期输出分两段第一段是 Client 的决策形如{action: call_tool, tool_name: get_current_weather, arguments: {city: 上海}}第二段是 Host 转发后拿到的天气数据。看到这两段说明 Host、Client、Server 三角色和 TaoToken 通道全部打通。如果 Client 返回的是direct_response而不是call_tool说明模型没有选择调用工具。可能原因是模型不支持 function calling或者tools参数格式不对。换成gpt-4o或gpt-4o-mini再试同时确认tool_choice设为auto。验证成功后你可以把handle_weather换成真实 API把 Server 数量增加Host 会自动注册新工具Client 的决策逻辑不用改。这就是三角色架构的价值扩展能力只需要加 Server决策层和网关层保持稳定。实测下来整条链路从零到跑通大约 20 分钟主要时间花在环境变量和路径配置上。建议把TAOTOKEN_API_KEY、TAOTOKEN_BASE_URL、TAOTOKEN_MODEL三个变量写进.env文件用python-dotenv加载避免每次开终端都要 export。5. 常见报错排查401、local proxy failed、reading choices、OAuth跑 MCP 链路时报错信息往往指向不同层按层排查效率最高。下面是我踩过的几个典型错误和对应解法。401 Unauthorized这是认证层问题说明 Key 无效或没传对。检查三件事TAOTOKEN_API_KEY环境变量是否真的被进程读到在代码里 print 一下长度不要 print 完整 KeyBase URL 是否写成https://taotoken.net/api而不是带/v1或其他路径Key 是否在控制台被禁用或删除。如果 Host 拉起 Server 时用了env透传确认mcp_config.json里的${TAOTOKEN_API_KEY}被正确替换有些 shell 不展开 JSON 里的变量需要在 Host 代码里手动替换。local proxy failed这个报错通常出现在网络层说明请求没到达 TaoToken 的 API 地址。检查本机网络是否能访问https://taotoken.net/api用curl -I https://taotoken.net/api看返回状态。如果公司网络有出口限制确认该域名在允许列表里。另外检查是否误设了HTTP_PROXY或HTTPS_PROXY环境变量这些变量会让 SDK 走本地代理导致连接失败。清掉这两个变量再试。reading choices of undefined这是响应解析层问题说明 SDK 拿到的响应结构不符合预期。常见原因是 Base URL 配错请求打到了非 OpenAI 兼容的端点返回了 HTML 或错误 JSON。确认base_url是https://taotoken.net/api且没有多余路径。另一个原因是模型 ID 写错服务端返回了错误对象而不是 completion 对象。在代码里加一层判断response client.chat.completions.create(...) if not response.choices: print(响应异常:, response) return这样能看到实际返回内容快速定位是模型名错还是通道错。OAuth 相关报错如果你用 Claude Code 或 Cline 这类工具它们可能走 OAuth 流程而不是 API Key。报错形如OAuth token expired或invalid_grant。这种情况下不要混用 OAuth 和 API Key二选一。用 TaoToken 的 API Key 模式时在工具的配置里选择API Key认证方式填入 Key 和 Base URL不要走 OAuth 登录。如果工具强制 OAuth检查是否有自定义端点选项把端点指向https://taotoken.net/api。工具调用返回空Client 决策正确但 Host 拿不到结果通常是 Server 进程的 stdout 缓冲问题。stdio 模式下Server 每次写响应后必须flush()否则 Host 的readline()会一直阻塞。检查 Server 代码里sys.stdout.flush()是否在每次 write 后调用。另一个可能是 Server 进程崩溃了检查stderr输出把stderrsubprocess.PIPE改成stderrNone让错误直接打印到终端。模型不调用工具Client 返回direct_response而不是call_tool说明模型没触发 function calling。检查tools参数的 JSON Schema 是否合法required字段是否和properties对应。有些模型对工具描述敏感把description写得更具体比如获取指定城市的当前天气情况包括温度和湿度能提高触发率。如果还是不行换gpt-4o试试它的 function calling 稳定性更好。排查时建议按Server → Host → Client → 通道的顺序逐层验证每层单独跑通再串联。这样报错时能快速缩小范围不用在整条链路里猜。三角色架构的好处在这里也体现出来每层职责单一排查目标明确。6. 从三角色到生产MCP 接入的长期实践把最小链路跑通只是起点真正要在项目里用起来还需要考虑几件事。第一是 Server 的复用性把每个领域能力封装成独立 Server比如数据库 Server、代码仓库 Server、监控 ServerHost 统一注册Client 按需决策。这样新增能力不用改 Client 代码符合开闭原则。第二是安全策略的落地。Host 层要做的不只是转发还要加权限控制、审计日志、输入输出过滤。比如在call_tool里加一层白名单校验只允许特定工具被调用在转发前记录调用者、时间、参数在返回后对敏感字段做脱敏。这些逻辑集中在 Host 一处比散落在各个 Server 里好维护得多。第三是通道的稳定性。TaoToken 作为统一 API 通道好处是 Key 和 Base URL 集中管理切换模型或调整配额只改一处。长期编码和 Agent 场景如果调用量大可以关注 Coding Plan 的配额方案https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面有各语言 SDK 的配置示例。第四是调试工具的准备。模型对话页面可以用来单独验证模型是否正常响应https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。当 Client 决策异常时先在对话页面用同样的 prompt 测一下能快速判断是模型问题还是代码问题。API Keys 管理页面用来轮换 Keyhttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。如果你用 Claude Code 做开发它的 MCP 配置和 Anthropic 的接入方式可以参考https://taotoken.net/claude-code?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。注意 Claude Code 的配置里 Base URL 同样指向https://taotoken.net/apiModel ID 按实际使用的模型填Key 用环境变量引用。最后一点经验三角色架构的价值不在于能连上工具而在于安全、可控、可审计地连上工具。Client 直连 Server 在 demo 里能跑但生产环境里 Host 这一层不能省。把 Host 当成基础设施来对待像重视数据库和 API 网关一样重视它的配置和监控整条链路才能长期稳定运行。 【AI】AI学习笔记：MCP 核心三角色指南：基于 OpenAI 的架构解析与 TaoToken 统一接入实践
1. 为什么 MCP 需要 Host、Client、Server 三个角色MCPModel Context Protocol是一套让大语言模型安全调用外部工具的开放协议它把模型决策和工具执行拆成三个独立角色Host 负责运行环境与安全网关Client 负责理解意图并做决策Server 负责提供具体能力。这套三角色架构最适合正在用 OpenAI 接口做 Agent 开发、又不想为每个工具重写胶水代码的工程师。我试过把天气查询、数据库读取、代码仓库检索分别封装成 Server再让同一个 Client 复用改动量比传统 function calling 少了一大半。传统做法里模型和工具是硬编码绑定的。你想让 GPT-4 查天气就得在 prompt 里塞工具描述在代码里写 if-else 分发工具一多就变成意大利面。MCP 的核心思路是语义化工具发现Server 用自然语言描述自己有哪些工具、参数是什么Host 把这些描述汇总后交给 ClientClient 像人翻说明书一样决定调哪个。这样工具一次开发、处处可用语言无关Python、Go、JavaScript 都能实现 Server。三角色的职责边界非常清晰。Server 是专业工具提供者只关心自己的领域逻辑比如查天气、读数据库、跑测试它通过 stdio、HTTP 或 SSH 暴露 JSON-RPC 接口。Client 是AI 决策大脑它不碰网络、不碰安全、不碰协议细节只做一件事拿到用户请求和可用工具列表输出结构化的工具调用决策。Host 是协议网关与安全代理它管理所有 Server 连接、做协议转换、执行权限控制、记录审计日志Client 想访问任何 Server 都必须经过 Host。用一个类比Host 像智能手机的操作系统Client 像你点开某个 App 时的意图识别层Server 像高德地图、微信支付这些具体 App 的后端服务。你点导航回家系统识别意图Client调用高德Server但整个过程受操作系统权限管理Host约束——位置权限要确认、调用要记日志。MCP 三角色就是这套关系缺了 Host安全模型就塌了。为什么不能 Client 直连 Server技术上可行一个能收发 JSON 的脚本就能直接跟 Server 通信。但生产环境里这等于让 AI 模型拿到生产系统的最高权限一旦被提示词诱导或出现幻觉后果不可控。Host 存在的意义就是强制依赖点所有外部访问必须经过它权限、审计、脱敏都在这一层做。这也是 MCP 架构设计的底线不是可选项。理解了三角色接下来要解决的是接入通道问题。本地开发时Client 需要调用 OpenAI 接口做决策Server 需要被 Host 拉起这些请求都要走一个稳定的 API 通道。下面用 TaoToken 统一 Key 和 API 通道把整条链路跑通。2. TaoToken 统一接入Key 与 API 通道准备在本地搭 MCP 调用链路最容易卡住的不是协议本身而是 API 通道。Client 要调 OpenAI 做决策Server 里可能也要调模型做二次处理如果每个组件各自配一套 Key 和 Base URL管理起来很乱还容易把 Key 硬编码进代码。TaoToken 的作用就是提供统一的 Key 和 API 通道让 Host、Client、Server 都指向同一个入口配置集中、切换方便。你需要先拿到一个可用的 API Key。登录 TaoToken 控制台在 API Keys 页面创建一个新 Key复制保存。这个 Key 后面会同时用于 Client 的模型调用和 Server 的模型调用所以不要泄露到前端或公开仓库。控制台地址是 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 。Base URL 统一用 https://taotoken.net/api 注意这个地址不带任何查询参数直接作为 OpenAI SDK 的 base_url 使用。模型 ID 根据你的场景选做 MCP Client 决策推荐用支持 function calling 的模型比如 gpt-4o 或 gpt-4o-mini如果只是做连通性验证gpt-4o-mini 足够且便宜。Model ID 的完整列表可以在模型对话页面查看https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。环境变量建议这样组织避免把 Key 写死在代码里export TAOTOKEN_API_KEYsk-你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api export TAOTOKEN_MODELgpt-4o-mini如果你用 Python 的 openai SDK初始化 Client 时这样写import os from openai import OpenAI client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL], )这样 Client 和 Server 都可以复用同一个环境变量Host 在拉起 Server 子进程时把环境变量透传下去即可。实测下来这种集中配置方式在调试阶段特别省事换模型只改一个变量不用翻遍代码找硬编码。有一点要注意TaoToken 是 API 通道不是编辑器替代品也不是 MCP Server 本身。它解决的是模型调用走哪里的问题MCP 三角色的职责划分和协议逻辑还是要在你的代码里实现。把这两件事分清楚配置才不会乱。Key 准备好之后下一步是把三角色用可复制的配置片段串起来。下面给出 Host、Client、Server 的最小可运行配置以及 settings 片段。3. 可复制配置Host、Client、Server 三角色 settings 片段这一节给出可以直接复制运行的配置。为了让结构清晰我用一个mcp_config.json管理 Server 注册信息用 Python 实现 Host 和 ClientServer 单独一个文件。所有模型调用都走 TaoToken 的 Base URL 和 Key。先看 Server 注册配置mcp_config.jsonHost 读这个文件来决定拉起哪些 Server{ servers: { weather-service: { command: [python, weather_server.py], env: { TAOTOKEN_API_KEY: ${TAOTOKEN_API_KEY}, TAOTOKEN_BASE_URL: https://taotoken.net/api } } } }这个 JSON 里command是 Host 拉起 Server 子进程的命令env是透传给子进程的环境变量。注意 Base URL 写的是不带 UTM 的 API 地址Key 用${TAOTOKEN_API_KEY}占位运行时从宿主环境读取避免明文写进配置文件。接下来是 Server 实现weather_server.py它通过 stdio 暴露tools/list和tools/call两个方法import json import sys TOOLS [{ name: get_current_weather, description: 获取指定城市的当前天气情况, inputSchema: { type: object, properties: { city: {type: string, description: 城市名称如北京、上海} }, required: [city] } }] def handle_weather(city): mock { 北京: {temp: 22°C, condition: 晴朗, humidity: 45%}, 上海: {temp: 25°C, condition: 多云, humidity: 65%} } return mock.get(city, {error: 城市不支持}) def process(request): method request.get(method) if method tools/list: return {jsonrpc: 2.0, result: {tools: TOOLS}, id: request.get(id)} if method tools/call: params request.get(params, {}) if params.get(name) get_current_weather: city params.get(arguments, {}).get(city, 北京) result handle_weather(city) return {jsonrpc: 2.0, result: {content: [{type: text, text: json.dumps(result)}]}, id: request.get(id)} return {jsonrpc: 2.0, error: 方法不支持, id: request.get(id)} for line in sys.stdin: line line.strip() if not line: continue req json.loads(line) resp process(req) sys.stdout.write(json.dumps(resp) \n) sys.stdout.flush()这个 Server 不依赖任何第三方库纯标准库实现方便你直接跑起来验证协议。真实场景里把handle_weather换成真实 API 调用即可。然后是 Host 实现host.py它负责拉起 Server、注册工具、转发调用import json import os import subprocess class MCPHost: def __init__(self): self.processes {} self.tool_registry {} def connect(self, name, command, envNone): full_env os.environ.copy() if env: full_env.update(env) proc subprocess.Popen( command, stdinsubprocess.PIPE, stdoutsubprocess.PIPE, stderrsubprocess.PIPE, textTrue, bufsize1, envfull_env ) req json.dumps({jsonrpc: 2.0, method: tools/list, id: 1}) proc.stdin.write(req \n) proc.stdin.flush() resp json.loads(proc.stdout.readline()) for tool in resp.get(result, {}).get(tools, []): self.tool_registry[tool[name]] {proc: proc, server: name} self.processes[name] proc print(f已连接 {name}工具: {list(self.tool_registry.keys())}) def call_tool(self, tool_name, arguments): if tool_name not in self.tool_registry: return {error: f工具 {tool_name} 未找到} proc self.tool_registry[tool_name][proc] req json.dumps({ jsonrpc: 2.0, method: tools/call, params: {name: tool_name, arguments: arguments}, id: 2 }) proc.stdin.write(req \n) proc.stdin.flush() return json.loads(proc.stdout.readline())Host 的核心是tool_registry它把工具名映射到对应的 Server 进程Client 只看到工具名不知道背后是哪个进程这就是强制依赖点的体现。最后是 Client 实现client.py它调用 TaoToken 的 OpenAI 兼容接口做决策import json import os from openai import OpenAI class MCPClient: def __init__(self): self.client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL], ) self.model os.environ.get(TAOTOKEN_MODEL, gpt-4o-mini) self.tools [] def set_tools(self, tool_names): self.tools tool_names def decide(self, user_query): messages [ {role: system, content: 你是一个可以查询天气的助手。}, {role: user, content: user_query} ] if self.tools: response self.client.chat.completions.create( modelself.model, messagesmessages, tools[{ type: function, function: { name: get_current_weather, description: 获取指定城市的当前天气情况, parameters: { type: object, properties: {city: {type: string}}, required: [city] } } }], tool_choiceauto ) msg response.choices[0].message if msg.tool_calls: tc msg.tool_calls[0] return {action: call_tool, tool_name: tc.function.name, arguments: json.loads(tc.function.arguments)} response self.client.chat.completions.create(modelself.model, messagesmessages) return {action: direct_response, content: response.choices[0].message.content}这三个文件加上mcp_config.json就是完整的三角色最小实现。Client 里的tools参数目前是硬编码的真实项目里应该从 Host 的tool_registry动态生成这里为了可读性做了简化。如果你用 Claude Code 或 Cline 这类工具它们的 MCP 配置通常写在settings.json或mcp.json里格式类似{ mcpServers: { weather-service: { command: python, args: [weather_server.py], env: { TAOTOKEN_API_KEY: sk-你的Key, TAOTOKEN_BASE_URL: https://taotoken.net/api } } } }注意这里 Base URL 同样不带 UTM 参数Key 建议用环境变量引用而不是明文。Codex 的auth.json里如果配了自定义 Base URL也要确保指向https://taotoken.net/apiModel ID 填你实际使用的模型名。这三件套——Base URL、Key、Model ID——在任何一个 MCP 客户端里都要对齐否则会出现认证失败或模型找不到的错误。4. 验证请求跑通完整调用链路配置写完之后最关键的一步是验证整条链路能不能跑通。我按先 Server、再 Host、最后 Client的顺序验证这样出错时容易定位是哪一层的问题。第一步单独验证 Server 能否正确响应tools/list。在终端里手动发一条 JSON-RPC 请求echo {jsonrpc:2.0,method:tools/list,id:1} | python weather_server.py预期输出是一行 JSON包含get_current_weather工具的描述{jsonrpc: 2.0, result: {tools: [{name: get_current_weather, description: 获取指定城市的当前天气情况, inputSchema: {type: object, properties: {city: {type: string, description: 城市名称如北京、上海}}, required: [city]}}]}, id: 1}如果这一步没输出检查 Python 版本和文件路径如果输出报错检查 JSON 格式是否合法。Server 层验证通过说明协议实现没问题。第二步验证 Host 能否拉起 Server 并注册工具。写一个简单的测试脚本from host import MCPHost host MCPHost() host.connect(weather-service, [python, weather_server.py]) result host.call_tool(get_current_weather, {city: 上海}) print(result)预期输出里能看到已连接 weather-service工具: [get_current_weather]以及工具调用返回的天气数据。如果 Host 报FileNotFoundError检查weather_server.py是否在当前目录如果卡住不返回检查 Server 的stdout.flush()是否加了stdio 模式下不 flush 会导致 Host 一直等。第三步验证 Client 能否通过 TaoToken 做出正确决策。运行完整链路import os from host import MCPHost from client import MCPClient host MCPHost() host.connect(weather-service, [python, weather_server.py]) client MCPClient() client.set_tools(list(host.tool_registry.keys())) decision client.decide(上海天气怎么样) print(决策:, decision) if decision[action] call_tool: result host.call_tool(decision[tool_name], decision[arguments]) print(工具结果:, result)预期输出分两段第一段是 Client 的决策形如{action: call_tool, tool_name: get_current_weather, arguments: {city: 上海}}第二段是 Host 转发后拿到的天气数据。看到这两段说明 Host、Client、Server 三角色和 TaoToken 通道全部打通。如果 Client 返回的是direct_response而不是call_tool说明模型没有选择调用工具。可能原因是模型不支持 function calling或者tools参数格式不对。换成gpt-4o或gpt-4o-mini再试同时确认tool_choice设为auto。验证成功后你可以把handle_weather换成真实 API把 Server 数量增加Host 会自动注册新工具Client 的决策逻辑不用改。这就是三角色架构的价值扩展能力只需要加 Server决策层和网关层保持稳定。实测下来整条链路从零到跑通大约 20 分钟主要时间花在环境变量和路径配置上。建议把TAOTOKEN_API_KEY、TAOTOKEN_BASE_URL、TAOTOKEN_MODEL三个变量写进.env文件用python-dotenv加载避免每次开终端都要 export。5. 常见报错排查401、local proxy failed、reading choices、OAuth跑 MCP 链路时报错信息往往指向不同层按层排查效率最高。下面是我踩过的几个典型错误和对应解法。401 Unauthorized这是认证层问题说明 Key 无效或没传对。检查三件事TAOTOKEN_API_KEY环境变量是否真的被进程读到在代码里 print 一下长度不要 print 完整 KeyBase URL 是否写成https://taotoken.net/api而不是带/v1或其他路径Key 是否在控制台被禁用或删除。如果 Host 拉起 Server 时用了env透传确认mcp_config.json里的${TAOTOKEN_API_KEY}被正确替换有些 shell 不展开 JSON 里的变量需要在 Host 代码里手动替换。local proxy failed这个报错通常出现在网络层说明请求没到达 TaoToken 的 API 地址。检查本机网络是否能访问https://taotoken.net/api用curl -I https://taotoken.net/api看返回状态。如果公司网络有出口限制确认该域名在允许列表里。另外检查是否误设了HTTP_PROXY或HTTPS_PROXY环境变量这些变量会让 SDK 走本地代理导致连接失败。清掉这两个变量再试。reading choices of undefined这是响应解析层问题说明 SDK 拿到的响应结构不符合预期。常见原因是 Base URL 配错请求打到了非 OpenAI 兼容的端点返回了 HTML 或错误 JSON。确认base_url是https://taotoken.net/api且没有多余路径。另一个原因是模型 ID 写错服务端返回了错误对象而不是 completion 对象。在代码里加一层判断response client.chat.completions.create(...) if not response.choices: print(响应异常:, response) return这样能看到实际返回内容快速定位是模型名错还是通道错。OAuth 相关报错如果你用 Claude Code 或 Cline 这类工具它们可能走 OAuth 流程而不是 API Key。报错形如OAuth token expired或invalid_grant。这种情况下不要混用 OAuth 和 API Key二选一。用 TaoToken 的 API Key 模式时在工具的配置里选择API Key认证方式填入 Key 和 Base URL不要走 OAuth 登录。如果工具强制 OAuth检查是否有自定义端点选项把端点指向https://taotoken.net/api。工具调用返回空Client 决策正确但 Host 拿不到结果通常是 Server 进程的 stdout 缓冲问题。stdio 模式下Server 每次写响应后必须flush()否则 Host 的readline()会一直阻塞。检查 Server 代码里sys.stdout.flush()是否在每次 write 后调用。另一个可能是 Server 进程崩溃了检查stderr输出把stderrsubprocess.PIPE改成stderrNone让错误直接打印到终端。模型不调用工具Client 返回direct_response而不是call_tool说明模型没触发 function calling。检查tools参数的 JSON Schema 是否合法required字段是否和properties对应。有些模型对工具描述敏感把description写得更具体比如获取指定城市的当前天气情况包括温度和湿度能提高触发率。如果还是不行换gpt-4o试试它的 function calling 稳定性更好。排查时建议按Server → Host → Client → 通道的顺序逐层验证每层单独跑通再串联。这样报错时能快速缩小范围不用在整条链路里猜。三角色架构的好处在这里也体现出来每层职责单一排查目标明确。6. 从三角色到生产MCP 接入的长期实践把最小链路跑通只是起点真正要在项目里用起来还需要考虑几件事。第一是 Server 的复用性把每个领域能力封装成独立 Server比如数据库 Server、代码仓库 Server、监控 ServerHost 统一注册Client 按需决策。这样新增能力不用改 Client 代码符合开闭原则。第二是安全策略的落地。Host 层要做的不只是转发还要加权限控制、审计日志、输入输出过滤。比如在call_tool里加一层白名单校验只允许特定工具被调用在转发前记录调用者、时间、参数在返回后对敏感字段做脱敏。这些逻辑集中在 Host 一处比散落在各个 Server 里好维护得多。第三是通道的稳定性。TaoToken 作为统一 API 通道好处是 Key 和 Base URL 集中管理切换模型或调整配额只改一处。长期编码和 Agent 场景如果调用量大可以关注 Coding Plan 的配额方案https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面有各语言 SDK 的配置示例。第四是调试工具的准备。模型对话页面可以用来单独验证模型是否正常响应https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。当 Client 决策异常时先在对话页面用同样的 prompt 测一下能快速判断是模型问题还是代码问题。API Keys 管理页面用来轮换 Keyhttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。如果你用 Claude Code 做开发它的 MCP 配置和 Anthropic 的接入方式可以参考https://taotoken.net/claude-code?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。注意 Claude Code 的配置里 Base URL 同样指向https://taotoken.net/apiModel ID 按实际使用的模型填Key 用环境变量引用。最后一点经验三角色架构的价值不在于能连上工具而在于安全、可控、可审计地连上工具。Client 直连 Server 在 demo 里能跑但生产环境里 Host 这一层不能省。把 Host 当成基础设施来对待像重视数据库和 API 网关一样重视它的配置和监控整条链路才能长期稳定运行。