1. 为什么第一个 MCP 服务值得从 FastMCP 开始如果你最近在折腾智能体大概率会反复看到三个词智能体、MCP、Model Context Protocol。MCP 是 Anthropic 提出的开放协议它把「大模型怎么调用外部工具」这件事标准化了。你可以把它理解成 AI 应用世界的 USB-C 接口以前每个模型、每个框架都要自己定义一套函数调用格式现在只要服务端按 MCP 暴露能力客户端就能用统一方式发现并调用。而 FastMCP 是 Python SDK 里封装度最高的那一层。它把协议细节、传输层、参数校验都藏起来你只需要写普通的 Python 函数加一个装饰器它就变成一个可被智能体调用的工具。对刚入门的人来说这就是智能体开发里的 Hello World不追求功能多强先确认「模型能发现我的工具、能成功调用、能拿到结果」这条链路是通的。这篇内容适合三类人完全没写过 MCP 服务的新手、写过函数调用但没接触过 MCP 协议的开发者、以及想把本地工具接进统一 API 通道的工程师。我会用一个「查询 arxiv 最新论文」的真实小工具做例子从零写出服务骨架跑通本地调试再通过统一 Key 和 API 通道接入 TaoToken 完成端到端调用。全程可复制不需要任何特殊网络环境。2. 前置准备环境、依赖与 TaoToken 通道2.1 Python 环境与依赖安装FastMCP 现在直接内置在官方mcp包里不需要单独装。建议用 Python 3.10 以上虚拟环境隔离一下更干净。python -m venv venv source venv/bin/activate # Windows 用 venv\Scripts\activate pip install mcp[cli] arxiv httpx这里三个包各有分工mcp[cli]提供 FastMCP 和命令行调试工具arxiv负责抓论文元数据httpx留着后面做异步请求。装完可以用python -c from mcp.server.fastmcp import FastMCP; print(ok)验证一下能打印 ok 就说明环境没问题。2.2 为什么需要一个统一 API 通道本地 MCP 服务跑起来后智能体要调用它中间还得有个「模型侧」的入口。传统做法是每个模型厂商一套 Key、一套地址、一套参数格式切换模型时改代码改到崩溃。TaoToken 的价值就在这里它提供统一的 Key 和 API 通道模型对话、编码计划、控制台、API Keys 都在一个体系里MCP 工具接进来之后换模型不用重写调用逻辑。你需要提前准备两样东西一个可用的 API Key以及确认好要用的模型名。Key 在控制台的 API Keys 页面生成地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。生成后先复制保存后面配置文件里要用。注意Key 只显示一次建议生成后立刻存进密码管理器或本地环境变量不要直接硬编码进要提交到 Git 的代码里。3. 可复制配置FastMCP 服务骨架与接入文件3.1 最小 MCP 服务计算器 问候资源先写一个最小可运行的服务确认 FastMCP 的基本结构。新建hello_mcp.pyfrom mcp.server.fastmcp import FastMCP mcp FastMCP(Demo) mcp.tool() def add(a: int, b: int) - int: Add two numbers return a b mcp.resource(greeting://{name}) def get_greeting(name: str) - str: Get a personalized greeting return fHello, {name}! if __name__ __main__: mcp.run(transportstdio)三个关键点FastMCP(Demo)里的名字是服务标识mcp.tool()装饰的函数会自动被解析成工具参数类型和 docstring 会变成 schemamcp.resource()暴露的是只读数据源用 URI 模板访问。transportstdio表示走标准输入输出适合本地进程间通信性能最好。3.2 真实工具arxiv 论文搜索服务把上面的骨架换成有实际价值的工具。新建arxiv_server.pyimport json import arxiv from mcp.server.fastmcp import FastMCP app FastMCP(arxiv-search, port9000) app.tool() async def arxiv_search(query: str) - str: 根据关键词返回 arxiv 上最新提交的论文列表 client arxiv.Client() search arxiv.Search( queryquery, max_results3, sort_byarxiv.SortCriterion.SubmittedDate, ) results [] for r in client.results(search): results.append({ url: r.entry_id, title: r.title, published: r.published.strftime(%Y-%m-%d), }) return json.dumps(results, ensure_asciiFalse) if __name__ __main__: app.run(transportsse)这里用transportsse因为后面要通过 HTTP 通道接入SSE 传输更适合跨进程调用。port9000是服务监听端口客户端连http://127.0.0.1:9000/sse就能建立会话。工具函数返回 JSON 字符串智能体拿到后能直接解析。3.3 config.tomlMCP 客户端注册服务不同客户端配置文件格式略有差异但核心字段一致。以常见的config.toml为例[mcp_servers.arxiv] command python args [/absolute/path/to/arxiv_server.py] transport sse url http://127.0.0.1:9000/sse如果你用的是 stdio 版本把transport改成stdio去掉url客户端会自动拉起进程。路径一定写绝对路径相对路径在不同工作目录下会找不到文件这是新手最常踩的坑。3.4 settings.json统一 API 通道配置在客户端的settings.json里配置模型侧通道把 Key 和地址填进去{ api_base: https://taotoken.net/api, api_key: sk-你的Key, model: claude-sonnet-4-20250514, mcp_servers: [arxiv] }api_base用 https://taotoken.net/api 注意这里不加任何查询参数。model填你实际要用的模型名控制台里能看到可用列表。mcp_servers数组里写上面 config.toml 注册的服务名客户端启动时会自动加载。提示如果客户端支持环境变量插值把api_key写成${TAOTOKEN_API_KEY}然后在 shell 里 export比明文写在 JSON 里安全得多。4. 验证请求确认智能体真的调用了 MCP 工具4.1 本地调试Inspector 可视化验证FastMCP 自带调试工具终端里跑npx -y modelcontextprotocol/inspector python arxiv_server.py它会自动打开浏览器点 Connect 连上服务然后你能在 Tools 标签页看到arxiv_search在 Resources 标签页看到暴露的资源。手动填个 query 点调用右侧会返回论文 JSON。这一步能过说明服务本身没问题。4.2 客户端调用端到端跑通写个最小客户端脚本client_test.pyimport asyncio from mcp.client.sse import sse_client from mcp import ClientSession async def main(): async with sse_client(http://127.0.0.1:9000/sse) as streams: async with ClientSession(*streams) as session: await session.initialize() tools await session.list_tools() print(发现工具:, [t.name for t in tools.tools]) res await session.call_tool(arxiv_search, {query: Model Context Protocol}) print(调用结果:, res.content[0].text[:300]) if __name__ __main__: asyncio.run(main())先启动服务python arxiv_server.py另开终端跑客户端。成功的话你会看到两行输出第一行列出发现的工具名第二行是论文 JSON 的前 300 字符。看到arxiv_search出现在工具列表里并且返回了真实论文数据就说明智能体已经能发现并调用这个 MCP 工具了。4.3 通过统一通道发起模型请求工具链路通了之后把模型侧也接上。用 curl 验证统一 API 通道是否正常curl https://taotoken.net/api/v1/messages \ -H Content-Type: application/json \ -H x-api-key: $TAOTOKEN_API_KEY \ -H anthropic-version: 2023-06-01 \ -d { model: claude-sonnet-4-20250514, max_tokens: 256, messages: [{role: user, content: 用一句话说明 MCP 是什么}] }返回里能看到模型正常回复就说明 Key 和通道都没问题。接下来在支持 MCP 的客户端里模型会自动把arxiv_search作为可调用工具用户问「帮我找 MCP 最新论文」时模型会发起工具调用服务返回数据模型再组织成自然语言回答。整条链路用户提问 → 模型决策 → MCP 工具执行 → 结果回传 → 模型总结全部跑通。5. 本篇常见错误排查5.1 服务启动报 ModuleNotFoundError最常见的是mcp或arxiv没装进当前虚拟环境。确认which python指向的是 venv 里的解释器然后重新pip install mcp[cli] arxiv。如果用的是 conda注意别装到 base 环境去了。5.2 Inspector 连不上或工具列表为空先确认服务进程真的在跑curl http://127.0.0.1:9000/sse应该有事件流响应。如果端口被占用改FastMCP(arxiv-search, port9001)换个端口。工具列表为空通常是装饰器没生效检查app.tool()是否写在函数正上方中间不能有空行或其他装饰器。5.3 客户端调用超时SSE 连接建立后如果长时间无响应多半是 arxiv 请求本身慢。给arxiv.Client()加超时参数或者在工具函数里包一层asyncio.wait_for。另外确认客户端和服务端在同一台机器跨机访问要把127.0.0.1换成实际 IP并检查防火墙。5.4 API 通道返回 401 或 403先检查 Key 有没有复制完整前后不能有空格。然后确认请求头字段名对Anthropic 风格用x-api-keyOpenAI 风格用Authorization: Bearer。如果还是 401去控制台重新生成一个 Key 试试有时候是旧 Key 被禁用或额度用尽。5.5 模型不调用工具模型没发起工具调用通常是工具描述不够清晰。app.tool()函数的 docstring 会变成工具描述写得太模糊模型就不知道什么时候该用。把 docstring 改成「当用户需要查询 arxiv 论文时调用此工具」这种明确触发条件命中率会高很多。6. 下一步把 MCP 工具接进长期编码流跑通这个 Hello World 之后你已经掌握了 MCP 服务的核心结构定义工具、暴露资源、本地调试、端到端调用。接下来可以往两个方向走。一是把工具做厚。现在只有 arxiv 搜索你可以加文件读写、数据库查询、内部 API 调用每个都是一个app.tool()函数。工具越多智能体能做的事越多但要注意每个工具的 docstring 都要写清楚触发场景否则模型会乱调。二是把通道用起来。如果你打算长期做编码或 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 里面有各语言 SDK 的完整示例。想先直观感受模型对话效果的可以直接去 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 试一下。我自己的经验是MCP 服务写多了之后真正花时间的不是写工具函数而是调 docstring 和参数 schema让模型准确判断「什么时候该调、传什么参数」。这个只能靠反复实测没有捷径。