AI大模型-6：MCP原理和开发，用TaoToken统一Key跑通第一个MCP Server

1. 为什么你的 AI 应用需要一个「USB-C 接口」如果你最近在折腾 AI Agent大概率会遇到一个很具体的麻烦模型本身很聪明但它不知道你公司内部的工单系统长什么样也读不到你本地那个 CSV 文件更没法帮你把一段文本直接写进数据库。你想让它做这些事就得为每一个外部服务单独写一套对接代码——今天接一个天气 API明天接一个内部知识库后天又要接一个飞书机器人。每接一个就要重新定义一遍参数格式、错误处理、鉴权方式写到最后你会发现真正花在「让模型变聪明」上的时间远不如花在「让模型能连上东西」上的时间多。MCPModel Context Protocol模型上下文协议就是为了解决这个问题出现的。你可以把它理解成 AI 世界的 USB-C 接口以前每个设备都有自己的充电口现在统一成一个标准谁都能插。MCP 让 AI 模型和外部工具、数据源之间有了统一的交互协议Host、Client、Server 三个角色各司其职模型不需要知道工具内部怎么实现只需要按标准发起调用就行。这篇文章面向的是想动手跑通第一个 MCP Server 的开发者。我会从 MCP 的三角色架构讲起然后用 TaoToken 统一 Key 接入模型在本地把一个可调用的 MCP Server 真正跑起来。你会拿到可复制的 config.toml 和 settings.json 骨架、启动命令以及一次完整的工具调用验证。适合谁写过一点 Python 或 Node想搞清楚 MCP 到底怎么落地而不是只停留在概念层面的人。2. MCP 的 Host、Client、Server 到底谁在干活先把三个角色拆清楚不然后面配 config 的时候容易懵。MCP Host 是宿主应用也就是你平时直接面对的那个 AI 工具比如 IDE 里的 Copilot、Claude Desktop或者你自己写的一个 Agent 程序。Host 负责跟用户交互决定什么时候需要调用外部能力。MCP Client 是嵌在 Host 里面的一个组件它不直接面对用户而是负责跟 MCP Server 建立连接、发送请求、接收响应。你可以把它当成 Host 派出去的信使专门跑协议通信这件事。MCP Server 是真正干活的轻量级服务程序它把对外部资源或工具的访问能力封装起来通过标准协议暴露给 Client。比如一个查数据库的 Server、一个读本地文件的 Server、一个调内部 API 的 Server。通信层面MCP 基于 JSON-RPC 2.0支持两种传输方式。stdio 走标准输入输出适合本地进程比如你写个 Python 脚本当 ServerHost 直接把它当子进程拉起来。HTTPStreamable HTTP走网络请求适合远程服务。本地开发阶段stdio 是最省事的不用起端口、不用配网络。Server 能暴露三种能力Tools 是模型可以调用的函数比如查询、创建、更新Resources 是模型可以读取的数据比如文件内容、数据库记录Prompts 是预定义的提示模板。第一个 MCP Server 通常从 Tools 开始因为最容易验证。整个调用流程分三步。第一步 initializeClient 发初始化请求带上协议版本和客户端信息Server 返回自己支持的能力。第二步 tools/listClient 拉取 Server 注册的所有工具定义包括名字、描述、参数 schema。第三步 tools/call模型决定用某个工具时Client 按 schema 传参发起调用Server 执行后返回结果。这里有个容易踩的坑protocolVersion 不能随便写。它是 MCP 官方规范定义的版本号目前常见的是 2024-11-05 和 2025-03-26。Client 在 initialize 阶段会做版本协商如果你返回一个它不认识的版本它会直接拒绝连接报 unsupported protocol version。所以写 Server 的时候版本号要么跟 Client 对齐要么按官方规范来。3. 用 TaoToken 统一 Key 把模型通道先打通MCP Server 本身不负责调模型它只负责暴露工具。真正决定「什么时候调哪个工具」的是 Host 里的模型。所以你需要先有一个能稳定调用的模型通道这里用 TaoToken 统一 Key 来接。TaoToken 的定位是统一 API 通道你拿一个 Key 就能接入多种模型不用为每个模型单独维护一套鉴权和地址。对 MCP 开发来说好处是你可以在 Host 里把模型调用统一走 TaoTokenMCP Server 那边只管工具逻辑两边解耦。先拿 Key。打开 https://taotoken.net/api-keys 登录后创建一个 API Key复制出来存好。这个 Key 后面会填到 Host 的配置里用来调模型。如果你用的是 Claude Code 这类编码 AgentTaoToken 有对应的接入文档地址是 https://taotoken.net/doc 里面写了 base_url 和 Key 怎么填。核心就是把请求地址指向 TaoToken 的 API 端点鉴权用你刚创建的 Key。模型对话的调试入口在 https://taotoken.net/chat 你可以先在网页里发一条消息确认 Key 能用、模型有响应再去配本地环境。这一步别跳过很多人后面 MCP 调不通其实是 Key 或 base_url 填错了先在这里排除掉模型通道的问题。长期做编码或 Agent 开发的话可以看一下 Coding Plan地址是 https://taotoken.net/coding-plan 适合需要持续调用、不想每次手动换 Key 的场景。控制台在 https://taotoken.net/console 可以看调用记录和用量。4. 可复制的 config.toml 与 settings.json 骨架现在进入配置环节。不同 Host 的配置文件格式不一样这里给两个最常见的骨架你按自己用的工具选。先看 config.toml适合用 TOML 管理配置的 Host。核心是两段一段配模型通道一段配 MCP Server。[model] provider taotoken base_url https://taotoken.net/api api_key 你的_TaoToken_API_Key model_name claude-sonnet-4-20250514 [mcp_servers.local_demo] command python args [-m, mcp_server_demo] transport stdio enabled true这里 model 段告诉 Host 去哪里调模型base_url 指向 TaoToken 的 API 端点api_key 填你创建的那个。mcp_servers 段注册了一个本地 Servercommand 是启动命令args 是参数transport 选 stdio 表示走标准输入输出。再看 settings.json适合用 JSON 配置的 Host比如 Claude Desktop 类的工具。{ model: { provider: taotoken, baseUrl: https://taotoken.net/api, apiKey: 你的_TaoToken_API_Key, modelName: claude-sonnet-4-20250514 }, mcpServers: { local_demo: { command: python, args: [-m, mcp_server_demo], transport: stdio, enabled: true } } }两个骨架的结构是一样的模型通道走 TaoTokenMCP Server 走本地 stdio。你只需要把 api_key 换成自己的model_name 换成你想用的模型标识。注意一点MCP Server 的 command 和 args 必须能真正启动一个进程。如果你写的是 python -m mcp_server_demo那你的环境里得真的有这个模块否则 Host 拉起子进程时会直接失败日志里会看到 spawn 相关的错误。5. 写一个最小 MCP Server 并跑起来配置有了现在写 Server。用 Python 写一个最小的只暴露一个工具功能是查当前时间。别小看这个它能完整走通 initialize、tools/list、tools/call 三步。先装依赖pip install mcp然后创建 mcp_server_demo.pyimport asyncio from mcp.server import Server from mcp.server.stdio import stdio_server from mcp.types import Tool, TextContent app Server(local_demo) app.list_tools() async def list_tools(): return [ Tool( nameget_current_time, description返回当前服务器时间格式为 ISO 8601, inputSchema{ type: object, properties: {}, required: [] } ) ] app.call_tool() async def call_tool(name: str, arguments: dict): if name get_current_time: from datetime import datetime now datetime.now().isoformat() return [TextContent(typetext, textnow)] raise ValueError(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())这段代码做了三件事。用 Server(local_demo) 创建服务实例名字跟 config 里的 key 对应。用 app.list_tools() 注册工具列表返回一个 get_current_time 工具inputSchema 是空对象表示不需要参数。用 app.call_tool() 处理调用收到 get_current_time 就返回当前时间。启动命令就是配置里写的那个python -m mcp_server_demo如果你没做成模块直接跑文件也行python mcp_server_demo.py跑起来之后进程会挂在 stdio 上等 Client 发消息。你不会在终端看到什么输出这是正常的因为通信走的是标准输入输出不是打印到屏幕。6. 验证一次完整的工具调用Server 跑起来了现在验证调用。最直接的方式是在 Host 里发一条会触发工具的消息比如「现在几点了」。Host 收到消息后会先走 initialize跟 Server 协商协议版本和能力。然后走 tools/list拉到 get_current_time 的定义。模型看到这个工具描述后判断用户问时间决定调用它。Client 发 tools/call参数为空对象。Server 执行返回 ISO 时间字符串。模型拿到结果组织成自然语言回复你。如果你想在命令行里手动验证可以用 mcp 提供的客户端工具或者直接发 JSON-RPC 消息。手动发 initialize 的样子是这样{jsonrpc:2.0,id:1,method:initialize,params:{protocolVersion:2024-11-05,clientInfo:{name:manual-test,version:1.0},capabilities:{}}}Server 会返回它支持的协议版本和能力声明。接着发 tools/list{jsonrpc:2.0,id:2,method:tools/list}你会看到 get_current_time 的完整定义。最后发 tools/call{jsonrpc:2.0,id:3,method:tools/call,params:{name:get_current_time,arguments:{}}}返回结果里会有一个 content 数组里面是 TextContenttext 字段就是当前时间。走到这一步说明你的 MCP Server 已经能被正常发现和调用了。实测下来第一次跑通的关键不是代码多复杂而是配置里的 command 和 args 要跟你的实际启动方式完全一致。我见过不少人 config 里写 python -m mcp_server_demo但文件根本没做成模块结果 Host 拉不起来日志里只有一行 spawn ENOENT排查半天。7. 本篇常见错排查报错 unsupported protocol versionServer 返回的 protocolVersion 跟 Client 期望的不一致。检查你代码里 create_initialization_options 用的版本或者手动返回的版本号改成 2024-11-05 或 2025-03-26。Host 启动后 MCP Server 没反应先确认 command 能不能在终端里手动跑起来。如果手动跑报 ModuleNotFoundError说明模块路径不对改成绝对路径或先 pip install 你的包。tools/list 返回空数组检查 app.list_tools() 装饰器有没有生效函数是不是 async 的。同步函数在部分版本里不会被正确注册。tools/call 报未知工具name 参数跟 list_tools 里注册的名字要完全一致大小写敏感。别一个写 get_current_time另一个写 getCurrentTime。模型通道报 401 或鉴权失败回到 TaoToken 的 API Keys 页面确认 Key 没复制错base_url 是不是 https://taotoken.net/api 。可以先去模型对话页面发一条消息确认 Key 本身可用。stdio 通信卡住Server 里不要往 stdout 打印任何调试信息因为 stdout 被协议占用了。要打日志就写 stderr 或文件。8. 把原理落到可运行代码之后走到这里你已经有了一个能跑通的 MCP Server也理解了 Host、Client、Server 三者怎么协作。接下来可以做的扩展很直接把 get_current_time 换成查数据库、读文件、调内部 APIinputSchema 里加上参数定义call_tool 里做参数校验和错误处理。模型通道这边如果你要长期跑编码或 Agent 任务建议把 Key 和 base_url 统一走 TaoToken接入文档在 https://taotoken.net/doc API Keys 在 https://taotoken.net/api-keys 需要持续调用的话看 https://taotoken.net/coding-plan 。这样 MCP Server 只管工具逻辑模型调用统一管理两边不耦合换模型也不用改 Server 代码。最后一个实用技巧写 MCP Server 的时候先把工具描述写清楚。模型是靠 description 和 inputSchema 来决定调不调、怎么调的。描述写得含糊模型要么不调要么传错参数。把 description 当成给模型看的 API 文档来写调用成功率会高很多。