MCP 协议实战：用 TaoToken 统一 Key 打通 AI Agent 的 JSON-RPC 调用链

1. 从一次 JSON-RPC 报错说起：MCP 协议到底解决什么问题

如果你最近在折腾 AI Agent，大概率见过这样的场景：Agent 想调用一个本地工具查数据库，代码里写死了函数名和参数格式；换一个模型供应商，工具描述又得重写一遍；想让 Claude Desktop 和自研 Agent 共用同一套工具，结果两边协议对不上。这些问题的根子在于，模型和外部工具之间缺少一层统一的通信约定。

MCP（Model Context Protocol，模型上下文协议）就是冲着这个痛点来的。它基于 JSON-RPC 2.0 定义了一套标准消息格式，把「模型想调用什么工具」和「工具怎么执行」解耦开。你可以把它理解成 AI 世界的 USB-C 接口：Server 端负责暴露工具（Tools）、资源（Resources）和提示（Prompts），Client 端负责发现并调用这些能力，中间走的是标准的 JSON-RPC 请求响应。

这套协议适合谁？我观察下来有三类人最需要：一是做 AI Agent 编排的开发者，需要让多个工具动态注册而不是硬编码；二是想把本地能力（文件系统、数据库、内部 API）安全暴露给模型的团队；三是希望在不同模型供应商之间自由切换、不被某家 Function Calling 格式绑死的工程师。MCP 的 JSON-RPC 通信层是纯文本、可调试的，出问题时你能直接看到请求体和响应体，这点比很多黑盒 SDK 友好得多。

这篇内容聚焦 MCP 的通信层实战。我会用 Python 写一个最小的 MCP Server 和 Client，把工具注册、请求路由、响应解析这条链路完整跑通，然后把模型调用的 endpoint 切到 TaoToken 统一管理 Key，最后用一次真实的工具调用验证整条链路。全程代码可复制，报错可对照排查。

2. TaoToken 前置准备：统一 Key 与 endpoint 配置

在动手写 MCP 代码之前，先把模型调用的出口理清楚。MCP 本身只负责工具通信，但 Agent 最终还是要调 LLM 来做意图判断和参数提取。如果每个项目都散落着不同的 API Key 和 base_url，维护成本会很高。我的做法是用 TaoToken 做统一入口，一个 Key 覆盖多个模型，endpoint 也统一。

TaoToken 的 API 地址是https://taotoken.net/api，注意这个地址不带任何查询参数，直接作为 base_url 使用。官网入口在https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=，注册后在控制台生成 Key 即可。控制台地址是https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite，API Keys 管理页在https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite。

这里有个关键点：MCP 的 JSON-RPC 通信和模型调用是两条独立的链路。JSON-RPC 走的是 stdio 或 HTTP，模型调用走的是 OpenAI 兼容的/v1/chat/completions。很多人第一次配的时候会把两者混在一起，导致 base_url 填错。正确的做法是：MCP Server 的启动命令里不涉及模型 endpoint，模型 endpoint 只在 Agent 主程序里配置。

我建议用环境变量管理 Key，避免硬编码。在项目根目录建一个.env文件：

TAOTOKEN_API_KEY=sk-你的实际Key TAOTOKEN_BASE_URL=https://taotoken.net/api

然后在 Python 里用python-dotenv加载。这样 MCP Server 和 Client 都能读到同一份配置，切换环境时只改.env就行。如果你用的是 Claude Code 这类工具，它的配置方式略有不同，需要走settings.json或环境变量注入，后面第 3 节会给具体片段。

有一点要提醒：TaoToken 是合规的 API 聚合入口，不是所谓的「中转」。它的作用是让你用一个 Key 调用多个模型，省去分别申请和管理 Key 的麻烦。配置时确保 base_url 写对，不要多加/v1后缀，SDK 会自动拼接。

3. 可复制配置：server.py 与 client.py 完整片段

这一节是核心，我给出两个文件的完整代码。先装依赖：

pip install mcp openai python-dotenv

mcp是官方 Python SDK，openai用来调 TaoToken 的兼容接口。先写server.py：

