1. 从意图到执行MCP 到底在解决什么问题很多人第一次接触 MCP 时会把它理解成“给大模型装插件”。这个说法不算错但容易让人忽略真正关键的部分模型本身并不会直接操作系统、读文件或发请求它做的只是把一句自然语言需求翻译成“调用哪个工具、传什么参数”的结构化指令。MCPModel Context Protocol要解决的就是把这套翻译结果稳定地送到一个可执行的服务端再把结果原样带回来。举个具体场景。你对 AI 说“帮我算一下 2 加 3然后给张三写一句友好的问候”。模型不会自己去算也不会自己拼字符串它会先看当前连接的服务端暴露了哪些能力有没有add工具、有没有greeting://{name}这样的资源、有没有greet_user提示模板。确认之后它生成类似tools/call的请求参数是{a:2,b:3}服务端执行完返回5模型再基于这个结果继续规划下一步。这条链路里客户端和服务端之间要完成一次标准的生命周期握手客户端先发initialize协商协议版本和能力服务端返回自身信息客户端再发notifications/initialized进入正常运行阶段。之后客户端通过tools/list、resources/list、prompts/list拉取能力目录必要时监听list_changed通知保持目录更新。模型拿到目录后才能形成可执行计划。所以 MCP 的价值不在于“让模型变聪明”而在于把模型的意图转化成可复现、可审计、可远程调用的执行路径。本地单机跑 stdio 就像装了个本机插件稳定低延迟但一旦你要给多个客户端复用、要接入 Codex 这类支持 URL 的工具就必须把服务端变成一个有明确地址的 Streamable HTTP 端点。这也是本篇要打通的核心链路用 FastMCP 写服务用 Streamable HTTP 暴露接口再用 TaoToken 统一管理模型调用凭证让整条部署链路可复现。如果你之前只在本机用 stdio 跑过 demo这一篇会带你把它推到“有 URL、能被远程客户端调用、能排查报错”的状态。下面从凭证准备开始一步步来。2. TaoToken 前置准备统一 Key 与 API 通道在把 MCP 服务暴露成 HTTP 端点之前先要把模型调用的凭证问题解决掉。原因很直接MCP 服务端本身只负责执行工具但很多实际场景里服务端内部或调用它的客户端需要访问大模型能力。如果每个客户端、每个环境都各自维护一套 Key很快就会乱掉。TaoToken 在这里的作用就是提供一个统一的 API 通道把模型调用凭证收敛到一处管理。先明确几个地址后面配置会反复用到。官网入口是https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 基础地址是https://taotoken.net/api这个不加 UTM 参数。模型对话页面在https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewriteCoding Plan 在https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite控制台在https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteAPI Keys 管理在https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite。操作顺序建议这样先到控制台确认账号状态然后进 API Keys 页面创建一个新的 Key。创建时给它起一个能区分用途的名字比如mcp-fastmcp-demo方便后面在多个环境里对照。Key 生成后只显示一次复制下来存到本地环境变量里不要直接写进会提交到 Git 的代码。拿到 Key 之后你需要确认两件事Base URL 用https://taotoken.net/apiModel ID 用你实际要调用的模型标识。这两个值加上 Key就是后面所有配置的“三件套”。很多接入失败的问题追根到底就是这三者里有一个写错了或者 Base URL 多带了斜杠、少带了路径。这里要提醒一点TaoToken 是统一的 API 通道不是让你绕过什么限制的工具。它的定位是帮你把凭证管理和调用入口标准化方便在 MCP 服务端、Codex、Cline 等多个客户端之间复用同一套配置。理解这一点后面的配置逻辑就顺了。凭证准备好后我们进入 FastMCP 服务端的实际编写。这一部分会给出可直接运行的代码包含工具、资源、提示模板三类能力并以 Streamable HTTP 方式暴露在/mcp路径上。3. 可复制配置FastMCP 服务端与 Streamable HTTP 端点先写服务端代码。下面这份server.py是可直接运行的最小实现包含一个add工具、一个greeting://{name}资源、一个greet_user提示模板并以 Streamable HTTP 暴露在/mcp。# server.py from mcp.server.fastmcp import FastMCP # 推荐Streamable HTTP JSON 响应更适合生产环境 # 若需要状态会话可将 stateless_http 设为 False mcp FastMCP( Demo MCP, json_responseTrue, stateless_httpTrue, streamable_http_path/mcp, ) mcp.tool() def add(a: int, b: int) - int: Add two numbers. return a b mcp.resource(greeting://{name}) def greeting(name: str) - str: Get a personalized greeting. return fHello, {name}! mcp.prompt() def greet_user(name: str, style: str friendly) - str: Generate a greeting prompt. styles { friendly: Please write a warm, friendly greeting, formal: Please write a formal, professional greeting, casual: Please write a casual, relaxed greeting, } return f{styles.get(style, styles[friendly])} for someone named {name}. if __name__ __main__: mcp.run(transportstreamable-http, host127.0.0.1, port8000)这段代码的结构和官方 FastMCP Quickstart 一致。mcp.tool()装饰的函数会出现在tools/list里mcp.resource()对应资源目录mcp.prompt()对应提示模板。streamable_http_path/mcp决定了最终端点地址是http://127.0.0.1:8000/mcp。安装依赖有两种方式选一种即可。用 uv 的话先uv init再执行uv add mcp[cli]用 pip 的话直接pip install mcp[cli]。安装完成后运行python server.py或者用 uv 的话uv run server.py。服务起来之后先确认它能被访问。官方示例建议用 MCP Inspector 连接http://localhost:8000/mcp能看到工具列表就说明服务是活的。这一步很关键因为后面 Codex 配置失败时你要先排除“服务本身没起来”这个可能。接下来是 Codex 客户端的配置。Codex 支持在 CLI 或 IDE 扩展里配置 MCP而且配置共享。有两种方式方式 A 用 CLI 添加codex mcp add my-local-mcp --url http://127.0.0.1:8000/mcp codex mcp list方式 B 直接改~/.codex/config.toml[mcp_servers.my-local-mcp] url http://127.0.0.1:8000/mcp这里要强调“三件套”的完整性。如果你的 MCP 服务端内部还要调用模型那么除了上面的 URL 配置你还需要在服务端或客户端侧配置 Base URL、Key、Model ID。Base URL 是https://taotoken.net/apiKey 是你在 API Keys 页面创建的那串Model ID 按你实际使用的模型填写。三者缺一不可写错任何一个都会在请求阶段报错。配置完成后用codex mcp list确认服务已被识别。如果列表里能看到my-local-mcp说明客户端已经知道去哪里找你的服务了。下一步就是实际发一次请求验证整条链路。4. 验证请求与成功结果curl 调用与日志观察配置写完不代表链路通了必须实际发一次请求。最直接的验证方式是用 curl 打一次 Streamable HTTP 端点。先确认服务在跑然后执行curl -X POST http://127.0.0.1:8000/mcp \ -H Content-Type: application/json \ -H Accept: application/json, text/event-stream \ -d { jsonrpc: 2.0, id: 1, method: initialize, params: { protocolVersion: 2024-11-05, capabilities: {}, clientInfo: {name: curl-test, version: 1.0} } }如果服务正常你会收到一个包含result的 JSON 响应里面有服务端的能力信息。这一步验证的是握手阶段。接着发notifications/initializedcurl -X POST http://127.0.0.1:8000/mcp \ -H Content-Type: application/json \ -H Accept: application/json, text/event-stream \ -d {jsonrpc:2.0,method:notifications/initialized}然后拉取工具列表curl -X POST http://127.0.0.1:8000/mcp \ -H Content-Type: application/json \ -H Accept: application/json, text/event-stream \ -d {jsonrpc:2.0,id:2,method:tools/list,params:{}}正常返回里应该能看到add工具及其 JSON Schema。最后实际调用一次curl -X POST http://127.0.0.1:8000/mcp \ -H Content-Type: application/json \ -H Accept: application/json, text/event-stream \ -d { jsonrpc:2.0, id:3, method:tools/call, params:{name:add,arguments:{a:2,b:3}} }返回结果里content字段应该包含5。到这一步服务端的工具调用链路就验证通过了。再走一遍 Codex 侧的验证。在 Codex 里输入“请使用 MCP 的 add 工具计算 2 3”如果能看到工具调用结果返回说明客户端到服务端的完整链路是通的。这一步相当于 MCP Server 的“毕业考试”模型形成计划、客户端执行tools/call、服务端返回结果、模型据此输出最终答复。观察日志时注意几个点。stdio 模式下stdout 只能输出 MCP 消息日志必须写 stderr否则会污染协议流。Streamable HTTP 模式下服务端提供一个单一 endpoint支持 GET/POST可以用 SSE 或流式响应推送多条消息。如果你在日志里看到请求进来了但没返回先检查Content-Type和Accept头是否带全。验证通过后建议把这次成功的 curl 命令和返回结果记下来作为后续排障的基线。一旦后面改了配置或换了环境可以拿同样的命令快速对比。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth部署链路上最容易卡住的几个报错这里逐个对照。401 Unauthorized。这个通常出现在服务端内部调用模型时。检查三件套Base URL 是不是https://taotoken.net/apiKey 是不是从 API Keys 页面新创建的那串Model ID 是不是写对了。常见错误是 Key 复制时带了空格或者 Base URL 末尾多加了/v1之类的路径。另外确认 Key 没有过期或被删除。local proxy failed。这个报错一般和本地网络配置有关。先确认服务端监听的 host 和 port 是否正确127.0.0.1:8000是否真的在监听。可以用curl http://127.0.0.1:8000/mcp直接测。如果服务没起来先解决启动问题不要急着改客户端配置。reading choices 相关报错。这类错误通常出现在模型返回结构不符合预期时。检查你调用的 Model ID 是否支持当前请求格式以及服务端是否正确解析了返回。如果是流式响应确认Accept头里带了text/event-stream。OAuth 相关报错。如果你在客户端配置里启用了 OAuth 流程但服务端没有对应实现就会卡在授权阶段。对于本地部署的 FastMCP 服务建议先用无认证的 localhost 绑定方式跑通确认链路没问题后再考虑加认证。Streamable HTTP 的生产部署要求做 Origin 校验、尽量绑定 localhost 并启用认证但这些是上线前的加固步骤不是跑通 demo 的前提。还有一个高频问题Codex 配置了 URL 但codex mcp list里看不到。先确认~/.codex/config.toml的路径和格式正确TOML 对缩进和引号敏感。用 CLI 方式codex mcp add添加后再codex mcp list确认。如果还是不行检查 Codex 版本是否支持 MCP 配置。排障的核心思路是分层先确认服务端活着再确认客户端能连上最后确认模型调用凭证正确。每一层都用最小请求验证不要跳步。6. 把链路固定下来从 demo 到可复用部署跑通一次之后接下来要做的是把这条链路固定成可复用的形态。几个实用建议。第一把服务端配置和凭证分离。server.py里不要硬编码 Key用环境变量读取。这样换环境时只改变量不动代码。第二把 Codex 的config.toml片段和 curl 验证命令一起放进项目文档。下次换机器或换人接手时照着文档走一遍就能复现。第三Streamable HTTP 端点上线前确认绑定的是 localhost 或内网地址加上 Origin 校验。如果确实需要远程访问再考虑认证层不要一上来就暴露公网。第四模型调用统一走 TaoToken 的 API 通道Base URL 固定为https://taotoken.net/apiKey 在 API Keys 页面集中管理。这样多个 MCP 服务、多个客户端可以复用同一套凭证排查问题时也只需要看一个地方。如果你后面要长期跑编码类或 Agent 类任务可以了解下 Coding Plan 的用法如果只是想先验证模型对话效果模型对话页面可以直接试。接入细节都在接入文档里遇到配置问题对照文档比反复试错快得多。整条链路的核心其实就三件事FastMCP 把能力封装成工具、资源和提示模板Streamable HTTP 把它变成一个可访问的 URLTaoToken 把模型调用凭证收敛成统一入口。把这三件事各自验证通过再串起来部署就不再是靠运气的操作了。
