Model Context Protocol (MCP) 实战：用 JSON-RPC 打通 AI 工具链的配置骨架

1. 为什么 MCP 值得你花一个下午跑通Model Context ProtocolMCP是 Anthropic 在 2024 年 11 月推出的开放协议它想解决的问题很具体让 AI 模型用一套标准方式去调用外部工具和数据源。你可以把它理解成 AI 工具链里的 USB-C——以前每接一个数据库、每连一个文件系统都要单独写适配层现在只要服务端按 MCP 暴露能力客户端就能动态发现并调用。它基于 JSON-RPC 2.0 做消息格式传输层可以走 Stdio、HTTP、SSE 或 WebSocket。这个分层设计意味着协议层管消息结构传输层管怎么送应用层管资源resource、工具tool、提示prompt三类组件的注册。对开发者来说最直接的价值是——你写一次 MCP 服务端Cursor、Cline、Claude Code 这类客户端都能接。这篇面向的是需要让本地 AI 工具接入统一模型通道的开发者。我会先给可复制的 config.toml / settings.json 配置骨架再走一遍 MCP 服务端与客户端的握手验证最后把 CC Switch、Cline 接入 TaoToken 的步骤串起来。目标是一次跑通不绕弯。2. 前置准备TaoToken 通道与 MCP 运行环境MCP 本身只定义通信不负责模型从哪来。你要让客户端里的 AI 真正干活得先有一个统一的模型通道。TaoToken 在这里扮演的就是这个角色——它提供兼容 Anthropic 风格的 API 入口MCP 客户端把模型请求发过去工具调用结果再回传给模型。先拿 Key。打开 https://taotoken.net/api-keys 登录后创建一个 API Key复制保存。注意这个 Key 只在创建时完整显示一次丢了就重新建。模型通道的 Base URL 用 https://taotoken.net/api 不要加任何多余路径。如果你用的是 Anthropic 风格的客户端它通常要求填ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY两个环境变量对应关系如下环境变量值ANTHROPIC_BASE_URLhttps://taotoken.net/apiANTHROPIC_API_KEY你刚创建的 KeyANTHROPIC_MODEL按控制台可用列表填如 claude-sonnet-4-5MCP 服务端这边Python 用pip install mcpNode 用npm install modelcontextprotocol/sdk。我建议先用 Python 的 FastMCP 起一个最小服务端因为它把 JSON-RPC 的握手细节封装得比较干净你能更快看到initialize和tools/list的往返。注意MCP 服务端和模型通道是两件事。服务端负责暴露工具TaoToken 负责提供模型。客户端同时连这两边缺一不可。3. 可复制配置config.toml 与 settings.json 骨架先写 MCP 服务端。新建mcp-demo/server.pyfrom mcp.server import FastMCP mcp FastMCP(demo-server) mcp.tool() def add(a: int, b: int) - int: 两数相加用于验证工具调用链路 return a b mcp.tool() def read_config(path: str) - str: 读取指定路径的文本文件 with open(path, r, encodingutf-8) as f: return f.read() if __name__ __main__: mcp.run(transportstdio)这段代码注册了两个工具。add用来做最小验证read_config演示资源读取。transportstdio表示走标准输入输出这是本地 MCP 最常用的传输方式客户端拉起子进程后通过 stdin/stdout 交换 JSON-RPC 消息。接着是客户端的 config.toml 骨架。以 Cline 或类似支持 TOML 的客户端为例[mcp_servers.demo] command python args [/absolute/path/to/mcp-demo/server.py] env { PYTHONUNBUFFERED 1 } [model] provider anthropic base_url https://taotoken.net/api api_key sk-你的Key model claude-sonnet-4-5如果你用的是 JSON 配置的客户端比如 Claude Desktop 或 Cline 的 settings.json等价写法是{ mcpServers: { demo: { command: python, args: [/absolute/path/to/mcp-demo/server.py], env: { PYTHONUNBUFFERED: 1 } } }, model: { provider: anthropic, baseUrl: https://taotoken.net/api, apiKey: sk-你的Key, model: claude-sonnet-4-5 } }两个配置里command和args必须用绝对路径相对路径在客户端拉起子进程时经常找不到文件。PYTHONUNBUFFERED1是为了让 Python 的输出不被缓冲否则 JSON-RPC 消息可能卡在缓冲区里客户端一直等不到响应。4. 握手验证从 initialize 到 tools/call 跑通配置写好后先单独验证 MCP 服务端能不能正常握手。最直接的办法是用官方提供的 inspector或者手写一个最小 JSON-RPC 客户端。我用后者因为你能清楚看到每条消息。新建mcp-demo/client_test.pyimport json import subprocess proc subprocess.Popen( [python, server.py], stdinsubprocess.PIPE, stdoutsubprocess.PIPE, textTrue, ) def send(msg): proc.stdin.write(json.dumps(msg) \n) proc.stdin.flush() return json.loads(proc.stdout.readline()) # 1. 初始化握手 init send({ jsonrpc: 2.0, id: 1, method: initialize, params: { protocolVersion: 2024-11-05, capabilities: {}, clientInfo: {name: test-client, version: 1.0} } }) print(initialize:, init) # 2. 通知初始化完成 send({jsonrpc: 2.0, method: notifications/initialized}) # 3. 列出可用工具 tools send({jsonrpc: 2.0, id: 2, method: tools/list}) print(tools/list:, tools) # 4. 调用 add 工具 result send({ jsonrpc: 2.0, id: 3, method: tools/call, params: {name: add, arguments: {a: 3, b: 4}} }) print(tools/call:, result)跑python client_test.py你应该看到四段输出。initialize返回服务端的 protocolVersion 和 capabilitiestools/list返回add和read_config两个工具的描述tools/call返回{result: {content: [{type: text, text: 7}]}}。这一步跑通说明 JSON-RPC 的请求-响应链路是通的。接下来把客户端指向 TaoToken让模型来决定调哪个工具。在 Cline 里你只需要在设置里填好 Base URL 和 Key然后发一句「帮我算 3 加 4」。模型会返回一个 tool_use 块客户端解析后调用 MCP 服务端的add再把结果回传给模型模型最终输出「7」。CC Switch 的场景类似它本质是帮你切换不同的模型通道配置。把 TaoToken 的 Base URL 和 Key 填进它的 provider 配置MCP 服务端照常挂在客户端侧两边互不干扰。5. 常见报错排查握手失败与工具不触发报错一Method not found: initialize。这通常是客户端和服务端的 protocolVersion 不匹配。检查服务端 SDK 版本pip show mcp看是不是太旧。2024-11-05 是初版协议新版本 SDK 可能默认用更新的版本号两边对齐即可。报错二客户端一直转圈没有 tools/list 返回。九成是 stdio 缓冲问题。确认PYTHONUNBUFFERED1已设置或者在 Python 里加sys.stdout.reconfigure(line_bufferingTrue)。另外检查args里的路径是不是绝对路径。报错三模型不调用工具直接编答案。这说明模型通道没把工具描述传过去或者模型本身不支持 tool use。确认你用的模型在 TaoToken 控制台里标注了支持 function calling。如果支持检查客户端有没有把tools/list的结果塞进请求的tools字段。报错四401 Unauthorized。Key 错了或者 Base URL 多了斜杠。Base URL 严格用https://taotoken.net/api不要写成https://taotoken.net/api/或带/v1。Key 重新复制一次注意前后不要有空格。报错五工具调用返回isError: true。看服务端日志。常见是参数类型不对比如add期望 int模型传了字符串。在工具函数里加类型转换或校验返回明确的错误信息模型下一轮会自己修正。提示调试 MCP 时先把模型通道断开只用 client_test.py 验证服务端。服务端通了再接模型能省掉一半排查时间。6. 把这条链路固定下来跑通一次之后建议把server.py和客户端配置一起放进项目仓库用相对路径加启动脚本包装避免换机器后绝对路径失效。MCP 服务端可以按领域拆多个比如db-server、file-server、api-server客户端配置里并列挂载模型会根据工具描述自动选择。模型通道这边TaoToken 的 Key 建议用环境变量注入不要硬编码在 settings.json 里。长期做编码或 Agent 场景的话可以了解下 Coding Plan它更适合高频工具调用的负载。接入文档在 https://taotoken.net/doc 里面有各客户端的详细字段说明。想先验证模型对话是否正常可以直接用 https://taotoken.net/models 试一句。整条链路的核心就三件事MCP 服务端用 JSON-RPC 暴露工具客户端负责握手和转发模型通道提供推理能力。三者解耦任何一环出问题都能单独替换和排查。