1. 从一次“工具调用失败”说起MCP 到底解决什么问题如果你最近在折腾 LLM 应用大概率遇到过这种场景想让模型查一下数据库、算个复杂公式、调一下公司内部接口结果发现每个模型厂商、每个客户端都有自己的“函数调用”格式换一个 Host 就得重写一遍适配层。MCPModel Context Protocol模型上下文协议就是冲着这个痛点来的——它把“大模型调用外部工具”这件事标准化了你可以把它理解成专为 LLM 交互设计的 Web API 规范。MCP 的核心价值在于统一了大模型调用工具的方法为【大模型】与【外部数据和工具】的【无缝集成】提供了标准化协议和平台。一个 MCP Server 通常暴露三类能力Resources 负责把数据加载进模型上下文类似 GET 端点Tools 负责执行代码或产生副作用类似 POST 端点Prompts 则是可复用的交互模板。Host 是客户端软件比如 Cursor、Cherry StudioServer 是各种工具提供的 MCP 接口每个 Server 对应 Host 里的一个 Client 做一对一通信。传输机制上目前主流有三种Stdio 通过本地进程间通信客户端以子进程形式启动服务器双方用 stdin/stdout 交换 JSON-RPC 消息每条消息以换行符分隔SSE 基于 HTTP 长连接需要 /sse 和 /messages 两个端点正在逐步淘汰Streamable HTTP 是官方推荐的替代方案完全基于标准 HTTP所有消息走 /message 端点服务器可按需把普通请求升级为 SSE 流。对初次接触的 Python 开发者来说Stdio 是最容易上手、也最适合本地隐私数据处理的入口本文就带你用 uv Python 从零搭一个 Stdio MCP Server并接入 TaoToken 完成模型侧联调。2. 前置准备uv 环境与 TaoToken 统一 Key 通道在写代码之前先把两件事准备好Python 项目环境和模型调用通道。环境这块我强烈建议用 uv它比 pip venv 快得多而且能自动管理 Python 版本和依赖锁定对 MCP 这种需要频繁试错的场景特别友好。TaoToken 在这里扮演的角色是“统一 Key / API 通道”。你不需要为每个模型厂商单独申请 Key、单独记 Base URL而是通过一个统一的 API 入口去调用不同模型这对 MCP 联调阶段特别省事——Server 写好后换模型只改一个配置项。你需要先去控制台创建一个 API Key地址是 https://taotoken.net/api-keys 创建完记得复制保存后面配置里要用。API 的基础地址是 https://taotoken.net/api 注意这个地址不带任何查询参数直接作为 base_url 使用。如果你还没注册可以先从官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 进去了解整体能力。整个前置准备大概五分钟装 uv、建项目、拿 Key然后就可以进入编码环节了。3. 可复制配置用 uv 初始化项目并编写 Stdio Server先建目录并初始化。打开终端执行下面这几条命令uv 会自动帮你把项目骨架和虚拟环境都准备好mkdir myMCPServer cd myMCPServer uv init . uv add mcp[cli]uv init .会在当前目录生成 pyproject.toml 和基础结构uv add mcp[cli]把 MCP 官方 SDK 加进依赖。生成的 pyproject.toml 大致长这样你可以直接对照检查[project] name mymcpserver version 0.1.0 description A demo MCP server requires-python 3.10 dependencies [ mcp[cli], ] [build-system] requires [hatchling] build-backend hatchling.build接下来把 main.py 改成我们的 Server 骨架。这里用 FastMCP 是最省心的写法它把协议细节都封装好了你只需要关心工具函数本身# main.py from mcp.server.fastmcp import FastMCP # 创建 MCP Server 实例名字会显示在客户端里 mcp FastMCP(Demo) mcp.tool() def add(a: int, b: int) - int: Add two numbers return a b mcp.tool() def square(a: int) - int: square one numbers return a * a # 动态 greeting 资源通过 greeting://{name} 访问 mcp.resource(greeting://{name}) def get_greeting(name: str) - str: Get a personalized greeting return fHello, {name}! if __name__ __main__: mcp.run()注意mcp.tool()装饰的函数docstring 会被当作工具描述暴露给模型所以写清楚一点模型才知道什么时候该调用它。mcp.resource则用于把数据以 URI 形式暴露出去客户端可以按需读取。4. 启动与验证mcp dev 调试 TaoToken 联调请求启动调试模式前确认你的 Node 版本满足要求^20.17.0 || 22.9.0因为 MCP Inspector 依赖它。然后运行mcp dev main.py启动成功后终端会打印一个 Inspector 的访问链接点进去在 Connection 面板选择 Stdio确认能连上。连上后你就能在 Tools 标签页看到 add 和 square 两个工具在 Resources 里看到 greeting 资源。这一步是纯本地验证不涉及任何模型调用先把协议层跑通。协议通了之后接 TaoToken 做模型侧联调。核心是把 base_url 指向 https://taotoken.net/api api_key 用你在控制台创建的那把。下面是一个最小调用示例用 OpenAI 兼容的 SDK 风格演示from openai import OpenAI client OpenAI( base_urlhttps://taotoken.net/api, api_key你的_TaoToken_API_Key, ) resp client.chat.completions.create( modelclaude-sonnet-4-5, messages[ {role: user, content: 帮我算一下 12 加 30 等于多少} ], ) print(resp.choices[0].message.content)如果你用的是支持 MCP 的 Host比如 Cherry Studio配置里把 Server 指向你的 main.py 即可command 填 uv 的绝对路径args 填[run, --with, mcp, mcp, run, /你的路径/myMCPServer/main.py]。配置成功后在对话里问“12 加 30 等于多少”模型会调用 add 工具问“9 的平方”会调用 square。但如果你问“2 的立方”模型不会调用工具因为我们的 Server 里根本没提供求立方的方法——这恰好验证了工具调用是严格按 Server 暴露的能力来的不是模型瞎编。想快速验证模型对话效果也可以直接用模型对话页面 https://taotoken.net/models 试一下确认 Key 和通道都正常。5. 本篇常见报错排查报错一mcp: command not found。说明依赖没装进当前环境。确认你在项目目录下执行并且用uv run mcp dev main.py而不是裸mcp dev main.py让 uv 从项目环境里找命令。报错二Inspector 连不上Connection 一直转圈。九成是 Node 版本不对。执行node -v检查低于 20.17 就升级。另外确认 main.py 里mcp.run()没有被其他代码阻塞。报错三模型不调用工具。先看工具 docstring 是否清晰模型靠它判断用途再看 Host 里 Server 是否显示为已连接、工具列表是否加载出来。如果工具列表是空的说明 Server 启动就失败了回到上一步用 Inspector 单独验证。报错四TaoToken 调用返回 401。检查 api_key 是否复制完整、有没有多余空格确认 base_url 是https://taotoken.net/api不要自己拼/v1之类的后缀。如果还是不行去控制台重新生成一把 Key 试试。报错五Stdio 消息解析失败。多半是你在 stdout 里打印了调试信息。Stdio 模式下 stdout 是协议通道任何print都会污染 JSON-RPC 消息。调试信息请走 stderr或者用 logging 写到文件。6. 下一步把 MCP 接进你的真实工作流Server 跑通只是起点。接下来你可以把真实的业务逻辑塞进mcp.tool()里比如查内部数据库、调公司 API、做文件处理。模型侧继续走 TaoToken 的统一通道换模型、加并发都不用改 Server 代码。如果你打算长期做编码类或 Agent 类项目可以了解一下 Coding Plan https://taotoken.net/coding-plan 它在长会话和工具调用场景下更省心。接入文档在 https://taotoken.net/doc 遇到协议细节可以对照查。整个链路的核心就一句话Server 负责暴露能力TaoToken 负责统一模型通道两边解耦你只管把工具写好。
1. 从一次“工具调用失败”说起MCP 到底解决什么问题如果你最近在折腾 LLM 应用大概率遇到过这种场景想让模型查一下数据库、算个复杂公式、调一下公司内部接口结果发现每个模型厂商、每个客户端都有自己的“函数调用”格式换一个 Host 就得重写一遍适配层。MCPModel Context Protocol模型上下文协议就是冲着这个痛点来的——它把“大模型调用外部工具”这件事标准化了你可以把它理解成专为 LLM 交互设计的 Web API 规范。MCP 的核心价值在于统一了大模型调用工具的方法为【大模型】与【外部数据和工具】的【无缝集成】提供了标准化协议和平台。一个 MCP Server 通常暴露三类能力Resources 负责把数据加载进模型上下文类似 GET 端点Tools 负责执行代码或产生副作用类似 POST 端点Prompts 则是可复用的交互模板。Host 是客户端软件比如 Cursor、Cherry StudioServer 是各种工具提供的 MCP 接口每个 Server 对应 Host 里的一个 Client 做一对一通信。传输机制上目前主流有三种Stdio 通过本地进程间通信客户端以子进程形式启动服务器双方用 stdin/stdout 交换 JSON-RPC 消息每条消息以换行符分隔SSE 基于 HTTP 长连接需要 /sse 和 /messages 两个端点正在逐步淘汰Streamable HTTP 是官方推荐的替代方案完全基于标准 HTTP所有消息走 /message 端点服务器可按需把普通请求升级为 SSE 流。对初次接触的 Python 开发者来说Stdio 是最容易上手、也最适合本地隐私数据处理的入口本文就带你用 uv Python 从零搭一个 Stdio MCP Server并接入 TaoToken 完成模型侧联调。2. 前置准备uv 环境与 TaoToken 统一 Key 通道在写代码之前先把两件事准备好Python 项目环境和模型调用通道。环境这块我强烈建议用 uv它比 pip venv 快得多而且能自动管理 Python 版本和依赖锁定对 MCP 这种需要频繁试错的场景特别友好。TaoToken 在这里扮演的角色是“统一 Key / API 通道”。你不需要为每个模型厂商单独申请 Key、单独记 Base URL而是通过一个统一的 API 入口去调用不同模型这对 MCP 联调阶段特别省事——Server 写好后换模型只改一个配置项。你需要先去控制台创建一个 API Key地址是 https://taotoken.net/api-keys 创建完记得复制保存后面配置里要用。API 的基础地址是 https://taotoken.net/api 注意这个地址不带任何查询参数直接作为 base_url 使用。如果你还没注册可以先从官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 进去了解整体能力。整个前置准备大概五分钟装 uv、建项目、拿 Key然后就可以进入编码环节了。3. 可复制配置用 uv 初始化项目并编写 Stdio Server先建目录并初始化。打开终端执行下面这几条命令uv 会自动帮你把项目骨架和虚拟环境都准备好mkdir myMCPServer cd myMCPServer uv init . uv add mcp[cli]uv init .会在当前目录生成 pyproject.toml 和基础结构uv add mcp[cli]把 MCP 官方 SDK 加进依赖。生成的 pyproject.toml 大致长这样你可以直接对照检查[project] name mymcpserver version 0.1.0 description A demo MCP server requires-python 3.10 dependencies [ mcp[cli], ] [build-system] requires [hatchling] build-backend hatchling.build接下来把 main.py 改成我们的 Server 骨架。这里用 FastMCP 是最省心的写法它把协议细节都封装好了你只需要关心工具函数本身# main.py from mcp.server.fastmcp import FastMCP # 创建 MCP Server 实例名字会显示在客户端里 mcp FastMCP(Demo) mcp.tool() def add(a: int, b: int) - int: Add two numbers return a b mcp.tool() def square(a: int) - int: square one numbers return a * a # 动态 greeting 资源通过 greeting://{name} 访问 mcp.resource(greeting://{name}) def get_greeting(name: str) - str: Get a personalized greeting return fHello, {name}! if __name__ __main__: mcp.run()注意mcp.tool()装饰的函数docstring 会被当作工具描述暴露给模型所以写清楚一点模型才知道什么时候该调用它。mcp.resource则用于把数据以 URI 形式暴露出去客户端可以按需读取。4. 启动与验证mcp dev 调试 TaoToken 联调请求启动调试模式前确认你的 Node 版本满足要求^20.17.0 || 22.9.0因为 MCP Inspector 依赖它。然后运行mcp dev main.py启动成功后终端会打印一个 Inspector 的访问链接点进去在 Connection 面板选择 Stdio确认能连上。连上后你就能在 Tools 标签页看到 add 和 square 两个工具在 Resources 里看到 greeting 资源。这一步是纯本地验证不涉及任何模型调用先把协议层跑通。协议通了之后接 TaoToken 做模型侧联调。核心是把 base_url 指向 https://taotoken.net/api api_key 用你在控制台创建的那把。下面是一个最小调用示例用 OpenAI 兼容的 SDK 风格演示from openai import OpenAI client OpenAI( base_urlhttps://taotoken.net/api, api_key你的_TaoToken_API_Key, ) resp client.chat.completions.create( modelclaude-sonnet-4-5, messages[ {role: user, content: 帮我算一下 12 加 30 等于多少} ], ) print(resp.choices[0].message.content)如果你用的是支持 MCP 的 Host比如 Cherry Studio配置里把 Server 指向你的 main.py 即可command 填 uv 的绝对路径args 填[run, --with, mcp, mcp, run, /你的路径/myMCPServer/main.py]。配置成功后在对话里问“12 加 30 等于多少”模型会调用 add 工具问“9 的平方”会调用 square。但如果你问“2 的立方”模型不会调用工具因为我们的 Server 里根本没提供求立方的方法——这恰好验证了工具调用是严格按 Server 暴露的能力来的不是模型瞎编。想快速验证模型对话效果也可以直接用模型对话页面 https://taotoken.net/models 试一下确认 Key 和通道都正常。5. 本篇常见报错排查报错一mcp: command not found。说明依赖没装进当前环境。确认你在项目目录下执行并且用uv run mcp dev main.py而不是裸mcp dev main.py让 uv 从项目环境里找命令。报错二Inspector 连不上Connection 一直转圈。九成是 Node 版本不对。执行node -v检查低于 20.17 就升级。另外确认 main.py 里mcp.run()没有被其他代码阻塞。报错三模型不调用工具。先看工具 docstring 是否清晰模型靠它判断用途再看 Host 里 Server 是否显示为已连接、工具列表是否加载出来。如果工具列表是空的说明 Server 启动就失败了回到上一步用 Inspector 单独验证。报错四TaoToken 调用返回 401。检查 api_key 是否复制完整、有没有多余空格确认 base_url 是https://taotoken.net/api不要自己拼/v1之类的后缀。如果还是不行去控制台重新生成一把 Key 试试。报错五Stdio 消息解析失败。多半是你在 stdout 里打印了调试信息。Stdio 模式下 stdout 是协议通道任何print都会污染 JSON-RPC 消息。调试信息请走 stderr或者用 logging 写到文件。6. 下一步把 MCP 接进你的真实工作流Server 跑通只是起点。接下来你可以把真实的业务逻辑塞进mcp.tool()里比如查内部数据库、调公司 API、做文件处理。模型侧继续走 TaoToken 的统一通道换模型、加并发都不用改 Server 代码。如果你打算长期做编码类或 Agent 类项目可以了解一下 Coding Plan https://taotoken.net/coding-plan 它在长会话和工具调用场景下更省心。接入文档在 https://taotoken.net/doc 遇到协议细节可以对照查。整个链路的核心就一句话Server 负责暴露能力TaoToken 负责统一模型通道两边解耦你只管把工具写好。
