1. 从零理解 MCP 本地服务stdio 与 sse 到底差在哪MCPModel Context Protocol是让大模型调用外部工具的通信协议你可以把它理解成「AI 世界的 USB 接口」——只要按协议把服务端写好任何支持 MCP 的客户端都能即插即用。而自定义 MCP 本地服务就是你自己写一个跑在本机的工具进程让 AI 通过它完成官方工具做不到的个性化计算、数据查询或流程编排。很多人第一次接触 MCP 会卡在传输模式的选择上stdio 和 sse 到底该用哪个简单说stdio 走标准输入输出服务端和客户端在同一台机器上通过管道通信启动快、零网络配置适合本地单机调试sse 走 HTTP 长连接服务端监听端口客户端通过 URL 接入适合多客户端共享、跨进程甚至跨设备调用。两者代码逻辑几乎一样差别只在启动参数和客户端配置。这篇教程面向想自己动手搭 MCP 服务的开发者尤其是用 AI 编程工具做个性化扩展的人。我会从环境准备讲到代码编写再分别演示 stdio 和 sse 两种模式的完整配置最后用 TaoToken 统一通道把 Key 和 API 管起来让 AI 工具调用更省心。全程命令可直接复制踩过的坑我也会标出来。核心检索词先明确MCP 本地服务、stdio 传输、sse 传输、AI 工具个性化调用、TaoToken 统一通道。下面每一步都围绕这几个点展开你跟着做就能跑通。2. 环境准备与 TaoToken 统一通道前置配置动手写代码前先把工具链和 API 通道准备好。MCP 服务本身不依赖大模型但你要让 AI 真正调用它就得有一个能发请求的模型通道。TaoToken 在这里的作用是统一管理 Key 和 API 地址避免你在多个客户端里反复填不同厂商的配置。2.1 安装 uv 包管理工具uv 是新一代 Python 包管理器比 pip 快很多还能统一管理 Python 版本。Windows 下用 PowerShell 执行powershell -ExecutionPolicy Bypass -c irm https://github.com/astral-sh/uv/releases/download/0.9.27/uv-installer.ps1 | iex装完验证uv --version能输出版本号就说明环境变量已自动配好。macOS 或 Linux 用户可以用curl -LsSf https://astral.sh/uv/install.sh | sh逻辑一样。2.2 安装 Python 3.13 并初始化项目MCP SDK 对 Python 3.13 兼容性更好用 uv 一键装uv python install 3.13 uv python list然后建项目目录。我习惯按「根目录 - 项目目录」分层方便后面放多个 MCP 服务mkdir -p D:\AiMcpProject\mcp_server cd D:\AiMcpProject\mcp_server uv init . -p 3.13初始化成功会提示Initialized project mcp-server。接着装 MCP SDKuv add mcp[cli]如果环境特殊用 pip 也行pip install mcp[cli]但 uv 更快且不会有依赖冲突。2.3 配置 TaoToken 统一 Key 与 API 通道TaoToken 的 API 地址是https://taotoken.net/api官网入口在https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。你需要先在控制台创建一个 API Key然后把它作为环境变量注入到 MCP 服务或客户端里。推荐做法是在项目根目录建一个.env文件不要提交到 git内容形如TAOTOKEN_API_KEYsk-你的实际Key TAOTOKEN_BASE_URLhttps://taotoken.net/api然后在 MCP 服务代码里用os.getenv读取。这样 stdio 和 sse 两种模式都能复用同一套 Key切换客户端时不用改代码。如果你用的是 Claude Code 或 Cline 这类工具它们的配置文件里也要填 Base URL、Key、Model ID 三件套后面章节会给出具体片段。注意Key 只存在本地环境变量或客户端配置里不要硬编码进main.py提交到公开仓库。3. 编写 MCP 服务代码stdio 与 sse 可复制配置这一章是核心我会给出完整的main.py然后分别说明 stdio 和 sse 的启动差异。代码里故意把加法结果「多加 1」这样联调时一眼就能看出 AI 是不是真的调用了你的服务而不是模型自己算的。3.1 完整服务端代码from mcp.server import FastMCP import os # 初始化 MCP 服务Demo 是服务标识客户端里会显示这个名字 mcp FastMCP(Demo) # 1. 自定义加法工具ab 后多加 1用于验证服务是否被真实调用 mcp.tool() def add(a: int, b: int) - int: Add two numbers return a b 1 # 2. 动态问候资源通过自定义协议返回个性化内容 mcp.resource(greeting://{name}) def get_greeting(name: str) - str: Get a personalized greeting return fHello, {name}! # 3. 多风格问候提示词为 AI 生成指定风格的问候语提供模板 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__: # 默认 stdio 模式切 sse 时改下面两行 mcp.settings.port 8001 mcp.run(transportstdio)三个装饰器的含义mcp.tool()标记可被 AI 直接调用的函数mcp.resource()标记资源通过自定义 URI 协议访问mcp.prompt()标记提示词模板给 AI 生成内容时提供风格参考。3.2 stdio 模式配置stdio 模式下服务端通过标准输入输出和客户端通信不需要监听端口。启动就是mcp.run(transportstdio)。客户端配置通常是一个 JSON 片段以 Cline 或 Claude Code 的 MCP 配置为例{ mcpServers: { mcp-stdio-add: { command: python, args: [ D:\\AiMcpProject\\mcp_server\\main.py ], env: { TAOTOKEN_API_KEY: sk-你的实际Key, TAOTOKEN_BASE_URL: https://taotoken.net/api } } } }关键点command是启动命令args是脚本路径env里注入 TaoToken 的 Key 和 Base URL。Windows 路径要用双反斜杠或正斜杠。stdio 的优点是启动即用缺点是只能本机、单客户端。3.3 sse 模式配置sse 模式需要监听端口把main.py末尾改成if __name__ __main__: mcp.settings.port 8001 mcp.run(transportsse)启动后服务端会在http://localhost:8001/sse提供 SSE 端点。客户端配置改成 URL 形式{ mcpServers: { mcp-sse-add: { url: http://localhost:8001/sse, env: { TAOTOKEN_API_KEY: sk-你的实际Key, TAOTOKEN_BASE_URL: https://taotoken.net/api } } } }sse 适合多客户端共享同一个服务比如你同时用 Cherry Studio 和另一个 IDE 插件都连同一个端口即可。代价是要管端口占用和防火墙。3.4 两种模式对照维度stdiosse通信方式标准输入输出管道HTTP 长连接是否监听端口否是默认 8001适用场景本地单机调试多客户端共享客户端配置command argsurl启动速度快略慢需等端口就绪跨设备不支持支持需网络可达选哪个取决于你的使用方式自己一个人调试用 stdio团队或多工具共用选 sse。4. 连通性验证从请求到成功结果代码写完不算完得验证 AI 真的调用了你的服务。这一步我会用「13 等于多少」这个经典测试因为正常加法是 4而我们的服务返回 5结果对不上就说明没走你的 MCP。4.1 stdio 模式验证先确认客户端里 MCP 服务已加载。以支持 MCP 的客户端为例添加完上面的 JSON 配置后重启客户端在工具列表里应该能看到mcp-stdio-add和它暴露的add工具。然后输入使用 mcp-stdio-add 工具计算 13 的和如果返回 5说明调用成功。返回 4 则说明模型自己算了没走 MCP。这时候检查三点服务是否真的启动、客户端配置路径是否正确、工具名是否拼对。4.2 sse 模式验证先手动启动服务端cd D:\AiMcpProject\mcp_server uv run main.py看到类似Uvicorn running on http://0.0.0.0:8001的输出就说明端口起来了。然后用 curl 探一下 SSE 端点curl -N http://localhost:8001/sse能持续收到事件流就说明服务正常。接着在客户端里配置url为http://localhost:8001/sse同样输入「使用 mcp-sse-add 工具计算 13 的和」返回 5 即成功。Python 端会打印出接口请求日志方便你确认请求真的到达了服务端。4.3 用 TaoToken 模型对话做二次确认如果你想确认模型通道也正常可以打开 TaoToken 的模型对话页面https://taotoken.net/api对话入口在控制台内发一条普通消息看是否正常返回。模型对话能通说明 Key 和 Base URL 没问题MCP 工具能返回 5说明本地服务没问题。两者都通整条链路就打通了。提示验证阶段建议先用小请求量测试确认无误再接入正式工作流。5. 常见报错排查401、local proxy failed、reading choices、OAuth搭 MCP 服务最容易在配置和网络环节翻车下面这几个报错我基本都遇到过按顺序排查能省不少时间。5.1 401 Unauthorized这是 Key 问题。先检查.env或客户端env里的TAOTOKEN_API_KEY是否填对有没有多余空格或换行。然后确认 Base URL 是https://taotoken.net/api不要漏掉/api或写成带 UTM 的官网地址。如果 Key 是在控制台新建的确认它没有被禁用或过期。401 基本就是「Key 不对或没带上」跟 MCP 代码无关。5.2 local proxy failed这个报错通常出现在客户端尝试连接本地 MCP 服务时。stdio 模式下检查command和args路径是否正确Windows 路径分隔符是否转义sse 模式下检查端口 8001 是否被占用用netstat -ano | findstr 8001看一下。如果服务端没启动客户端自然连不上。另外确认 Python 解释器路径是 uv 环境里的那个而不是系统里另一个版本。5.3 reading choices 相关报错这类报错一般出现在模型返回结构不符合预期时常见原因是 Base URL 配错导致请求打到了非预期端点或者 Model ID 填了一个不存在的模型。检查客户端里 Model ID 是否与 TaoToken 控制台里可用的模型一致。如果用的是 Claude Code 或 Codex 这类工具它们的auth.json或settings.json里要同时写全 Base URL、Key、Model ID 三件套缺一个都可能报解析错误。5.4 OAuth 相关报错部分客户端在首次连接时会走 OAuth 流程如果本地 MCP 服务没有实现对应端点就会失败。解决办法是确认客户端配置里用的是 stdio 或 sse 直连模式而不是需要 OAuth 的托管模式。如果你用的是 Claude Code 的 Anthropic 接入方式确保配置的是本地 MCP 服务地址而非云端 OAuth 地址。遇到 OAuth 报错先看客户端文档里该模式是否需要额外授权步骤。5.5 工具调用返回 4 而不是 5这不是报错但很常见。说明模型没走你的 MCP而是自己算了。排查客户端工具列表里有没有你的服务、工具名是否被正确识别、提示词里是否明确指定了工具名。有时候模型会「偷懒」你需要在提示里强调「必须使用 mcp-stdio-add 工具」。6. 接入 TaoToken 统一通道让 AI 工具个性化调用服务跑通后最后一步是把 TaoToken 统一通道接进来让 Key 和 API 管理更省心。TaoToken 的价值在于一个 Key 走通多个客户端不用每个工具单独配。6.1 统一 Key 的注入方式前面已经在 MCP 配置的env里注入了TAOTOKEN_API_KEY和TAOTOKEN_BASE_URL。如果你有多个 MCP 服务可以把这两个变量放到系统环境变量里所有服务共享。Windows 下用setx TAOTOKEN_API_KEY sk-...macOS/Linux 写进~/.zshrc或~/.bashrc。6.2 在 Claude Code 中接入Claude Code 的 MCP 配置通常在~/.claude/settings.json或项目级配置里。三件套写法{ mcpServers: { mcp-stdio-add: { command: python, args: [D:\\AiMcpProject\\mcp_server\\main.py], env: { TAOTOKEN_API_KEY: sk-你的实际Key, TAOTOKEN_BASE_URL: https://taotoken.net/api } } } }如果你用的是 Anthropic 兼容接入Base URL 填https://taotoken.net/apiModel ID 填控制台里可用的模型名。Claude Code 的 OAuth 模式不适用于本地 MCP直连即可。6.3 在 Cline MCP 中接入Cline 的 MCP 配置在设置面板的 MCP Servers 里格式和上面类似。stdio 用commandargssse 用url。Cline 支持同时挂多个 MCP 服务你可以把 stdio 和 sse 两个都配上按场景切换。6.4 长期编码与 Agent 场景如果你打算把 MCP 服务用于长期编码或 Agent 工作流建议走 Coding Plan 通道配合 TaoToken 的 API Key 做统一鉴权。这样多个 Agent 共享同一套 Key额度和管理都在一个地方。具体入口在控制台的 Coding Plan 页面配置时同样填 Base URL、Key、Model ID 三件套。6.5 验证整条链路最后做一次端到端验证启动 sse 服务端客户端连上输入「使用 mcp-sse-add 工具计算 13 的和」返回 5再打开模型对话页面发一条普通消息正常返回。两条都通说明 MCP 本地服务 TaoToken 统一通道全部就绪。之后你要加新工具只需在main.py里加一个mcp.tool()函数重启服务即可Key 和通道不用动。到这里stdio 和 sse 两种模式的 MCP 本地服务就完整跑通了。实际用下来stdio 适合快速迭代sse 适合多端共享TaoToken 统一通道则帮你把 Key 管理这件事从「每个客户端填一遍」变成「一处配置处处可用」。