1. 从客户端到服务器端为什么你的第一个 MCP Server 值得认真跑通MCP模型上下文协议服务器端搭建简单说就是写一个能被 AI 客户端调用的本地小程序把外部数据或工具通过标准协议暴露给模型。它适合已经用过 MCP 客户端、知道在配置文件里加个 server 就能让 AI 多一项能力但还没自己写过服务端的开发者。我试过把客户端配置改来改去最后发现真正卡住大家的不是协议本身而是服务端启动后 Key 怎么统一、工具注册有没有生效、调用返回是不是符合预期。这一篇聚焦一件事从零在本地跑通一个可被调用的 MCP Server并且用 TaoToken 的统一 Key 来管理模型侧调用凭证。你会拿到一份可复制的config.toml骨架、一段 TaoToken 统一 Key 配置片段、启动命令以及一次真实的工具调用验证动作。整个过程不需要你理解 JSON-RPC 的每个字段但需要你跟着敲命令、看日志、确认响应。MCP 服务器端和客户端的关系可以类比成「插座」和「插头」。客户端负责把 AI 的请求转成协议消息服务器端负责真正执行函数、读数据、返回结果。你写的 Server 通过 stdio 或 SSE 与客户端通信客户端再把结果交给模型。所以服务端跑通的标准不是「代码没报错」而是「客户端能列出你的工具并且调用后拿到结构化结果」。下面按顺序来先准备 TaoToken 的 Key 和接入信息再写config.toml然后启动服务端最后用一次工具调用确认注册与响应正常。中间会穿插我踩过的坑比如工具没出现在列表里、启动后立刻退出、返回内容被截断。2. TaoToken 前置统一 Key 与接入信息准备TaoToken 在这里的角色是统一管理模型调用的凭证。你不需要在 MCP Server 里硬编码多个平台的 Key而是通过一个统一 Key 去访问模型对话、Coding Plan 等能力。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 这个地址不加 UTM 参数。你需要先拿到一个 API Key。进入控制台创建 Key 的路径是https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 在 API Keys 页面生成https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。生成后复制那串以sk-开头的字符串后面写进环境变量不要直接写进代码提交到仓库。如果你还没决定用哪个模型来驱动工具调用可以先在模型对话页试一下https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。长期做编码或 Agent 场景可以看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite Claude Code 相关配置参考 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 。注意Key 只放在环境变量或本地未提交的配置文件里。MCP Server 的代码仓库里不要出现真实 Key。准备动作就三步注册/登录、创建 API Key、把 Key 导出到当前 shell。导出命令后面会给出。这里先记住两个值TAOTOKEN_API_KEY和TAOTOKEN_BASE_URL前者是你的 Key后者是https://taotoken.net/api。3. 可复制配置config.toml 骨架与 TaoToken 统一 Key 片段MCP 客户端通常用一个配置文件来声明要启动哪些 Server。不同客户端配置文件位置不同但结构类似。下面这份config.toml骨架可以直接复制改掉路径和 Key 引用即可。它声明了一个本地 stdio 类型的 MCP Server并通过环境变量把 TaoToken 的统一 Key 传进去。# config.toml - MCP 客户端配置骨架 [mcp_servers.taotoken_demo] command python args [-m, mcp_server_demo.server] cwd /Users/yourname/projects/mcp_server_demo # 通过环境变量注入 TaoToken 统一 Key避免硬编码 [mcp_servers.taotoken_demo.env] TAOTOKEN_API_KEY ${TAOTOKEN_API_KEY} TAOTOKEN_BASE_URL https://taotoken.net/api MCP_LOG_LEVEL INFO这份配置里几个关键点。command和args决定客户端怎么启动你的服务端进程cwd是工作目录确保模块能被找到。env段把宿主环境里的TAOTOKEN_API_KEY透传给子进程这样服务端代码里用os.getenv(TAOTOKEN_API_KEY)就能拿到不需要在代码里写死。TAOTOKEN_BASE_URL固定为https://taotoken.net/api后续所有模型调用都走这个基址。服务端代码侧你需要一个最小的 FastMCP 实例和一个注册工具。下面这段是服务端入口的骨架重点看 Key 的读取和工具注册方式。# mcp_server_demo/server.py import os import logging from mcp.server.fastmcp import FastMCP logging.basicConfig(levelos.getenv(MCP_LOG_LEVEL, INFO)) logger logging.getLogger(taotoken_demo) # 读取 TaoToken 统一 Key TAOTOKEN_API_KEY os.getenv(TAOTOKEN_API_KEY) TAOTOKEN_BASE_URL os.getenv(TAOTOKEN_BASE_URL, https://taotoken.net/api) if not TAOTOKEN_API_KEY: logger.warning(TAOTOKEN_API_KEY 未设置模型调用类工具将不可用) mcp FastMCP(titleTaoToken Demo Server) mcp.tool() async def echo_tool(text: str) - str: 回显输入文本用于验证服务端注册与响应是否正常。 logger.info(echo_tool 被调用: %s, text) return fecho: {text} mcp.tool() async def token_status() - str: 返回当前 TaoToken 配置状态不发起真实模型请求。 if not TAOTOKEN_API_KEY: return TAOTOKEN_API_KEY 未配置 return fbase_url{TAOTOKEN_BASE_URL}, key_prefix{TAOTOKEN_API_KEY[:6]}*** if __name__ __main__: logger.info(启动 TaoToken Demo MCP Server) mcp.run()依赖安装用 uv 或 pip 都行。用 uv 的话uv add mcp httpx用 pip 的话pip install mcp httpx导出 Key 到当前 shellexport TAOTOKEN_API_KEYsk-你的真实Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api到这里配置和代码骨架就齐了。接下来启动服务端。4. 启动与验证一次工具调用确认注册与响应正常启动 MCP Server 有两种方式。一种是让客户端按config.toml自动拉起另一种是先在终端手动启动确认进程不报错。建议先手动启动观察日志。cd /Users/yourname/projects/mcp_server_demo python -m mcp_server_demo.server如果日志里出现启动 TaoToken Demo MCP Server并且进程保持运行说明 stdio 传输层已经就绪。此时它不会打印更多内容因为 stdio 模式下它在等待客户端通过标准输入发消息。你可以按 CtrlC 退出然后让客户端接管。把config.toml放到客户端要求的路径后重启客户端。客户端启动时会执行command和args把服务端作为子进程拉起。你需要在客户端的工具列表里看到echo_tool和token_status两个工具。如果没看到先看客户端日志里有没有「server failed to start」或「module not found」。验证动作分两步。第一步调用token_status确认 Key 和 base_url 被正确读取。预期返回类似base_urlhttps://taotoken.net/api, key_prefixsk-abc***第二步调用echo_tool传入textmcp server ok。预期返回echo: mcp server ok这两步都通过说明服务端注册、环境变量透传、工具调用链路都正常。如果客户端支持直接发请求也可以用 JSON-RPC 手动验证。下面是一个 stdio 模式下的请求示例你可以用echo管道模拟echo {jsonrpc:2.0,id:1,method:tools/list,params:{}} | python -m mcp_server_demo.server预期输出里会包含echo_tool和token_status的 schema。这一步能帮你确认工具注册没有漏掉。提示如果tools/list返回空数组先检查mcp.tool()装饰器是否加在函数上以及函数是否有类型注解。FastMCP 依赖类型注解生成 schema。5. 本篇常见错排查工具不出现、进程退出、Key 读不到第一个高频问题客户端工具列表里没有你的工具。原因通常是服务端启动失败但客户端没明显报错。排查顺序是手动在终端跑一遍启动命令看有没有 traceback检查cwd是否指向项目根目录检查模块路径是否和args一致。如果手动能跑、客户端跑不了多半是客户端用的 Python 解释器和你的终端不是同一个把command改成绝对路径比如/usr/bin/python3或虚拟环境里的python。第二个问题进程启动后立刻退出。stdio 模式下如果服务端没有进入mcp.run()的等待循环或者标准输入被关闭进程会退出。检查if __name__ __main__:分支是否真的执行了mcp.run()。另外不要在mcp.run()之前做阻塞式输入比如input()那会让客户端以为服务端卡住。第三个问题TAOTOKEN_API_KEY读不到。表现是token_status返回「未配置」。原因是config.toml的env段没有正确透传或者宿主 shell 里没有导出。先确认echo $TAOTOKEN_API_KEY有值再确认config.toml里写的是${TAOTOKEN_API_KEY}。有些客户端不支持${}语法那就改成直接写值但要注意别提交到仓库。第四个问题调用工具返回内容被截断或格式错误。MCP 工具返回值需要是可序列化的。如果你返回了自定义对象客户端可能解析失败。统一返回字符串或字典。日志里如果出现JSON serialization error就是这个问题。第五个问题端口或 SSE 相关。本篇用的是 stdio不涉及端口。如果你改成 SSE 传输需要额外指定 host 和 port并确认客户端用 SSE 方式连接。stdio 和 SSE 的配置字段不同不要混用。第六个问题模型调用类工具超时。如果你在工具里调用 TaoToken 的模型接口记得设置合理的超时和重试。httpx.AsyncClient(timeout30.0)是常见配置。超时后返回结构化错误而不是抛异常这样客户端能拿到可读信息。6. 下一步把统一 Key 用到真实工具与长期编码场景跑通echo_tool和token_status之后你可以把真实逻辑填进去。比如一个查询类工具内部用TAOTOKEN_BASE_URL和TAOTOKEN_API_KEY去调用模型对话能力把结果整理后返回。模型对话入口在 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 接入细节看文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。如果你打算把这个 Server 用在长期编码或 Agent 工作流里建议把 Key 管理收敛到 Coding Plan 的配置方式参考 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。Claude Code 场景的配置片段在 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 。需要新建或轮换 Key 时回到 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 操作。最后留一个实用习惯每次改完服务端代码先在终端手动启动一次用tools/list确认工具注册再让客户端接管。这样能把「代码问题」和「客户端配置问题」分开排查效率会高很多。