# server.py import asyncio import json from mcp.server import Server from mcp.server.stdio import stdio_server from mcp.types import Tool, TextContent app = Server("demo-mcp-server") # 模拟一个用户数据源 USERS = [ {"id": 1, "name": "张三", "role": "工程师"}, {"id": 2, "name": "李四", "role": "产品经理"}, ] @app.list_tools() async def list_tools() -> list[Tool]: return [ Tool( name="get_user_by_id", description="根据用户ID获取用户信息", inputSchema={ "type": "object", "properties": { "user_id": {"type": "integer", "description": "用户ID"} }, "required": ["user_id"], }, ), Tool( name="list_users", description="列出所有用户", inputSchema={"type": "object", "properties": {}}, ), ] @app.call_tool() async def call_tool(name: str, arguments: dict) -> list[TextContent]: if name == "get_user_by_id": uid = arguments.get("user_id") user = next((u for u in USERS if u["id"] == uid), None) text = json.dumps(user, ensure_ascii=False) if user else "用户不存在" return [TextContent(type="text", text=text)] if name == "list_users": return [TextContent(type="text", text=json.dumps(USERS, ensure_ascii=False))] return [TextContent(type="text", text=f"未知工具: {name}")] async def main(): async with stdio_server() as (read, write): await app.run(read, write, app.create_initialization_options()) if __name__ == "__main__": asyncio.run(main())

再写client.py，它负责启动 Server 子进程、发 JSON-RPC 请求、解析响应：

# client.py import asyncio import json import os from dotenv import load_dotenv from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client from openai import OpenAI load_dotenv() # 模型调用走 TaoToken llm = OpenAI( api_key=os.getenv("TAOTOKEN_API_KEY"), base_url=os.getenv("TAOTOKEN_BASE_URL"), ) async def run(): params = StdioServerParameters(command="python", args=["server.py"]) async with stdio_client(params) as (read, write): async with ClientSession(read, write) as session: await session.initialize() # 1. 发现工具 tools = await session.list_tools() print("可用工具:", [t.name for t in tools.tools]) # 2. 调用工具 result = await session.call_tool("get_user_by_id", {"user_id": 1}) print("工具返回:", result.content[0].text) # 3. 把工具结果交给模型做自然语言总结 resp = llm.chat.completions.create( model="gpt-4o-mini", messages=[ {"role": "system", "content": "你是助手，根据工具返回的JSON用中文回答。"}, {"role": "user", "content": f"用户信息：{result.content[0].text}"}, ], ) print("模型总结:", resp.choices[0].message.content) if __name__ == "__main__": asyncio.run(run())

如果你用 Claude Code，配置片段放在~/.claude/settings.json或项目级.mcp.json：

{ "mcpServers": { "demo": { "command": "python", "args": ["server.py"], "env": { "TAOTOKEN_API_KEY": "sk-你的Key", "TAOTOKEN_BASE_URL": "https://taotoken.net/api" } } } }

三件套对照：Base URL 填https://taotoken.net/api，Key 填控制台生成的sk-开头字符串，Model ID 填gpt-4o-mini或你账号下可用的模型名。Cline 的 MCP 配置类似，在cline_mcp_settings.json里按同样结构写。Codex 的auth.json则是另一套格式，把 base_url 和 key 填进对应字段即可。

4. 验证请求：一次真实工具调用的完整链路

配置写完后，跑起来验证。先单独启动 Server 确认不报错：

python server.py

如果卡住不动是正常的，stdio 模式在等 Client 连接。按 Ctrl+C 退出，然后跑 Client：

python client.py

预期输出：

可用工具: ['get_user_by_id', 'list_users'] 工具返回: {"id": 1, "name": "张三", "role": "工程师"} 模型总结: 用户张三，ID为1，职位是工程师。

这三行分别对应链路的三个阶段。第一行是tools/list的 JSON-RPC 响应，证明工具注册成功；第二行是tools/call的响应，证明请求路由和参数传递正确；第三行是模型调用成功，证明 TaoToken 的 endpoint 配置无误。

如果你想看底层 JSON-RPC 报文长什么样，可以在 Client 里加日志。MCP 的请求体大致是：

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_user_by_id","arguments":{"user_id":1}}}

