1. 为什么我要把 MCP 服务端和模型调用拆开接MCPModel Context Protocol说白了就是给 AI 应用装一个标准化的外设接口让模型能通过统一协议去读文件、查数据库、调工具。你可以把它理解成 AI 世界的 USB-C不管对面是 Claude Desktop、Cursor 还是你自己写的 Agent只要插上这个口工具就能被识别和调用。而 JSON-RPC 2.0 就是这根线里跑的电信号负责把「调用哪个工具、传什么参数、返回什么结果」讲清楚。但真正动手搭第一个 MCP 应用时很多人会卡在一个很现实的地方服务端骨架搭好了工具也注册了可一旦要让 MCP 服务端背后的逻辑去调用大模型Key 的管理就乱了。每个工具函数里塞一个 API Key环境变量散落各处换模型要改一堆代码。我这次的做法是MCP 服务端只负责协议和工具暴露模型调用统一走 TaoToken 的 API 通道用一个 Key 打通 Python SDK 和 JSON-RPC 两条链路。这篇是「从 0 到 1 构建 MCP 应用」的上篇目标很明确用 Python SDK 初始化一个 MCP 服务端配好 JSON-RPC 通信骨架再通过 TaoToken 统一 Key 完成一次模型调用接入最后跑通一次 JSON-RPC 握手验证。跟着做你能得到一个最小可用的 MCP 应用雏形而不是一堆看不懂的抽象概念。适合谁看写过一点 Python、听过 MCP 但没真正跑起来、想让自己的工具被 AI 调用的开发者。不需要你懂协议底层但需要你愿意动手敲命令。2. 前置准备TaoToken 统一 Key 与 Python 环境2.1 为什么用 TaoToken 统一 KeyMCP 服务端的一个典型场景是工具函数内部需要调用模型做二次处理比如「读取文件 → 让模型总结 → 返回摘要」。如果每个工具各自管 Key配置会非常碎。TaoToken 提供的是 OpenAI 兼容的 API 通道一个 Key 就能覆盖模型对话、编码等调用Python SDK 直接指向它的 base_url 即可不用为每个工具单独维护凭证。你需要先去控制台创建一个 API Key。入口在这里控制台创建 Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentconsole 接入文档base_url 与参数说明https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc创建完把 Key 存到环境变量里别硬编码进代码。API 基础地址是https://taotoken.net/api这个地址在后面的 config.toml 和 Python SDK 里都会用到。2.2 环境与依赖安装Python 版本要求 3.9 以上先确认一下python --version然后建项目目录和虚拟环境。虚拟环境这一步别省MCP SDK 和模型 SDK 的依赖版本容易互相干扰mkdir mcp-demo cd mcp-demo python -m venv venv source venv/bin/activate # Windows 用 venv\Scripts\activate安装核心依赖。mcp是官方 Python SDKopenai用来走 TaoToken 的兼容接口pip install mcp openai验证安装python -c import mcp; print(mcp.__version__)能打印版本号就说明 SDK 装好了。如果报ModuleNotFoundError八成是虚拟环境没激活重新source venv/bin/activate再试。3. 可复制配置config.toml 与 settings.json 骨架MCP 应用通常有两类配置一类是服务端自己的运行参数比如模型通道、超时一类是宿主应用如 Claude Desktop用来发现和启动 MCP 服务端的配置。我把它拆成两个文件职责清晰改起来不打架。3.1 config.toml服务端运行配置在项目根目录建config.toml把模型通道和 MCP 服务端的基础参数放进去# config.toml [model] # TaoToken 统一 API 通道 base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY # 从环境变量读取不写死 default_model gpt-4o-mini timeout 30 [mcp] server_name mcp-demo-server transport stdio # 本地开发先用 stdio log_level INFO [tools] # 工具级开关方便调试时单独关掉某个工具 enable_time_tool true enable_model_tool true这里的关键点是api_key_env配置文件里只存环境变量的名字真正的 Key 通过export TAOTOKEN_API_KEY你的Key注入。这样配置文件可以进版本库Key 不会泄露。3.2 settings.json宿主应用发现配置如果你要把这个 MCP 服务端挂到 Claude Desktop 或类似宿主里需要一个settings.json不同宿主文件名可能不同这里给通用骨架{ mcpServers: { mcp-demo-server: { command: python, args: [/absolute/path/to/mcp-demo/server.py], env: { TAOTOKEN_API_KEY: 从环境变量继承或在此填入 } } } }注意args里必须是绝对路径相对路径在宿主启动子进程时经常找不到文件这是新手最容易踩的坑之一。env字段用来把 Key 传给子进程如果宿主支持继承系统环境变量这里可以留空。4. 用 Python SDK 初始化 MCP 服务端并接入模型调用4.1 读取配置与初始化模型客户端先写一个配置加载模块config_loader.py把 config.toml 读进来同时初始化 TaoToken 的模型客户端# config_loader.py import os import tomllib # Python 3.113.9~3.10 用 tomli from openai import OpenAI def load_config(path: str config.toml) - dict: with open(path, rb) as f: return tomllib.load(f) def build_model_client(cfg: dict) - OpenAI: api_key os.environ.get(cfg[model][api_key_env]) if not api_key: raise RuntimeError(未找到 TAOTOKEN_API_KEY请先 export) return OpenAI( base_urlcfg[model][base_url], api_keyapi_key, timeoutcfg[model][timeout], )base_url指向https://taotoken.net/apiapi_key从环境变量取。这样模型客户端就统一了后面所有工具要调模型都复用这一个 client。4.2 初始化 MCP 服务端并注册工具创建server.py用 MCP Python SDK 初始化服务端注册两个工具一个纯本地的时间工具一个走 TaoToken 模型调用的总结工具。# server.py import asyncio from datetime import datetime from mcp.server import Server from mcp.server.stdio import stdio_server from config_loader import load_config, build_model_client cfg load_config() model_client build_model_client(cfg) app Server(cfg[mcp][server_name]) app.tool() async def get_current_time() - str: 获取当前精确时间包含时区信息 return datetime.now().isoformat() app.tool() async def summarize_text(text: str) - str: 调用模型对给定文本做一句话总结。 Args: text: 需要总结的原始文本 resp model_client.chat.completions.create( modelcfg[model][default_model], messages[ {role: system, content: 你是一个简洁的总结助手。}, {role: user, content: f用一句话总结{text}}, ], ) return resp.choices[0].message.content async def main(): async with stdio_server() as (read_stream, write_stream): await app.run( read_stream, write_stream, app.create_initialization_options(), ) if __name__ __main__: asyncio.run(main())这段代码里summarize_text就是「MCP 工具 模型调用」的结合点工具通过 JSON-RPC 被外部调用内部再用 TaoToken 通道请求模型。整个服务端只依赖一个 Key配置集中在 config.toml。4.3 JSON-RPC 通信骨架说明MCP 底层跑的是 JSON-RPC 2.0。当宿主调用summarize_text时实际发出的消息长这样{ jsonrpc: 2.0, id: 1, method: tools/call, params: { name: summarize_text, arguments: { text: MCP 是 AI 应用的标准外设接口 } } }服务端处理完返回{ jsonrpc: 2.0, id: 1, result: { content: [{ type: text, text: MCP 是 AI 应用的标准外设接口。 }] } }你不需要手写这些 JSONSDK 会帮你序列化和反序列化。但理解这个骨架排障时看日志就能对上号。5. 验证请求跑通一次 JSON-RPC 握手5.1 启动服务端先注入 Key再启动export TAOTOKEN_API_KEY你的Key python server.py如果没有任何报错、进程挂起等待输入说明 stdio 传输已经就绪。这一步没有输出是正常的因为 stdio 模式下服务端在等 JSON-RPC 消息。5.2 用 MCP Inspector 做握手验证官方调试工具 MCP Inspector 可以直接连上服务端验证协议握手和工具列表npx modelcontextprotocol/inspector python server.py它会打开一个本地 Web 界面。左侧应该能看到get_current_time和summarize_text两个工具。点开summarize_text填入一段文本点击调用。如果配置正确你会看到模型返回的一句话总结。这一步同时验证了三件事JSON-RPC 握手成功、工具注册成功、TaoToken 模型通道可用。任何一环断了这里都会报错。5.3 用 Python 客户端做程序化验证Inspector 适合手动测想写进自动化脚本可以用 SDK 的客户端# client_test.py import asyncio from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client async def main(): params StdioServerParameters(commandpython, args[server.py]) async with stdio_client(params) as (read, write): async with ClientSession(read, write) as session: await session.initialize() # JSON-RPC 握手 tools await session.list_tools() print(可用工具:, [t.name for t in tools.tools]) result await session.call_tool( summarize_text, {text: MCP 让模型能标准化地调用外部工具。}, ) print(模型返回:, result.content[0].text) if __name__ __main__: asyncio.run(main())运行python client_test.py如果打印出工具列表和模型总结说明整条链路通了。session.initialize()就是那次关键的 JSON-RPC 握手握手失败后面全免谈。6. 本篇常见错排查报错一ModuleNotFoundError: No module named mcp虚拟环境没激活或者装到了全局。重新source venv/bin/activate后pip install mcp。报错二RuntimeError: 未找到 TAOTOKEN_API_KEY环境变量没导出或者导出后换了终端窗口。echo $TAOTOKEN_API_KEY确认一下为空就重新 export。注意 Key 只在当前 shell 会话有效。报错三模型调用返回 401 或鉴权失败检查base_url是不是写成了https://taotoken.net/api末尾不要多加斜杠或路径。Key 复制时别带空格。可以到模型对话页面手动发一条消息确认 Key 本身可用模型对话验证https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmodel-chat报错四Inspector 里看不到工具装饰器app.tool()没加或者函数定义在main()之后。工具必须在app.run()之前注册。另外确认server.py没有语法错误python server.py能正常挂起。报错五宿主启动子进程时报「找不到文件」settings.json 里的args用了相对路径。改成绝对路径Windows 下注意反斜杠转义。报错六JSON-RPC 握手超时stdio 模式下服务端往 stdout 打印了非协议内容比如调试用的 print会污染 JSON-RPC 流。把所有调试输出改成写日志文件或 stderr。排障时如果怀疑是接入参数问题对照接入文档再核一遍 base_url 和鉴权头格式接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc7. 下一步把 Key 管好把链路跑顺到这一步你已经有了一个能跑的最小 MCP 应用Python SDK 初始化服务端、JSON-RPC 骨架通了、TaoToken 统一 Key 把模型调用接进来了。上篇的重点是「跑通」下篇会在这个骨架上加更多工具、处理并发调用、以及把服务端部署成可远程访问的形态。如果你打算长期做编码类或 Agent 类项目工具会越加越多模型调用也会越来越频繁这时候建议直接看 Coding Plan把额度管理和多模型切换一次性配好省得后面每个工具单独折腾Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding-plan另外Key 的管理建议一开始就规范起来控制台里给不同项目建不同的 Key方便按项目排查用量和吊销。入口在这API Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-keys先把今天这套 config.toml settings.json server.py 的组合跑顺下篇我们在这个基础上继续加料。