1. 从一次“工具调用失败”说起MCP、Tool Calling、Agent 到底怎么串起来如果你刚开始接触 LLM 应用开发大概率会遇到这样一个场景模型能聊天但一让它“查一下天气”“读一下本地文件”“调一下数据库”它就开始胡编或者干脆告诉你它做不到。你翻文档看到三个词——MCP、Tool Calling、Agent每个词单独看都懂但放在一起就懵它们到底谁调用谁我该先写哪个我试过最笨的办法先照着 Tool Calling 的文档写一个函数跑通了再去看 MCP发现它像是“工具的统一插座”最后看 Agent发现它是“会自己决定用哪个插座的调度员”。三者不是替代关系而是从下到上的三层协作MCP 负责把外部能力标准化地暴露出来Tool Calling 负责让模型把“我想干什么”翻译成结构化调用Agent 负责在多轮里规划、重试、串联这些调用。这篇笔记就按这个顺序用一个最小可运行案例把三层串起来。你不需要先搭一整套微服务只要有一个能发 HTTP 请求的本地环境加上 TaoToken 的统一 Key 和 API 通道就能把 MCP 服务注册、Tool Calling 验证、Agent 循环三件事一次跑通。下面所有配置和命令都可以直接复制我会把每一步“怎么确认它生效了”写清楚避免你卡在“看起来配好了但没反应”的状态。2. TaoToken 前置一个 Key 打通模型通道别在鉴权上耗时间在写任何 Tool Calling 代码之前先把模型通道固定下来。很多入门教程卡人的地方不是逻辑而是每家模型一套 Key、一套 Base URL、一套参数名。TaoToken 在这里的作用是提供一个统一的 API 入口你拿一个 Key就能用 OpenAI 兼容的方式调用不同模型后面 MCP 和 Agent 的示例代码不用因为换模型而重写。你需要先拿到两样东西API Key 和 Base URL。Key 在控制台的 API Keys 页面创建Base URL 用https://taotoken.net/api。注意这个地址后面不加任何路径后缀OpenAI SDK 会自动拼/v1/chat/completions。如果你用的是其他兼容 OpenAI 协议的客户端填 Base URL 时也保持这个形式。创建 Key 的入口在这里控制台 API Keyshttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite拿到 Key 之后先别急着写业务代码用一条 curl 确认通道是通的。这一步能帮你排除掉后面 80% 的“模型没反应”问题curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { model: gpt-4o-mini, messages: [{role: user, content: 只回复两个字通了}] }如果返回的 JSON 里choices[0].message.content是“通了”说明 Key 和通道都没问题。把TAOTOKEN_API_KEY写进你的环境变量后面 Python 和 Node 示例都从环境变量读不要硬编码在代码里。这里有个容易踩的坑Base URL 末尾不要加/v1。有些客户端要求你填完整路径但 OpenAI SDK 的base_url参数会自动补/v1你多写一层就变成/v1/v1/chat/completions直接 404。实测下来保持https://taotoken.net/api最省事。3. 可复制配置settings.json 与 config.toml 骨架不同客户端读不同格式的配置文件。如果你用 Claude Code 这类支持 MCP 的工具它读的是settings.json如果你用 Codex 或类似 CLI它读的是config.toml。下面两份骨架你按需取用核心是把模型通道和 MCP 服务注册分开写别混在一起。先看settings.json。这个文件通常放在用户目录下的配置文件夹里比如~/.claude/settings.json。它的结构分两块一块是模型通道一块是 MCP 服务注册。{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: 你的_TaoToken_Key }, mcpServers: { local-tools: { command: python, args: [-m, mcp_server_demo], env: { PYTHONUNBUFFERED: 1 } } } }这里mcpServers下的local-tools是你自己起的服务名command和args决定怎么启动这个 MCP 服务。我建议先用一个最简单的 Python 脚本当 MCP 服务确认注册链路通了再换成真实工具。再看config.toml适合 Codex 这类 CLImodel gpt-4o-mini model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY [mcp_servers.local-tools] command python args [-m, mcp_server_demo]两份配置的共同点是模型通道只写一次MCP 服务按名字注册。这样你后面加第二个、第三个 MCP 服务时只需要在mcpServers或mcp_servers下面追加一段不用动模型配置。注意env_key和ANTHROPIC_API_KEY都指向环境变量不要把真实 Key 写进配置文件提交到 Git。如果你在本地测试图省事直接写了记得加.gitignore。配置写完后先别启动 Agent单独验证 MCP 服务能不能被拉起来。在终端里手动执行python -m mcp_server_demo如果它没有立刻报错退出而是停在等待输入的状态说明服务本身没问题。接下来才是让客户端去连它。4. MCP 服务注册片段把“本地能力”变成模型可调用的工具MCP 的核心价值是标准化。没有它的时候你每接一个工具就要写一套函数描述、参数校验、错误处理有了它工具方只要按 MCP 协议实现一个 server客户端就能动态发现它有哪些方法、需要什么参数。下面这个最小 MCP 服务用 Python 写只暴露一个read_file方法用来验证注册链路。# mcp_server_demo.py import json import sys def read_file(path: str) - str: with open(path, r, encodingutf-8) as f: return f.read() TOOLS { read_file: { description: 读取指定路径的文本文件内容, parameters: { type: object, properties: { path: {type: string, description: 文件绝对路径} }, required: [path] } } } def handle(request): method request.get(method) if method tools/list: return {tools: [{name: k, **v} for k, v in TOOLS.items()]} if method tools/call: name request[params][name] args request[params].get(arguments, {}) if name read_file: return {content: read_file(args[path])} return {error: unknown method} for line in sys.stdin: line line.strip() if not line: continue req json.loads(line) resp handle(req) print(json.dumps(resp), flushTrue)这个脚本用标准输入输出做 JSON-RPC 通信是最简形态。把它保存到当前目录然后在settings.json里把args改成[mcp_server_demo.py]或者用python -m的方式确保模块能被找到。注册成功后客户端启动时会向 MCP 服务发tools/list拿到工具清单。你可以在客户端日志里看到类似discovered 1 tool: read_file的输出。如果没看到先检查三件事Python 路径对不对、脚本有没有语法错误、command和args是不是能拼成一条可执行命令。MCP 服务注册好之后模型并不会自动去调它。模型只知道“有一个叫 read_file 的工具可用”至于什么时候调、传什么参数那是 Tool Calling 的事。这就是下一节要验证的。5. 验证 Tool Calling让模型自己决定“调哪个函数、传什么参数”Tool Calling 的本质是模型输出一段结构化 JSON告诉你它想调哪个函数、参数是什么。你拿到这段 JSON 后自己去执行再把结果回传给模型模型再生成自然语言回复。整个链路里模型不直接执行任何代码执行权在你手里。下面用 Python 和 OpenAI SDK 写一个最小验证。先装依赖pip install openai然后写调用代码import os import json from openai import OpenAI client OpenAI( base_urlhttps://taotoken.net/api, api_keyos.environ[TAOTOKEN_API_KEY] ) tools [{ type: function, function: { name: read_file, description: 读取指定路径的文本文件内容, parameters: { type: object, properties: { path: {type: string, description: 文件绝对路径} }, required: [path] } } }] resp client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: 帮我读一下 /tmp/demo.txt 的内容}], toolstools, tool_choiceauto ) msg resp.choices[0].message print(finish_reason:, resp.choices[0].finish_reason) print(tool_calls:, msg.tool_calls)如果模型决定调用工具finish_reason会是tool_callsmsg.tool_calls里会有函数名和参数。你会看到类似这样的输出finish_reason: tool_calls tool_calls: [ChatCompletionMessageToolCall( idcall_abc123, functionFunction(nameread_file, arguments{path:/tmp/demo.txt}) )]这一步验证的是“模型能不能正确识别意图并生成结构化调用”。如果finish_reason是stop而不是tool_calls说明模型选择直接回答而不是调工具。常见原因是工具描述不够清楚或者用户问法太模糊。你可以把tool_choice临时改成{type: function, function: {name: read_file}}强制它调确认链路通了再改回auto。拿到tool_calls之后你需要自己执行read_file把结果作为role: tool的消息追加回去再请求一次模型tool_call msg.tool_calls[0] args json.loads(tool_call.function.arguments) file_content open(args[path], r, encodingutf-8).read() followup client.chat.completions.create( modelgpt-4o-mini, messages[ {role: user, content: 帮我读一下 /tmp/demo.txt 的内容}, msg, {role: tool, tool_call_id: tool_call.id, content: file_content} ] ) print(followup.choices[0].message.content)第二次请求返回的才是给用户看的自然语言。到这里Tool Calling 的完整闭环就跑通了用户提问 → 模型生成调用 → 你执行 → 结果回传 → 模型总结。6. 验证 Agent 循环多轮里自动重试与串联Agent 和单次 Tool Calling 的区别在于“循环”和“决策”。单次调用是线性的问一次、调一次、答一次。Agent 是模型可以连续调多个工具根据上一步结果决定下一步失败还能重试。下面这个最小 Agent 循环用while实现核心是维护一个消息列表直到模型不再请求工具为止。def run_agent(user_input, max_turns5): messages [{role: user, content: user_input}] for turn in range(max_turns): resp client.chat.completions.create( modelgpt-4o-mini, messagesmessages, toolstools, tool_choiceauto ) msg resp.choices[0].message messages.append(msg) if not msg.tool_calls: return msg.content for tc in msg.tool_calls: args json.loads(tc.function.arguments) try: result read_file(args[path]) except Exception as e: result f调用失败: {e} messages.append({ role: tool, tool_call_id: tc.id, content: result }) return 达到最大轮次仍未完成 print(run_agent(先读 /tmp/a.txt再读 /tmp/b.txt把两者内容拼起来告诉我))这个循环里模型第一轮可能只调read_file读 a.txt拿到结果后第二轮再调read_file读 b.txt第三轮才输出拼接结果。你可以在每轮打印turn和msg.tool_calls观察 Agent 的决策过程。验证 Agent 是否生效看两个信号一是turn大于 1 且中间有多次tool_calls说明它在多轮里串联二是某次工具调用抛异常后循环没有崩而是把错误信息回传给模型模型决定重试或换路径。这就是 Agent 比单次调用强的地方——它把“失败”也当成一种上下文。如果你想让 Agent 更稳可以在工具执行外面包一层重试import time def safe_call(fn, args, retries3): for i in range(retries): try: return fn(**args) except Exception as e: if i retries - 1: raise time.sleep(0.5)把read_file换成safe_call(read_file, args)网络抖动或临时文件锁导致的失败就不会直接中断整个 Agent 流程。7. 本篇常见错排查配置对了但没反应怎么办第一个高频问题MCP 服务注册了但客户端启动时报command not found。这通常是command写的是python但你的环境里只有python3。把command改成python3或者用绝对路径/usr/bin/python3。Windows 下则是python.exe的完整路径。第二个问题Tool Calling 返回finish_reason: stop模型不调工具。先检查tools数组有没有正确传进去再检查工具描述是不是太笼统。把description写具体比如“读取指定路径的文本文件内容仅支持 UTF-8 编码”比“读文件”更容易让模型匹配意图。第三个问题Agent 循环停不下来一直调同一个工具。这通常是因为工具返回的结果里没有模型需要的信息模型以为没拿到就反复调。你可以在工具结果里加一个明确的结束标记或者在max_turns到限时强制返回。另外检查tool_call_id有没有正确对应回传时role: tool的消息必须带tool_call_id否则模型会认为调用没完成。第四个问题Base URL 配成https://taotoken.net/api/v1导致 404。前面说过OpenAI SDK 会自动补/v1你只需要写到/api。如果你用的是其他客户端先看它的文档要求填完整路径还是 Base URL别两边都按自己的习惯来。第五个问题环境变量没生效。在终端里echo $TAOTOKEN_API_KEY确认有值Python 里os.environ.get(TAOTOKEN_API_KEY)确认能读到。如果你在 IDE 里跑注意 IDE 可能不继承终端的环境变量需要在运行配置里单独设。8. 下一步把最小案例换成你自己的工具跑通上面这套之后你手里已经有了一个可工作的三层结构MCP 服务负责暴露能力Tool Calling 负责让模型生成调用Agent 循环负责多轮编排。接下来要做的不是继续加复杂度而是把read_file换成你真正需要的工具——查数据库、调内部 API、读日志、发消息。换工具的时候MCP 服务那边改TOOLS字典和对应的处理函数Tool Calling 这边改tools数组里的function定义Agent 循环本身不用动。这就是分层的好处底层能力变了上层调度逻辑保持稳定。如果你后面要长期跑编码类 Agent或者想让 Agent 在多个会话之间保持上下文可以了解一下 Coding Plan 的额度方式比按次调用更适合高频场景Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite想先在线验证模型对某个工具描述的理解是否准确可以直接在模型对话页面试模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite接入文档里有更完整的参数说明和错误码对照遇到 401 或 429 的时候先查这里接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite最后留一个我踩过的坑MCP 服务不要直接连生产数据库。先用只读账号或者本地副本验证链路确认 Agent 的调用逻辑没问题了再逐步放开权限。工具调用一旦跑起来模型可能会在你没预期的时候发起请求权限边界要提前划好。
