1. 从零跑通 MCP为什么你的 AI 工具调用总是断在最后一步如果你正在搜「Python 构建 MCP 服务器」或者「AI 工具调用系统怎么落地」大概率已经踩过这样的坑工具函数写好了FastMCP实例也创建了客户端配置也填了结果 AI 代理那边要么看不到工具要么调用时报连接错误要么模型返回一堆和工具无关的废话。问题往往不在 MCP 协议本身而在于三个容易被忽略的环节——工具函数的返回格式、stdio 启动路径的绝对化、以及模型侧 API 通道是否稳定。MCPModel Control Protocol本质上是一套让 AI 代理和工具解耦的通信约定。你可以把它理解成「AI 世界的 USB 接口」服务器负责托管工具代理负责发现和调用模型只负责决策。这套架构的好处是工具可以独立开发、独立部署代理换一个也不影响工具复用。但代价是链路上多了好几个节点任何一环配置不对端到端就断。这篇教程面向本地开发和多工具协同场景用 Python Anthropic 的mcp库从零搭一个可用的 MCP 服务器并且把模型调用这一侧的 Key 通道统一到 TaoToken避免你在多个平台之间来回切换配置。目标很明确五步之内完成端到端联调让 AI 真的能调用你写的工具并返回结果。适合已经会基础 Python、想快速把 MCP 跑起来的小白和中级开发者。2. 前置准备TaoToken 统一 Key 与 API 通道配置在写 MCP 服务器之前先把模型侧的通道准备好。MCP 服务器本身不负责调用大模型它只负责暴露工具真正做决策的是 AI 代理背后的模型。所以你需要一个稳定的 API 入口让代理能拿到模型响应。TaoToken 在这里的角色就是统一 Key 和 API 通道省去你在不同模型平台之间反复配置的麻烦。先到官网注册并拿到 API Keyhttps://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content注册完成后进入控制台创建 Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentconsoleKey 的管理页面在https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-keysAPI 的基础地址是这个不加 UTM直接用于代码里https://taotoken.net/api拿到 Key 之后建议先写进环境变量不要硬编码在代码里。Linux/macOS 下export TAOTOKEN_API_KEYsk-你的keyWindows PowerShell$env:TAOTOKEN_API_KEYsk-你的key如果你用的是支持 OpenAI 兼容协议格式的客户端Base URL 填https://taotoken.net/apiKey 填上面创建的即可。这一步做完模型通道就通了接下来专心搞 MCP 服务器。注意MCP 服务器和模型 API 是两条独立的链路。MCP 负责工具发现与调用模型 API 负责推理决策。两者都要配好端到端才能跑通。3. 五步搭建可复制的 MCP 服务器3.1 第一步初始化项目与依赖用 UV 初始化项目比 pip 更干净依赖锁定也更可靠uv init McpAgent cd McpAgent uv add mcp执行完后pyproject.toml里会自动加上mcp依赖。确认一下 Python 版本要求建议 3.10 以上[project] name mcpagent version 0.1.0 requires-python 3.10 dependencies [ mcp1.9.1, ]3.2 第二步设计工具函数工具函数是 MCP 服务器的核心。设计原则就三条命名描述性强、类型提示完整、返回值用 JSON 字符串。下面这个get_host_info是最小可用示例# tools.py import platform import json def get_host_info() - str: 获取当前设备的系统信息。 Returns: str: 包含操作系统、架构等系统信息的 JSON 格式字符串。 system_info { os: platform.system(), architecture: platform.machine(), platform: platform.platform(), } return json.dumps(system_info) if __name__ __main__: print(get_host_info())单独跑一下验证uv run tools.py正常会输出类似{os: Darwin, architecture: arm64, platform: macOS-15.4.1-arm64-arm-64bit}这里有个坑返回值一定要是字符串。如果你直接返回 dict某些代理在序列化时会报错。用json.dumps包一层最稳。3.3 第三步构建 MCP 服务器并注册工具用FastMCP创建服务器实例把工具注册进去# main.py from mcp.server.fastmcp import FastMCP import tools mcp FastMCP(System Info Service) mcp.add_tool(tools.get_host_info) def main() - None: mcp.run(stdio) if __name__ __main__: main()如果你想把工具和服务器写在一个文件里用装饰器更简洁# main.py from mcp.server.fastmcp import FastMCP import platform import json mcp FastMCP(System Info Service) mcp.tool() def get_host_info() - str: 获取当前设备的系统信息。 return json.dumps({ os: platform.system(), architecture: platform.machine(), platform: platform.platform(), }) if __name__ __main__: mcp.run(stdio)mcp.tool()等价于mcp.add_tool(get_host_info)看个人习惯选一种就行。3.4 第四步配置客户端 settings.json以 Claude Desktop 为例打开开发者设置里的配置文件路径通常在macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json填入以下内容注意把路径换成你自己的绝对路径{ mcpServers: { hostInfoMcp: { command: /Users/yourname/.local/bin/uv, args: [ --directory, /Users/yourname/projects/McpAgent, run, main.py ] } } }两个关键点command必须是 uv 可执行文件的完整绝对路径--directory必须是项目根目录的绝对路径。相对路径在这里基本都会失败。如果你用的是其他支持 MCP 的代理配置结构类似只是文件名可能叫mcp_config.json或写在 IDE 的 settings 里。核心字段就是commandargs。3.5 第五步启动服务并发起调用验证保存配置后重启客户端。在聊天界面输入我的计算机的 CPU 架构是什么代理会弹出授权提示点击允许后模型会调用get_host_info返回类似arm64的结果。到这一步端到端就通了。如果你想在命令行里单独验证 MCP 服务器能否正常启动可以直接跑uv run main.pystdio 模式下它不会输出什么但也不应该报错退出。如果卡住不动说明服务器在等待标准输入这是正常的。4. 验证请求与成功结果对照为了让你确认每一步都对这里给一个对照表环节验证命令/动作预期结果工具函数uv run tools.py输出 JSON 系统信息MCP 服务器启动uv run main.py无报错进程挂起等待输入客户端配置重启后查看工具列表出现 hostInfoMcp端到端调用聊天输入查询弹出授权返回架构信息模型通道检查 API Key 是否生效模型正常返回文本如果模型侧返回的是「我无法访问你的系统」这类话说明工具没被识别回去检查settings.json的路径。如果返回的是连接超时检查模型 API 通道是否配好。5. 本篇常见错误排查错误一ModuleNotFoundError: No module named mcp说明依赖没装到当前环境。用uv add mcp重新装或者确认你跑的是uv run而不是系统 Python。错误二客户端看不到工具九成是路径问题。command和--directory都必须是绝对路径。macOS 下 uv 通常在~/.local/bin/uv用which uv确认。错误三调用时提示工具执行失败检查工具函数返回值是不是字符串。返回 dict 或 None 都会导致序列化失败。统一用json.dumps包一层。错误四模型不调用工具直接瞎答说明工具描述不够清晰。把 docstring 写详细参数和返回值都说明白。模型是靠这些描述来决定调不调的。错误五API 请求 401Key 没配对或者环境变量没生效。重新到 API Keys 页面确认 Key 状态检查 Base URL 是不是https://taotoken.net/api。错误六stdio 模式下服务器启动后立刻退出检查main()里是不是漏了mcp.run(stdio)或者if __name__ __main__写错了。6. 下一步把工具扩展到真实场景跑通最小示例之后你可以按同样的模式加更多工具。比如加一个读文件的工具mcp.tool() def read_text_file(path: str) - str: 读取指定路径的文本文件内容。 Args: path: 文件的绝对路径。 try: with open(path, r, encodingutf-8) as f: return f.read() except Exception as e: return json.dumps({error: str(e)})注意异常也要返回字符串不要让异常直接抛出去否则整个 MCP 服务器会崩。如果你打算长期做编码类 Agent或者需要多工具协同的复杂工作流建议把模型通道固定下来用 Coding Plan 管理调用配额会更省心https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding-plan想快速验证不同模型对工具调用的支持情况可以直接在模型对话页面测试https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmodel-chat接入文档里有完整的参数说明和示例https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc如果你用的是 Claude Code 这类编码代理Anthropic 兼容通道的配置方式在https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaude-code-anthropic最后提醒一句MCP 服务器的工具函数尽量保持单一职责一个工具只做一件事。工具越多模型选择时的准确率越依赖 docstring 的质量。我试过把五个功能塞进一个工具里结果模型经常传错参数拆成五个独立工具后调用准确率明显提升。