响应体：

{"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"{\"id\":1,...}"}]}}

看到这个结构你就明白了：MCP 的通信层就是标准的 JSON-RPC，method决定路由到哪个 handler，params是参数，result是返回。工具注册的本质是 Server 响应tools/list时返回一个 Tool 数组，Client 拿到后可以动态展示给模型。

实测下来，整条链路从 Client 启动到模型返回大约 2-3 秒，其中模型调用占大头。如果你只想验证 MCP 通信层，可以先把模型调用那段注释掉，只看前两行输出。

5. 常见报错排查：401、local proxy failed 与 reading choices

这一节列几个我踩过的坑，对照报错找原因。

401 Unauthorized：模型调用返回 401，说明 TaoToken 的 Key 没读到或填错了。先检查.env是否被load_dotenv()正确加载，再确认 Key 没有多余空格。如果是在 Claude Code 里报 401，检查settings.json的env字段是否把 Key 传给了子进程。注意 base_url 不要写成https://taotoken.net/api/v1，SDK 会自己拼/v1，多写一层会 404 或 401。

local proxy failed / connection refused：这个报错通常出现在 stdio 模式下 Server 启动失败。检查command和args是否指向正确的 Python 解释器。如果你用虚拟环境，command要写 venv 里的 python 绝对路径，不能只写python。另外确认server.py路径是相对 Client 工作目录的，路径不对会直接找不到文件。

reading choices 报错 / KeyError 'choices'：说明模型返回的结构不是预期的 OpenAI 格式。常见原因是 base_url 指向了错误的 endpoint，或者模型名写错导致返回了错误对象。打印resp原始内容看看，如果是{"error": ...}就说明请求没成功。确认 Model ID 是你账号下真实可用的，不要凭记忆填。

OAuth 相关报错：如果你在 Claude Code 里看到 OAuth 字样，通常是认证方式冲突。MCP Server 本身不走 OAuth，走的是 stdio 或 HTTP。检查是不是把 MCP 配置和模型认证配置混在了同一个文件里。分开管理：MCP 的mcpServers只管进程启动，模型认证走环境变量或单独的 auth 配置。

工具调用返回「未知工具」：说明call_tool里的 name 匹配没命中。检查list_tools返回的 name 和call_tool里判断的字符串是否完全一致，大小写敏感。另外确认 Client 传的arguments键名和inputSchema里定义的一致。

排查时有个通用技巧：在call_tool开头加一行print(f"收到调用: {name}, 参数: {arguments}")，直接看 Server 端收到了什么。stdio 模式下 print 会输出到 stderr，不影响 JSON-RPC 通道。

6. 把链路用起来：从最小示例到生产接入

最小链路跑通后，你可以按需扩展。工具注册这块，把USERS换成真实的数据库查询或内部 API 调用即可，inputSchema用 JSON Schema 描述清楚参数类型，模型才能正确提取。请求路由方面，工具多了以后建议按业务域拆分多个 Server，Client 端并行连接，避免单个 Server 过于臃肿。

模型调用这块，TaoToken 的统一 Key 优势在多模型场景下会体现出来。比如意图识别用便宜的小模型，复杂推理用大模型，只改model参数，base_url 和 Key 都不用动。如果你要长期跑编码类 Agent，可以看看 Coding Plan 的额度方案，地址是https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite。想先在线试模型效果的，模型对话入口在https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite。

接入文档在https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite，里面有各语言 SDK 的配置示例。Claude Code 的专项接入说明在https://taotoken.net/doc/claudecode?utm_source=taotoken_aicg_blog_end&utm_content=claudecode&utm_campaign=rewrite，如果你用 Claude Code 做主力开发工具，这份文档能省不少配置时间。

最后说个实用技巧：MCP Server 的调试不要一上来就接真实模型，先用list_tools和call_tool把通信层验证通过，再接模型。这样出问题时能快速定位是协议层还是模型层。我习惯在 Client 里加一个--dry-run参数，只跑工具调用不调模型，排查效率高很多。整条链路的核心就是 JSON-RPC 的请求响应，把这层看透了，上面接什么模型、下面挂什么工具，都是可替换的零件。