1. 从零跑通 MCP Hello World为什么你总在第一步卡住MCPModel Context Protocol这两年被聊得很多但真正动手写一个最小可运行示例时很多人会卡在几个很具体的地方JSON-RPC 的握手格式写错、工具注册后客户端找不到、本地 Server 起来了但 AI 工具侧连不上。我自己第一次搭的时候光是把initialize请求的protocolVersion字段对齐就折腾了半小时。这篇内容面向 Python 开发者目标很明确从零搭一个本地 MCP Server 和 Client走通 JSON-RPC 握手、工具注册、工具调用这条完整链路最后用 TaoToken 的统一 Key 把 AI 工具侧接进来。你会拿到可复制的config.toml和settings.json骨架以及每一步的启动命令和验证动作。适合谁适合已经知道 MCP 大概是什么、但还没亲手跑通过一个 Hello World 的人。如果你连 MCP 的基本概念都还没建立建议先补一下协议层的背景再回来跟着敲代码。整条链路其实就三件事Server 暴露工具、Client 按 JSON-RPC 2.0 发请求、AI 工具侧通过统一通道调用。下面按这个顺序拆开讲每一步都给可复制的代码和验证方式。2. TaoToken 前置准备统一 Key 与 API 通道在写代码之前先把 AI 工具侧的接入通道准备好。MCP 的 Server 和 Client 是本地跑但真正让模型去调用工具时需要一个稳定的 API 通道。TaoToken 在这里的角色是提供统一的 Key 和 API 入口省去你在多个模型供应商之间来回切换配置的麻烦。你需要做两件事拿到 API Key确认 API 地址。API 地址是https://taotoken.net/api这个不加任何参数直接作为 base URL 用。Key 的获取在控制台的 API Keys 页面登录后新建一个即可。注意Key 只显示一次复制后存到环境变量里别硬编码进代码提交到仓库。拿到 Key 之后建议先做一次最小验证确认通道是通的。用 curl 发一个最简单的请求export TAOTOKEN_API_KEY你的Key curl https://taotoken.net/api/v1/models \ -H Authorization: Bearer $TAOTOKEN_API_KEY如果返回模型列表的 JSON说明 Key 和通道都没问题。这一步别跳过后面 MCP Client 调不通时你能快速判断是协议层的问题还是通道层的问题。对于长期做编码或 Agent 场景的可以考虑 Coding Plan它在调用频次和额度上更适合持续开发。如果只是验证模型对话用模型对话页面直接测就行。接入文档里有完整的参数说明遇到字段不确定时对着查。3. 可复制配置MCP Server 与 Client 骨架这一节给完整的可运行代码。先装依赖pip install jsonrpcserver requestsPython 3.7 即可。下面分 Server 和 Client 两部分。3.1 MCP Server工具注册与 JSON-RPC 握手Server 的核心是用method装饰器注册工具然后通过serve启动监听。这里我加了一个initialize方法用来模拟 MCP 的握手流程因为真实场景下 Client 第一步就是发initialize。# mcp_server.py from jsonrpcserver import method, Success, Result, serve method def initialize(context: dict) - Result: MCP 握手返回协议版本与能力声明 return Success({ protocolVersion: 2024-11-05, capabilities: {tools: {}}, serverInfo: {name: hello-mcp, version: 0.1.0} }) method def hello_world(context: dict) - Result: MCP 工具返回 Hello World return Success({message: Hello, MCP World!}) method def list_tools(context: dict) - Result: 动态工具发现列出可用工具 return Success({ tools: [{ name: hello_world, description: 返回欢迎信息, params: {} }] }) if __name__ __main__: print(MCP 服务端已启动监听端口 5000...) serve(port5000, methods[initialize, hello_world, list_tools])三个方法各司其职initialize负责握手hello_world是业务工具list_tools支持动态发现。返回结构必须用Success({...})包一层这是jsonrpcserver库的要求直接返回 dict 会导致序列化失败。3.2 MCP Client按 JSON-RPC 2.0 发请求Client 侧严格遵循 JSON-RPC 2.0 格式请求体包含jsonrpc、method、params、id四个字段。# mcp_client.py import requests MCP_ENDPOINT http://localhost:5000 def call_mcp(method_name: str, params: dict None, req_id: int 1) - dict: payload { jsonrpc: 2.0, method: method_name, params: params or {}, id: req_id } resp requests.post( MCP_ENDPOINT, jsonpayload, headers{Content-Type: application/json} ).json() if result in resp: return resp[result] return {error: resp.get(error, {}).get(message, unknown)} if __name__ __main__: # 第一步握手 init call_mcp(initialize, {context: {client: demo}}, 1) print(握手结果:, init) # 第二步发现工具 tools call_mcp(list_tools, {context: {}}, 2) print(可用工具:, tools) # 第三步调用工具 result call_mcp(hello_world, {context: {user: demo}}, 3) print(工具调用结果:, result)call_mcp做了统一封装id递增用来区分请求。实际协议里id用于匹配请求和响应这里简单递增即可。3.3 config.toml 与 settings.json 骨架如果你用的是支持 MCP 的编辑器或工具通常需要一份配置文件。config.toml骨架[mcp] enabled true endpoint http://localhost:5000 protocol_version 2024-11-05 [mcp.tools] hello_world { enabled true, description 返回欢迎信息 } [ai] provider taotoken api_base https://taotoken.net/api api_key_env TAOTOKEN_API_KEYsettings.json骨架{ mcpServers: { hello-mcp: { url: http://localhost:5000, transport: http, tools: [hello_world, list_tools] } }, ai: { baseUrl: https://taotoken.net/api, apiKeyEnv: TAOTOKEN_API_KEY } }这两份配置的作用是把本地 MCP Server 注册到工具侧同时把 AI 通道指向 TaoToken。api_key_env指向环境变量名避免明文写 Key。4. 验证请求启动命令与成功结果配置和代码都齐了现在按顺序跑一遍。先启动 Serverpython mcp_server.py # 输出MCP 服务端已启动监听端口 5000...另开一个终端跑 Clientpython mcp_client.py预期输出握手结果: {protocolVersion: 2024-11-05, capabilities: {tools: {}}, serverInfo: {name: hello-mcp, version: 0.1.0}} 可用工具: {tools: [{name: hello_world, description: 返回欢迎信息, params: {}}]} 工具调用结果: {message: Hello, MCP World!}看到Hello, MCP World!就说明整条 JSON-RPC 链路通了。如果只想快速验证单个工具也可以用 curlcurl -X POST http://localhost:5000 \ -H Content-Type: application/json \ -d {jsonrpc:2.0,method:hello_world,params:{context:{user:demo}},id:1}返回{jsonrpc: 2.0, result: {message: Hello, MCP World!}, id: 1}即为成功。这一步验证的是协议层。通道层的验证在前面第 2 节已经做过。两层都通说明 MCP 的 Hello World 完整流程跑通了。5. 本篇常见错排查跑不通的时候按下面几个方向查基本能覆盖 90% 的问题。握手失败返回 method not found。检查 Server 是否注册了initialize方法。有些教程只注册业务工具Client 第一步握手就会失败。methods列表里要把initialize加进去。返回 400 或解析错误。大概率是请求体格式问题。JSON-RPC 2.0 要求jsonrpc字段必须是字符串2.0不是数字2.0。另外params如果是空对象也要写成{}不能省略。Client 报 Connection refused。Server 没起来或者端口被占用。先确认python mcp_server.py的输出再用lsof -i :5000看端口状态。端口冲突就换一个Client 侧的MCP_ENDPOINT同步改。工具调用返回 error 但握手正常。检查方法名是否和 Server 注册的一致。method装饰器默认用函数名作为方法名如果你在 Client 里写的是helloWorld而 Server 是hello_world就会找不到。AI 工具侧连不上 MCP Server。确认settings.json里的url和 Server 实际监听地址一致。如果工具跑在容器里localhost可能指向容器内部需要换成宿主机的实际地址。TaoToken 通道返回 401。Key 没设置或环境变量名对不上。确认TAOTOKEN_API_KEY已经 export且api_base是https://taotoken.net/api不要多加路径。提示排查时先分层。协议层的问题看 Server 日志和 curl 返回通道层的问题看 Key 和 base URL。两层分开查比混在一起猜快得多。6. 把 Hello World 扩展成真实工具Hello World 跑通之后扩展方式很直接在 Server 侧加新的method方法在list_tools里补上元数据Client 侧改方法名和参数即可。比如加一个查询工具method def query_data(context: dict, sql: str) - Result: if context.get(auth_token) ! SECRET_123: return Success({status: error, message: Permission denied}) # 这里替换成你的真实查询逻辑 return Success({status: success, data: [{id: 1, name: demo}]})Client 调用时把method换成query_dataparams里带上sql和context。AI 模型侧只需要生成标准化的参数不用关心底层连接细节。长期做编码或 Agent 场景的话Coding Plan 在持续调用上更合适配合接入文档把参数对齐基本就能把 MCP 工具链稳定跑起来。验证模型对话行为时用模型对话页面直接测比在代码里反复改快。Key 管理在 API Keys 页面建议按项目分 Key方便排查和轮换。整条链路的核心就一句话Server 注册工具Client 按 JSON-RPC 2.0 调用AI 工具侧通过统一通道接入。把 Hello World 跑通剩下的就是替换工具逻辑。