1. 从“嘴炮 AI”到“能动手的 Agent”MCP 到底解决什么问题你让 AI 帮你查一下服务器磁盘空间它回你一段 500 字的df -h使用教程你让它读一下项目里的配置文件它开始给你讲“首先打开终端然后 cd 到目录”。这种场景做 AI Agent 的开发者都不陌生——模型脑子够用但它没有手。MCPModel Context Protocol就是给 AI 装手的那套标准。它由 Anthropic 提出并开源核心思路是把“模型能调用的外部能力”抽象成一个个 MCP Server每个 Server 通过标准协议暴露若干 tool客户端Claude Desktop、Cline、自研 Agent 等负责把 tool 列表喂给模型模型决定调哪个、传什么参数客户端再去真正执行并把结果回传。整条链路跑通之后AI 就从“告诉你怎么做”变成“直接帮你做完”。它和 Function Calling 的区别我用一句话概括Function Calling 是模型厂商私有的函数调用格式你写死在代码里换一家模型就得重写MCP 是跨模型、跨客户端的开放协议工具写一次Claude 能用别的支持 MCP 的客户端也能用。前者像某品牌专用充电口后者像 Type-C。这篇面向想让 Claude 等 AI Agent 真正调用外部工具的开发者从零跑通 MCP 客户端到工具服务的完整闭环并且把 TaoToken 统一 Key 接进settings.json和config.toml让模型请求走同一条 API 通道省得每个客户端配一遍。2. 前置准备TaoToken 统一 Key 与 MCP 运行环境在动手写 MCP Server 之前先把两件事准备好一个能用的模型 API 通道以及 Python 侧的 MCP SDK。TaoToken 在这里的角色是统一 Key 网关。你注册后在控制台创建一个 API Key之后 Claude Desktop、Cline、自研脚本都复用这一个 Key模型请求统一走https://taotoken.net/api。这样做的实际好处是MCP 客户端配置里不用散落多个厂商的 Key换模型只改一个model字段排查问题时也只需要看一条请求链路。环境侧需要 Python 3.10 以上MCP 官方 Python SDK 对版本有要求。装包一行pip install mcp anthropic httpxmcp提供 Server 和 Client 两端能力anthropic用来在自研脚本里调 Claudehttpx后面写网页抓取工具会用到。装完可以python -c import mcp; print(mcp.__version__)确认一下。注意MCP Server 本质是一个本地进程客户端通过 stdio 或 SSE 跟它通信。stdio 模式下 Server 的 stdout 会被协议占用所以调试打印一律走 stderr否则会污染协议流导致客户端解析失败。3. 可复制配置settings.json 与 config.toml 接入 TaoToken不同客户端的配置文件格式不一样。Claude Desktop 用claude_desktop_config.jsonCline 这类 VS Code 插件用settings.json一些命令行 Agent 用config.toml。下面给出两种最常见的骨架。3.1 settings.jsonClaude Desktop / Cline 风格{ mcpServers: { weather: { command: python, args: [/Users/you/mcp_demo/weather_mcp.py], env: { TAOTOKEN_API_KEY: sk-你的统一Key, TAOTOKEN_BASE_URL: https://taotoken.net/api } } }, env: { ANTHROPIC_API_KEY: sk-你的统一Key, ANTHROPIC_BASE_URL: https://taotoken.net/api } }关键点mcpServers里每个条目是一个 MCP Server 的启动命令env把 TaoToken 的 Key 和 Base URL 注入进去Server 内部如果要调模型或调外部 API 就能直接读环境变量。外层env是客户端自己调模型时用的同样指向 TaoToken。3.2 config.toml命令行 Agent 风格[model] provider anthropic api_key sk-你的统一Key base_url https://taotoken.net/api model claude-sonnet-4-20250514 [mcp_servers.weather] command python args [/Users/you/mcp_demo/weather_mcp.py] [mcp_servers.weather.env] TAOTOKEN_API_KEY sk-你的统一Key TAOTOKEN_BASE_URL https://taotoken.net/apiTOML 的层级更清晰[model]段管模型通道[mcp_servers.*]段管工具进程。改模型只动model字段工具配置完全不用碰。提示Key 不要硬编码进提交到 Git 的文件。生产环境用系统环境变量或密钥管理服务注入配置文件里只留占位符。4. 写一个最小 MCP Server 并验证调用链路配置就绪后写一个天气查询 Server 来验证整条链路。新建weather_mcp.pyfrom mcp.server.fastmcp import FastMCP mcp FastMCP(weather-service) mcp.tool() def get_weather(city: str) - str: 查询指定城市的天气情况。 Args: city: 城市名称例如 北京、上海、成都 fake_data { 北京: 晴 25C 适合出门, 上海: 小雨 20C 记得带伞, 成都: 阴 18C 适合吃火锅, } return fake_data.get(city, f暂时没有 {city} 的天气数据) mcp.tool() def add_numbers(a: float, b: float) - str: 两个数字相加。 Args: a: 第一个数 b: 第二个数 return f{a} {b} {a b} if __name__ __main__: mcp.run()mcp.tool()装饰器把普通函数注册成 MCP tool函数签名和 docstring 会自动转成 JSON Schema 给模型看。docstring 写得越清楚模型选工具、填参数就越准。接着写客户端脚本agent_client.py把 MCP Server 的工具列表转成 Claude 认识的格式并处理 tool_use 回环import asyncio import os from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client import anthropic async def run_agent(): server StdioServerParameters( commandpython, args[weather_mcp.py], ) async with stdio_client(server) as (read, write): async with ClientSession(read, write) as session: await session.initialize() tools await session.list_tools() claude_tools [ { name: t.name, description: t.description, input_schema: t.inputSchema, } for t in tools.tools ] client anthropic.Anthropic( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL], ) response client.messages.create( modelclaude-sonnet-4-20250514, max_tokens1000, toolsclaude_tools, messages[{role: user, content: 成都今天天气怎么样}], ) for block in response.content: if block.type tool_use: result await session.call_tool( block.name, argumentsblock.input ) print(f调用了 {block.name}结果{result.content[0].text}) asyncio.run(run_agent())运行前导出环境变量export TAOTOKEN_API_KEYsk-你的统一Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api python agent_client.py预期输出调用了 get_weather结果阴 18C 适合吃火锅看到这行就说明闭环通了客户端启动 MCP Server → 拉取工具列表 → 转成 Claude 格式 → 模型决定调get_weather→ 客户端执行 → 结果回传。AI 不再给你写教程它真的去查了。5. 本篇常见错排查报错一ModuleNotFoundError: No module named mcp客户端启动 Server 用的 Python 解释器和你装包的 Python 不是同一个。settings.json里把command写成绝对路径比如/usr/local/bin/python3或者用虚拟环境的解释器路径。报错二客户端连不上 Server日志显示 JSON 解析失败Server 里用了print()往 stdout 打调试信息。stdio 模式下 stdout 是协议通道任何非协议输出都会破坏解析。把所有调试打印改成print(..., filesys.stderr)。报错三模型不调工具直接回答两个原因。一是 tool 的 docstring 太模糊模型不知道什么时候该用二是input_schema没正确生成检查函数参数有没有类型注解。MCP SDK 靠类型注解生成 schemadef get_weather(city)和def get_weather(city: str)结果完全不同。报错四401 或鉴权失败检查TAOTOKEN_BASE_URL有没有多写斜杠或路径。正确值是https://taotoken.net/api不要写成https://taotoken.net/api/v1。Key 确认从控制台复制完整前后没有空格。报错五tool_use 返回了但 call_tool 报参数错误模型传的参数名和函数参数名对不上。检查 docstring 里的Args:描述和实际参数名是否一致模型是照着 schema 填的。6. 把统一 Key 用顺后续接入与验证入口链路跑通之后日常开发里最省事的做法是让所有 MCP 客户端共用同一个 TaoToken Key。Claude Desktop、Cline、自研脚本都指向https://taotoken.net/api换模型只改model字段工具配置一行不动。如果你在配 Key 或接 MCP 客户端时卡住先去控制台把 Key 和接入文档对一遍API Keys 管理在 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite接入参数说明在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite。想先验证模型通道是否正常不写代码直接对话最快https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite。如果你打算长期跑编码类 Agent、让 MCP 工具链常驻Coding Plan 比按量计费更划算入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite。最后留一个我踩过的坑MCP Server 的 tool 数量别一次暴露太多超过 20 个之后模型选错工具的概率明显上升。按业务域拆成多个 Server每个 Server 只暴露 5 到 8 个高相关 tool调用准确率会好很多。