Agent 与 MCP 概念学习：从 JSON-RPC 到 config.toml 的 TaoToken 配置骨架

1. 从一次工具调用失败说起Agent 与 MCP 到底在解决什么如果你刚开始接触 Agent 开发大概率会遇到这样一个场景你写了一个能对话的 LLM 应用想让它帮忙查数据库、读文件、调 GitHub于是给每个工具手写一套适配代码。工具一多参数格式、错误处理、鉴权方式全都不一样代码迅速膨胀成一团乱麻。Agent 与 Model Context ProtocolMCP要解决的正是这个“工具接入碎片化”的问题。Agent 可以理解成以大语言模型为大脑、能自主感知—推理—决策—行动的软件系统。它和传统单轮问答的区别在于传统 LLM 是你问一句它答一句被动响应Agent 则是理解任务后主动规划、调用工具、观察结果、继续推理形成一个闭环。一个完整的 Agent 通常由四部分组成LLM 负责推理决策Memory 保存上下文与偏好Tools 负责与外部世界交互Planning 负责任务拆解与编排。用一句话概括就是 Agent LLM Memory Tools Planning。而 MCPModel Context Protocol模型上下文协议是 Anthropic 开源的开放协议定位是让大模型和 Agent 以统一标准访问外部工具、数据源和服务。打个比方它就像 USB-C 接口之于硬件——以前每个工具都要写一套适配代码现在只要遵循 MCP就能即插即用。它的通信底座是 JSON-RPC 2.0本地进程走 stdio远程服务走 HTTPSSE 或 Streamable HTTP。本文会从 JSON-RPC 的握手细节讲到一份可复制的 config.toml 骨架并给出三步验证动作帮你把 MCP 真正跑起来。2. 动手前的准备用 TaoToken 统一 Key 与 API 通道在配置 MCP Server 之前先解决模型侧和工具侧的接入通道问题。很多新手卡在第一步不同模型厂商的 Key 格式不同、Base URL 不同、计费方式不同写 Agent 时要在代码里维护一堆分支。我的做法是用 TaoToken 作为统一的 Key 与 API 通道把模型调用收敛到一个入口这样 MCP 配置里只需要关心工具本身不用反复改模型参数。TaoToken 的官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 这个地址不加 UTM 参数直接用于代码里的 base_url。你需要先在控制台创建一个 API Key然后把它写进环境变量避免硬编码到配置文件里被提交到仓库。创建 Key 的路径是控制台里的 API Keys 页面https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。拿到形如sk-xxxx的 Key 之后建议这样设置环境变量Linux/macOS 用 exportWindows 用 setx# Linux / macOS export TAOTOKEN_API_KEYsk-你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api # Windows PowerShell setx TAOTOKEN_API_KEY sk-你的Key setx TAOTOKEN_BASE_URL https://taotoken.net/api这里有个容易踩的坑base_url 末尾不要多加/v1或斜杠具体路径由 SDK 拼接。如果你用的是 OpenAI 兼容的客户端通常只需要把 base_url 指向https://taotoken.net/apiKey 用上面创建的即可。模型对话的调试入口在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 可以先用它验证 Key 是否可用再去配 MCP这样能把“模型不通”和“工具不通”两类问题分开排查。3. 可复制的 config.toml 骨架把 MCP Server 接进来MCP 的发现机制目前以静态配置为主你在配置文件里显式声明要接入哪些 ServerAI 程序启动时读取并连接。不同 Host 的配置格式不一样Claude Desktop 用 JSON而很多 CLI 形态的 Host比如 Claude Code 这类用 TOML。下面这份 config.toml 骨架可以直接复制修改我把它拆成三段模型通道、MCP Server 声明、以及每个 Server 的启动参数。# 模型通道统一走 TaoToken [model] provider openai-compatible base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY model claude-sonnet-4-20250514 # MCP Server 声明 # 每个 [[mcp_servers]] 对应一个 Server 进程 [[mcp_servers]] name filesystem transport stdio command npx args [-y, modelcontextprotocol/server-filesystem, /Users/me/docs] enabled true [[mcp_servers]] name github transport stdio command npx args [-y, modelcontextprotocol/server-github] enabled true [mcp_servers.env] GITHUB_TOKEN ${GITHUB_TOKEN} [[mcp_servers]] name postgres transport stdio command npx args [-y, modelcontextprotocol/server-postgres, postgresql://localhost/mydb] enabled false # 远程 Server 示例HTTP SSE [[mcp_servers]] name remote-tools transport sse url https://example.com/mcp/sse enabled false几个关键字段说明。transport决定通信方式本地进程用stdio远程服务用sse或streamable-http。command和args是启动 Server 子进程的命令npx -y表示自动确认安装。env段用来注入环境变量注意用${VAR}语法引用系统环境变量不要把 Token 明文写进去。enabled字段方便你临时关掉某个 Server 而不删配置。这里要提醒一句MCP Server 的职责边界是“把工具按 MCP 规范暴露出去”它不负责决策也不负责编排。决策由 LLM 做编排由 Client 或 Agent 框架做。所以你在 config.toml 里配的只是“有哪些工具可用”至于什么时候调用、传什么参数是模型在运行时根据工具描述自己决定的。4. 三步验证从启动日志到工具调用结果比对配置写完不代表能用MCP 的调试需要按链路逐段验证。我总结了三步验证动作每一步都有明确的成功标志出问题时也能快速定位是哪一环断了。4.1 第一步启动日志确认 Server 进程拉起启动 Host 后先看日志里有没有每个 Server 的启动记录。以 stdio 为例正常会看到类似这样的输出[mcp] starting server filesystem via stdio [mcp] server filesystem process spawned, pid48213 [mcp] server github process spawned, pid48214 [mcp] connected to 2/3 servers (postgres disabled)如果某个 Server 显示failed to spawn或connection timeout先检查command是否在 PATH 里。npx找不到是最常见的问题可以用which npx确认路径必要时在 config.toml 里写绝对路径。另一个高频错误是 args 里的路径不存在比如 filesystem Server 指向的目录被删了进程会直接退出。4.2 第二步JSON-RPC 握手回包检查进程起来之后Client 会通过 JSON-RPC 和 Server 握手。这一步的核心是initialize调用和能力协商。你可以手动模拟一次握手来验证 Server 是否正常响应。对于 stdio 类型的 Server可以用管道直接喂 JSON-RPC 消息echo {jsonrpc:2.0,id:1,method:initialize,params:{protocolVersion:2024-11-05,capabilities:{},clientInfo:{name:test,version:1.0}}} \ | npx -y modelcontextprotocol/server-filesystem /Users/me/docs正常会返回类似这样的结果注意capabilities字段里声明了该 Server 支持哪些能力{ jsonrpc: 2.0, id: 1, result: { protocolVersion: 2024-11-05, capabilities: { tools: {}, resources: {} }, serverInfo: { name: filesystem, version: 0.6.2 } } }握手成功后紧接着调用tools/list获取工具清单echo {jsonrpc:2.0,id:2,method:tools/list,params:{}} \ | npx -y modelcontextprotocol/server-filesystem /Users/me/docs返回的tools数组里每个工具都有name、description和inputSchema。这个 schema 就是 LLM 看到的参数定义如果 schema 写错了模型生成的参数就会对不上调用必然失败。所以第二步的检查重点是握手有没有回包、工具清单里有没有你期望的工具、inputSchema 的字段类型是否正确。4.3 第三步工具调用返回结果比对前两步都过了最后验证真实调用。在 Host 里发一条会触发工具的消息比如“帮我读一下 docs 目录下的 README.md”然后观察日志里的 JSON-RPC 请求和响应-- {method:tools/call,params:{name:read_file,arguments:{path:/Users/me/docs/README.md}}} -- {result:{content:[{type:text,text:# 项目说明\n...}]}}比对的重点是返回内容和你直接打开文件看到的是否一致。如果返回isError: true看 error message 里是权限问题还是路径问题。我试过因为 filesystem Server 的根目录配成了相对路径导致模型传绝对路径时被拒绝访问改成绝对路径后就好了。这一步过了说明整条链路——模型决策、JSON-RPC 转发、Server 执行、结果回传——全部打通。5. 本篇常见错排查握手失败、工具不出现、调用超时配 MCP 的过程中报错基本集中在几个地方。下面按现象分类给出排查顺序。握手阶段报protocolVersion mismatchClient 和 Server 的协议版本对不上。MCP 协议还在演进老版本 Server 可能只支持2024-11-05而新 Client 默认发更高版本。解决办法是在 config.toml 里显式指定protocol_version或者升级 Server 到最新版。这类错误在日志里通常表现为 initialize 请求发出后没有回包或者回包里带 error 字段。工具清单为空tools/list返回空数组先确认 Server 本身有没有实现工具。有些 Server 只提供 Resources 不提供 Tools这时候tools/list返回空是正常的但resources/list应该有内容。如果两个都空检查 Server 的启动参数比如 postgres Server 需要传入连接字符串没传的话它可能启动成功但什么都不暴露。工具调用超时stdio 类型的 Server 如果执行时间长比如跑一个大 SQLClient 默认超时可能不够。可以在 config.toml 里加timeout字段单位秒。另外注意stdio 是单进程串行处理如果一个工具调用卡住后续请求会排队。远程 SSE 类型则要检查网络连通性和服务端是否支持流式响应。环境变量没生效${GITHUB_TOKEN}这种写法依赖 Host 支持变量展开。如果 Host 不支持会直接把字面量传进去导致鉴权失败。排查方法是看 Server 日志里收到的 Token 是不是${...}原文。不支持的话改用 Host 提供的密钥管理功能或者用启动脚本先 export 再启动 Host。模型不调用工具只输出文字这通常不是 MCP 的问题而是模型侧的工具描述没注入成功。检查 Client 有没有把tools/list的结果转成模型的 function calling 格式。如果用的是 TaoToken 统一通道确认请求里带了 tools 参数。模型对话调试入口可以帮你确认模型本身是否支持工具调用https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。6. 把链路跑通之后下一步该往哪走当你能稳定地让 Agent 通过 MCP 调用工具并且三步验证都通过之后接下来可以往两个方向深入。一是扩展 Server 数量把常用的数据库、对象存储、内部 API 都包成 MCP Server让 Agent 的能力边界跟着扩大。二是优化工具描述因为 LLM 选择工具完全依赖description和inputSchema描述写得越清楚模型选错工具的概率越低。我踩过的坑是给两个功能相近的工具写了几乎一样的描述结果模型经常调错后来把适用场景写进 description 里才解决。如果你打算长期做编码类 Agent 或需要频繁调用模型可以了解一下 Coding Plan它更适合高频、长上下文的开发场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。接入文档里有各语言 SDK 的完整示例配 MCP 时遇到 Client 侧的问题可以对照查https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。Key 的管理和轮换在 API Keys 页面操作建议给不同项目建不同的 Key方便排查用量和及时吊销。