1. 为什么本地 AI 服务都爱用 MCP stdio 模式如果你最近在折腾 AI 工具链大概率听过 MCP 这个词。MCP 全称 Model Context Protocol简单说就是一套让大模型能调用外部工具的通信协议。它解决的核心问题是模型本身只会生成文本但你想让它查数据库、读文件、调接口就得有个标准化的“插槽”把工具接进去。MCP 就是这个插槽规范。而 stdio 模式是 MCP 里最适合本地开发的一种通信方式。它不走网络端口不依赖 HTTP 服务直接通过进程的标准输入stdin和标准输出stdout来收发数据。你可以把它想象成一条“魔法管道”客户端把 JSON 请求塞进管道一头服务端从另一头读出来执行再把结果写回去。整个过程没有网络握手、没有端口占用、没有跨域问题启动即用。这套模式适合谁三类人最该掌握。第一类是 Python/Java 开发者想给自己的 AI 应用加工具能力但不想先搭一套 HTTP 服务第二类是本地调试党需要快速验证一个工具逻辑对不对stdio 模式改完代码重启进程就能测第三类是 Agent 开发者很多编码助手比如 Claude Code、Cline默认就用 stdio 方式拉起本地 MCP 服务你不懂这个模式配置都写不明白。我实测下来stdio 模式最大的好处是“零网络配置”。你不需要关心端口冲突、防火墙、内网穿透这些破事一个命令拉起进程客户端就能调用。代价是它只能在本机跑跨机器就得换 SSE 或 HTTP 模式。但对“从零搭建首个 AI 服务”这个目标来说stdio 是最短路径。这篇文章会带你走完三步先把服务端代码写出来再配好客户端调用最后通过 TaoToken 统一 Key 和 API 通道把模型接进来跑通一个真正可用的 MCP stdio 服务。全程可复制踩过的坑我也会标出来。2. TaoToken 前置准备统一 Key 与 API 通道在写代码之前先把“模型从哪来”这件事解决掉。MCP 服务本身只是工具的执行者真正决定调用哪个工具、怎么调用的是背后的大模型。所以你需要一个能稳定访问模型的 API 通道。TaoToken 在这里扮演的角色就是统一入口一个 Key 打通多家模型Base URL 固定省得你在代码里到处改配置。先注册并拿到 API Key。打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后在控制台里创建 Key。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 进去之后左侧菜单找 API Keys点新建复制那串 sk- 开头的字符串。这个 Key 只显示一次丢了就重新建一个。拿到 Key 之后记住两个固定值Base URL 是 https://taotoken.net/api 这个地址不加任何 UTM 参数直接写进代码。模型 ID 根据你用的场景选做工具调用建议用支持 function calling 的模型比如 claude 系列或 gpt 系列具体在模型对话页面能看到当前可用的列表https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。这里有个关键点MCP stdio 服务端本身不直接调模型它是被客户端比如 Claude Code、Cline、或者你自己写的 Agent拉起来的。所以 TaoToken 的 Key 和 Base URL 要配在客户端那一侧而不是服务端代码里。服务端只负责暴露工具客户端负责把工具描述发给模型、解析模型的调用意图、再把请求转发给 stdio 服务。这个分工一定要搞清楚否则你会把 Key 写错地方。如果你用的是 Claude Code 这类编码助手它内部已经集成了 MCP 客户端能力你只需要在它的配置文件里声明“我要启动哪个 stdio 服务”。而模型通道则通过环境变量注入。下面给一个通用的环境变量写法Python 和 Java 都适用export TAOTOKEN_API_KEYsk-你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api export TAOTOKEN_MODELclaude-3-5-sonnetWindows 下用set或者直接在系统环境变量里加。配好之后客户端启动时会读取这些变量把模型请求发到 TaoToken 的通道上。这样你换模型只改一个环境变量不用动服务端代码。另外提醒一句TaoToken 的 API 通道是标准 OpenAI 兼容格式所以任何支持自定义 Base URL 的客户端都能接。如果你后面要写自己的 Agent 循环直接用 openai 官方 SDK把 base_url 指向 https://taotoken.net/api 就行。这一步做完模型侧就通了接下来专心搞 stdio 服务端。3. 可复制配置Python 与 Java 的 stdio 服务端这一节是重头戏直接给可复制的代码和配置。先讲 Python因为 MCP 官方 SDK 对 Python 支持最完整上手最快。再讲 Java用 Solon-MCP 框架适合已经在 JVM 生态里的团队。3.1 Python 版用 uv 初始化并写一个搜索工具先建项目。我习惯用 uv比 pip 快很多而且虚拟环境管理干净uv init mcp_stdio_demo cd mcp_stdio_demo uv venv .venv source .venv/bin/activate uv add mcp[cli] httpxWindows 激活命令换成.venv\Scripts\activate.bat。装完之后项目结构大概是mcp_stdio_demo/ ├── .venv/ ├── pyproject.toml └── mcp_stdio_demo/在mcp_stdio_demo/目录下新建web_search.py内容如下import httpx from mcp.server import FastMCP app FastMCP(web-search) app.tool(description执行网络搜索并返回结果) def search_web(query: str) - str: 通过搜索引擎获取实时信息 with httpx.Client(timeout10.0) as client: response client.get( https://api.example.com/search, params{q: query} ) response.raise_for_status() return response.text if __name__ __main__: app.run(transportstdio)注意最后一行app.run(transportstdio)这是显式声明用 stdio 模式启动。如果你不写某些版本默认可能是 SSE客户端就连不上。FastMCP(web-search)里的名字是服务标识客户端配置里要对应。再写一个计算器工具方便测试app.tool(description将两个数字相加) def add(a: float, b: float) - float: return a b app.tool(description安全除法除数为零时抛异常) def safe_divide(a: float, b: float) - float: if b 0: raise ValueError(除数不能为零) return a / b启动命令就是python web_search.py。控制台会打印类似MCP Server web-search started in stdio mode的日志。这时候进程会挂起等待 stdin 输入这是正常的别以为卡死了。3.2 Java 版Solon-MCP 的 stdio 注解Java 这边用 Solon-MCPMaven 依赖dependency groupIdorg.noear/groupId artifactIdsolon-mcp-server/artifactId version2.5.0/version /dependency写一个计算器工具类import org.noear.solon.annotation.McpServerEndpoint; import org.noear.solon.mcp.annotation.ToolMapping; import org.noear.solon.mcp.annotation.Param; import org.noear.solon.mcp.McpChannel; McpServerEndpoint(channel McpChannel.STDIO) public class CalculatorTools { ToolMapping(description 将两个数字相加) public int add(Param int a, Param int b) { return a b; } ToolMapping(description 从第一个数中减去第二个数) public int subtract(Param int a, Param int b) { return a - b; } }关键注解是McpServerEndpoint(channel McpChannel.STDIO)它告诉框架用标准输入输出通信。ToolMapping定义工具description 会被发给模型模型靠它判断该不该调这个工具。打包用mvn clean package启动用java -jar target/calculator.jar。3.3 客户端配置片段把 stdio 服务挂上去服务端写好了得让客户端知道怎么拉起它。以 Claude Code 的配置为例在~/.claude/claude_desktop_config.json或者项目级.mcp.json里写{ mcpServers: { web-search: { command: python, args: [/absolute/path/to/web_search.py], env: { TAOTOKEN_API_KEY: sk-你的Key, TAOTOKEN_BASE_URL: https://taotoken.net/api } } } }三个要素必须齐全command 是可执行程序args 是参数env 是环境变量。路径一定用绝对路径相对路径在客户端拉起子进程时经常找不到文件。如果你用 Cline 或者别的支持 MCP 的编辑器配置结构类似字段名可能叫mcpServers或servers对照文档改一下就行。Java 版的配置把 command 换成javaargs 换成[-jar, /absolute/path/to/calculator.jar]。Model ID 通过环境变量TAOTOKEN_MODEL注入客户端会用它去 TaoToken 通道请求模型。4. 验证请求从终端到客户端的完整跑通配置写完怎么确认真的通了分两层验证先验证 stdio 服务端本身能正确响应再验证客户端能拉起服务并让模型调用工具。4.1 终端直连测试最原始的办法是手动往 stdin 写 JSON。启动 Python 服务后在另一个终端用管道喂数据echo {jsonrpc:2.0,id:1,method:tools/list,params:{}} | python web_search.py正常的话你会看到 stdout 返回工具列表包含search_web、add、safe_divide的描述。如果没有任何输出检查两点一是app.run(transportstdio)有没有写二是日志是不是打到了 stderr 而不是 stdout。MCP 协议规定 stdout 只能放协议数据日志必须走 stderr否则客户端解析会报reading choices之类的错。再测一次工具调用echo {jsonrpc:2.0,id:2,method:tools/call,params:{name:add,arguments:{a:3,b:5}}} | python web_search.py返回里应该能看到result: 8。这一步通了说明服务端逻辑没问题。4.2 客户端侧验证打开 Claude Code 或者你用的 MCP 客户端它会自动读取配置文件并拉起 stdio 进程。你可以在对话里直接说“帮我算一下 3 加 5”模型会识别出该调用add工具客户端把请求转发给 stdio 服务拿到结果再回给模型。整个过程你能在客户端的工具调用日志里看到。如果客户端没反应先看它的 MCP 日志。Claude Code 的日志一般在~/.claude/logs/下找 mcp 相关的文件。常见现象是进程启动了但工具列表为空多半是路径写错或者依赖没装全。另一个坑是 Python 虚拟环境客户端拉起子进程时用的是系统 Python不是你激活的 venv所以要么在 command 里写 venv 里的 python 绝对路径要么把依赖装到系统环境。4.3 通过 TaoToken 通道验证模型调用服务端和客户端都通了之后最后确认模型请求真的走了 TaoToken。在客户端里问一个需要工具的问题比如“搜索一下今天的天气”然后看 TaoToken 控制台的用量记录。控制台地址 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 进去看 API 调用日志应该能看到对应的请求记录模型 ID 和你配的一致。如果控制台没有记录说明客户端根本没发模型请求问题出在客户端的模型配置上不是 MCP 服务的问题。这时候检查TAOTOKEN_BASE_URL有没有写对Key 有没有过期。TaoToken 的 Base URL 是 https://taotoken.net/api 注意结尾没有斜杠有些客户端会自动补/v1你按它的文档来。5. 本篇常见错排查401、local proxy failed 与 reading choices这一节把最容易撞上的报错列出来对照着改。401 Unauthorized这个最直接Key 不对或者没传。检查三处环境变量TAOTOKEN_API_KEY有没有拼错客户端配置里的 env 字段有没有生效Key 是不是在控制台被删了。TaoToken 的 Key 是 sk- 开头复制的时候别带空格。如果用的是 Claude Code它可能读的是系统环境变量而不是配置文件里的 env那就把 Key 加到 shell 的 profile 里。local proxy failed / connection refused这个报错通常出现在客户端试图连接一个 HTTP 代理或者 SSE 端点时。stdio 模式根本不该有网络连接出现这个说明客户端配置写成了 SSE 模式或者 command 指向的程序启动失败。检查配置文件里有没有url字段stdio 模式只认command和args。另外确认 Python 或 Java 的路径是绝对路径子进程启动失败时客户端会报代理错误。reading choices 相关报错完整报错可能是error reading choices: unexpected end of JSON input之类。这是客户端在解析模型返回时失败了。原因通常是模型通道返回了非标准格式或者 stdout 里混入了日志。先确认 TaoToken 的 Base URL 写的是 https://taotoken.net/api 没有多余路径。再检查服务端代码把所有print()改成sys.stderr.write()保证 stdout 干净。OAuth 相关报错如果你用的是需要 OAuth 的客户端可能会看到 token 过期或 scope 不足。MCP stdio 本身不涉及 OAuth这个报错一般来自客户端连接模型通道时的认证。TaoToken 用的是 API Key 认证不需要 OAuth 流程所以检查客户端是不是错误地启用了 OAuth 模式。把认证方式改成 API Key 即可。工具列表为空客户端连上了但看不到工具。检查app.tool装饰器有没有漏写description 是不是空字符串。有些客户端要求 description 非空才展示。Java 版检查ToolMapping的 description 属性。另外确认服务端启动时没有抛异常异常信息会打到 stderr客户端日志里能看到。Codex auth.json 配置问题如果你用 Codex 类工具认证信息在auth.json里。确保里面的 base_url 指向 https://taotoken.net/api api_key 字段填你的 Key。这个文件权限要设好别让其他用户读到。改完重启客户端生效。6. 把 stdio 服务接进你的日常工作流跑通第一个服务之后下一步是把它用起来。几个实用方向把数据库查询封装成工具让模型直接读你的私有数据把文件操作封装进去实现“帮我找一下上周的日志”把内部 API 封装成工具让 Agent 自动调。每个工具就是一个app.tool函数加完重启进程客户端刷新工具列表就能用。如果你要长期跑编码类 Agent建议了解一下 Coding Plan它把模型通道和常用工具链打包好了省得自己一个个配https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各种客户端的配置示例照着抄就行。最后说个我踩过的坑stdio 服务进程的生命周期由客户端管理客户端退出时子进程可能变成僵尸进程。在服务端代码里加个信号处理收到 SIGTERM 时干净退出。Python 里用signal.signal(signal.SIGTERM, handler)Java 里用 shutdown hook。这样反复重启客户端不会攒一堆孤儿进程。现在你手里有一个能跑的 stdio 服务、一套客户端配置、一个统一的模型通道。接下来就是往里加工具加一个测一个慢慢就攒出自己的 AI 工具箱了。