1. 从一次“工具调不动”的翻车说起MCP 服务器到底解决什么问题如果你最近在折腾 Claude Desktop大概率遇到过这种场景想让模型读一下本地某个 JSON 文件、查一下数据库、或者调一个内部接口结果它只能干巴巴地告诉你“我无法访问你的本地文件系统”。这不是模型笨而是它和外部世界之间缺了一层标准化的“插线板”。MCP 服务器Model Context Protocol Server就是这块插线板——它把本地能力包装成模型能理解的工具再通过统一协议暴露出去。MCP 全称 Model Context Protocol是一个开放标准核心目标是让大语言模型以“即插即用”的方式访问外部数据源和工具。你可以把它类比成 AI 应用界的 USB-C以前每个模型接每个工具都要写一套私有适配现在只要双方都遵守 MCP就能互相识别。它适合谁适合想把私有数据、内部系统、领域计算能力接进 Claude Desktop、Cursor 这类客户端的开发者也适合想理解 Agent 工具调用底层链路的同学。这篇文章聚焦 MCP 协议原理与 Python 自建服务器全流程面向 Claude Desktop 与 SSE 场景把握手、工具注册、调用链路讲清楚。我会给出可复制的 server 配置、SSE 端点示例和 Claude Desktop 接入片段并附上本地启动与请求验证动作。整个过程中模型侧的 Key 统一走 TaoToken 的接入方式这样你在调试工具调用时不用来回切换多家的凭证省掉一堆环境变量管理的麻烦。先说清楚 MCP 的核心架构不然后面写代码容易懵。它分四层MCP Host 是宿主程序比如 Claude Desktop、CursorMCP Client 是宿主内部的中间件负责管理连接MCP Server 是我们今天要写的轻量服务提供具体功能数据源则是本地文件、数据库或远程 API。一次完整的工具调用链路是这样的用户在 Host 里说“帮我查上海天气”Host 把这句话和已注册的工具清单一起发给模型模型判断需要调用get_weather返回一个结构化的调用请求Client 把它转发给 ServerServer 执行完把结果回传模型再组织成自然语言。理解这条链路你就知道为什么 Server 要声明工具、为什么要握手、为什么 SSE 适合长连接场景。2. 动手前的准备Python 环境、依赖与 TaoToken 统一 Key 接入写 MCP 服务器之前环境要干净。我建议 Python 3.10 以上用 conda 或 venv 隔离别把系统环境搞乱。包管理推荐 uv它比 pip 快很多安装也简单。Windows 下可以执行winget install --idastral-sh.uv -eMac 下用brew install uv。装完之后新建一个项目目录初始化虚拟环境然后安装 MCP 官方 SDK 和几个常用库。uv init mcp-weather-demo cd mcp-weather-demo uv venv uv add mcp[cli] httpx python-dotenv这里mcp[cli]带上了命令行工具方便你本地调试httpx用来发异步 HTTP 请求python-dotenv管理密钥。装完可以用uv run python -c import mcp; print(mcp.__version__)验证一下。接下来是 Key 的问题。MCP 服务器本身不强制绑定某一家模型但你在 Claude Desktop 里调试工具调用时模型请求需要走一个稳定的接入点。我这边统一用 TaoToken 的 Key好处是一个凭证能覆盖对话、编码、Agent 多种场景不用为每个客户端单独配。你可以在控制台创建 API Key地址是 https://taotoken.net/api-keys 创建后复制保存后面写进环境变量。# .env 文件 TAOTOKEN_API_KEYsk-你的key OPENWEATHER_API_KEY你的天气服务key注意MCP Server 和模型接入是两件事Server 负责暴露工具模型负责决定调不调。但为了让 Claude Desktop 里的模型请求走统一入口你需要在客户端侧配置 Base URL 和 Key。TaoToken 的 API 端点是 https://taotoken.net/api 这个地址不加任何查询参数直接作为 OpenAI 兼容的 Base URL 使用。模型 ID 按你实际用的填比如claude-3-5-sonnet或gpt-4o具体以控制台文档为准。如果你用的是 Claude Code 这类编码 Agent长期跑任务建议走 Coding Plan额度更划算接入方式在 https://taotoken.net/coding-plan 有说明。调试阶段先用 API Key 就够了。把这三件套记牢Base URL、Key、Model ID后面配置客户端时一个都不能少。3. 可复制配置FastMCP 写一个天气服务器并暴露 SSE 端点现在写核心代码。MCP 官方提供了 FastMCP 框架用装饰器就能注册工具非常直观。新建weather_server.py内容如下from mcp.server.fastmcp import FastMCP import httpx import os from dotenv import load_dotenv load_dotenv() mcp FastMCP(WeatherService, host0.0.0.0, port9000) mcp.tool() async def get_weather(city: str) - str: 获取指定城市的实时天气数据。 Args: city: 城市名称例如 Shanghai api_key os.getenv(OPENWEATHER_API_KEY) async with httpx.AsyncClient() as client: resp await client.get( https://api.openweathermap.org/data/2.5/weather, params{q: city, appid: api_key, units: metric}, timeout10.0, ) data resp.json() if resp.status_code ! 200: return f查询失败{data.get(message, unknown error)} return f{city} 气温 {data[main][temp]}°C天气 {data[weather][0][description]} if __name__ __main__: mcp.run(transportsse)这段代码有几个关键点。FastMCP初始化时指定 host 和 portSSE 模式下会监听http://0.0.0.0:9000。mcp.tool()装饰器把函数注册成模型可调用的工具函数签名和 docstring 会被序列化成工具描述发给模型——所以 docstring 要写清楚参数含义模型靠它判断怎么传参。transportsse表示用 Server-Sent Events 长连接适合 Claude Desktop 这种需要持续接收工具结果的场景。启动服务器uv run python weather_server.py看到类似Uvicorn running on http://0.0.0.0:9000就说明起来了。SSE 端点默认在/sse消息回传端点在/messages/。你可以先用 curl 探一下curl -N http://127.0.0.1:9000/sse会看到一条event: endpoint的数据里面带着 session 信息说明握手正常。接下来配置 Claude Desktop。找到配置文件Windows 在%APPDATA%\Claude\claude_desktop_config.jsonMac 在~/Library/Application Support/Claude/claude_desktop_config.json。写入{ mcpServers: { weather: { url: http://127.0.0.1:9000/sse } } }如果你希望模型请求也走统一入口可以在同一份配置里加上模型侧的 Base URL 和 Key具体字段以客户端版本为准部分版本通过环境变量注入{ mcpServers: { weather: { url: http://127.0.0.1:9000/sse } }, env: { OPENAI_BASE_URL: https://taotoken.net/api, OPENAI_API_KEY: sk-你的key } }保存后重启 Claude Desktop。注意SSE 模式下 Server 必须先启动客户端才能连上如果你先开客户端再起 Server需要重启客户端触发重连。这是很多人第一次配置时踩的坑。4. 验证请求从握手到工具调用的完整链路实测配置完别急着问问题先确认链路通了。第一步看 Claude Desktop 的工具图标如果配置正确输入框附近会出现一个锤子或插件标志点开能看到weather服务器和get_weather工具。如果没出现说明客户端没连上 Server回到上一步检查端口和 URL。第二步做一次真实调用。在对话框输入“上海现在天气怎么样”模型会先返回一个工具调用请求界面上通常显示“正在使用 get_weather”。几秒后结果回来你会看到类似“上海 气温 25°C天气 多云”的回答。这个过程背后发生了什么Host 把工具清单和用户问题发给模型模型输出结构化调用Client 通过 SSE 把调用转发给 ServerServer 执行 httpx 请求把结果回传模型再润色成自然语言。整条链路跑通说明你的 MCP 服务器可用了。如果你想脱离客户端单独验证 Server可以用 MCP CLIuv run mcp dev weather_server.py这会启动一个调试界面列出所有注册的工具你可以手动填参数调用看到原始返回。实测下来这个方式排查参数错误特别快——比如城市名传了中文导致 API 返回 404调试界面会直接显示错误信息不用去猜模型为什么没调对。再验证一下 SSE 端点的稳定性。开两个终端一个跑 Server另一个用 curl 保持长连接curl -N http://127.0.0.1:9000/sse保持连接的同时在 Claude Desktop 里连续问三次天气。观察 curl 输出应该能看到多条消息事件依次推送没有断连。如果中途断了检查 Server 日志有没有异常退出常见原因是 httpx 超时没捕获导致协程崩溃。对于想验证模型侧接入是否正常的同学可以单独用 API 发一条请求确认 Base URL 和 Key 生效curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的key \ -H Content-Type: application/json \ -d {model:claude-3-5-sonnet,messages:[{role:user,content:ping}]}返回正常就说明模型通道没问题。这一步和 MCP 是独立的但两者都通整个工具调用体验才完整。你也可以在 https://taotoken.net/models 直接对话验证模型可用性省去写 curl 的功夫。5. 常见报错排查401、local proxy failed、reading choices 与 OAuth调试 MCP 服务器时报错基本集中在几类。我把真实遇到过的整理出来对照着查能省不少时间。401 Unauthorized这个最常见分两种。一种是模型侧 Key 无效检查OPENAI_API_KEY或TAOTOKEN_API_KEY有没有复制完整、有没有多余空格。另一种是工具内部调用的第三方 API Key 失效比如天气服务的 key 过期Server 日志会显示 401。区分方法看报错发生在握手阶段还是工具执行阶段。握手阶段报 401 是模型侧工具执行阶段报 401 是数据源侧。local proxy failed / connection refused客户端连不上 Server。先确认 Server 进程还活着curl http://127.0.0.1:9000/sse能不能通。如果 Server 正常但客户端报这个错多半是 URL 写错了比如漏了/sse后缀或者用了localhost而客户端解析到了 IPv6。改成127.0.0.1通常能解决。还有一种情况是端口被占用换个端口重启。reading choices 相关报错这类通常出现在模型返回结构不符合预期时比如你用的模型 ID 不支持工具调用或者 Base URL 指向的端点不兼容 OpenAI 格式。检查 Model ID 是否拼写正确Base URL 是否是https://taotoken.net/api这种标准格式。如果模型本身不支持 function calling工具调用链路会直接断掉换一个支持工具调用的模型即可。OAuth 相关报错部分 MCP 客户端在连接远程 Server 时会走 OAuth 流程如果你自建的 Server 没实现鉴权客户端可能卡在授权页。本地调试阶段建议先用无鉴权的 SSE等链路通了再加mcp.require_auth之类的装饰器。如果必须走 OAuth确认回调地址和客户端配置一致别一个用 http 一个用 https。工具注册了但模型不调用这不是报错但很常见。原因通常是 docstring 写得太模糊模型不知道什么时候该用。把函数描述写具体比如“获取指定城市的实时天气数据参数 city 为英文城市名”模型判断准确率会明显提升。另外工具数量太多也会稀释模型注意力调试阶段先注册一两个跑通再加。排查时养成看日志的习惯。Server 端用uv run python weather_server.py前台运行所有请求和异常都会打出来。客户端侧 Claude Desktop 的日志在%APPDATA%\Claude\logs下遇到连接问题翻一翻比盲猜快得多。6. 把工具接进真实工作流统一 Key 下的长期用法链路跑通之后真正的价值在于把 MCP 服务器接进日常。比如你有一个内部知识库可以写一个search_docs工具让模型在回答时自动检索或者接一个数据库查询工具用自然语言生成 SQL 再执行。这些场景的共同点是工具逻辑在本地数据不出内网模型只负责决策和表达。长期使用时Key 管理会变成负担。如果你同时用 Claude Desktop、Cursor、还有自己写的 Agent 脚本每个都配一套凭证很烦。统一走 TaoToken 的接入方式一个 Key 覆盖多个客户端Base URL 固定为https://taotoken.net/api模型 ID 按场景选。编码类任务如果跑得频繁Coding Plan 的额度比按量计费更省接入文档在 https://taotoken.net/doc 有详细说明。Claude Code 用户可以直接参考 https://taotoken.net/ClaudeCodeAnthropic 的配置方式把 Base URL 和 Key 填进去就能用。一个实用技巧把 MCP Server 做成可配置的工具列表通过环境变量控制开关。比如生产环境只开查询类工具调试环境开全部。这样同一份代码能适应不同场景不用改代码重新部署。另外SSE 长连接在长时间空闲后可能被中间层断开加一个心跳机制或者定期重连能避免“用着用着工具突然不响应”的问题。最后说个我自己的习惯每加一个新工具先用 MCP CLI 单独测通再配到客户端里。这样出问题时能快速定位是工具本身的问题还是客户端配置的问题。工具调用的稳定性靠的就是这种一层层验证的笨办法。