1. 为什么 MCP 值得你花一个下午搞懂如果你最近在折腾 AI 工具链大概率已经被各种「工具调用」「Function Calling」「插件」绕晕了。MCPModel Context Protocol想解决的就是这件事让大模型连接外部世界有一个统一插口就像 USB-C 一样不管你是接显示器、硬盘还是充电器接口形状一致协议一致插上就能用。MCP 是什么一句话它是一个开放协议规定了 AI 应用Host如何发现、调用、管理外部能力Server。能做什么把数据库、文件系统、内部 API、代码仓库这些能力用标准方式暴露给大模型不用每接一个数据源就写一套胶水代码。适合谁需要给 AI 工具统一接入多模型通道的 Python 开发者尤其是已经在用 Claude Desktop、Cursor、VS Code 这类支持 MCP 的宿主环境的人。我试过把几个内部服务用 MCP 包一层最大的感受是以前每个工具都要单独写 prompt 描述、单独处理参数校验、单独做错误返回现在这些全部收敛到一份inputSchema和一套 JSON-RPC 消息里。更关键的是模型通道也可以统一——用 TaoToken 的统一 Key 把模型调用收口MCP Server 只管暴露能力不碰模型凭证安全边界清晰很多。这篇会从协议原理讲到可运行代码给出config.toml与settings.json骨架、TaoToken 统一 Key 配置示例并演示一次可复制的连通性验证。目标很明确读完你能自己跑起来一个 MCP Server并让模型通过统一通道调用它。2. MCP 协议原理三层架构与四种能力2.1 Host-Client-Server 三层模型MCP 的架构不复杂但分工很讲究Host 是宿主环境比如 Claude Desktop、IDE 插件、你自己写的 Agent 应用。它负责管理多个 Client 实例、控制权限、协调 LLM 交互。Client 是协议连接器每个 Client 与一个 Server 建立 1:1 的有状态会话。注意是「有状态」这意味着初始化握手、能力协商、会话生命周期都有明确阶段。Server 是服务提供者对外暴露工具、资源、提示词模板。它可以是本地子进程也可以是远程 HTTP 服务。用一张简图理解Host (Claude Desktop / IDE / 自研 Agent) ├── Client 1 ── Server A (文件系统) ├── Client 2 ── Server B (数据库) └── Client 3 ── Server C (Web API)这种设计的价值在于隔离Server A 崩了不影响 Server B权限也可以按 Client 粒度控制。2.2 通信格式JSON-RPC 2.0MCP 底层用 JSON-RPC 2.0消息分三类RequestClient 到 Server要回复、ResponseServer 到 Client对应请求的回复、Notification双向不需要回复用于进度更新和状态变更。一条典型的工具调用请求长这样{ jsonrpc: 2.0, id: 1, method: tools/call, params: { name: query_database, arguments: { sql: SELECT * FROM users LIMIT 10 } } }id用于请求响应配对method是协议方法名params是参数体。整个协议的方法集不大核心就是initialize、tools/list、tools/call、resources/list、resources/read、prompts/list、prompts/get这几类。2.3 传输层Stdio 与 Streamable HTTP传输方式主要有两种还在广泛使用Stdio 适合本地进程间通信Server 作为子进程启动Host 通过 stdin 发请求、stdout 收响应、stderr 收日志。这是最简单也最常用的方式本地开发首选。Streamable HTTP 适合远程服务和 Web 应用支持流式传输能穿透常规网络环境。早期的 SSE 方案正在被它替代新项目建议直接用 Streamable HTTP。Stdio 的通信链路可以这样理解Host 启动 Server 进程 → stdin 发送 JSON-RPC 请求 → Server 处理 → stdout 返回响应 → stderr 输出日志不污染协议通道这里有个容易踩的坑如果你在 Server 里用print()调试输出会进 stdout直接破坏 JSON-RPC 消息格式Client 会解析失败。调试信息一律走 stderr或者用日志库写到文件。2.4 四大核心能力Tools 是最核心的能力允许 Server 暴露可执行操作供 LLM 调用。每个工具需要name、description、inputSchema三要素description 写得好不好直接决定模型会不会正确调用。Resources 类似 REST 的 GET 端点提供只读数据访问不触发副作用。通过 URI 唯一标识支持自定义 scheme比如db://、api://、file://。Prompts 是预定义的高质量提示词模板让用户可以主动选择使用适合把常见工作流固化下来。Sampling 是个很精妙的设计Server 可以反向请求 Host 进行 LLM 调用。这样 Server 端不需要直接持有模型 API Key避免了凭证泄露风险同时 Host 可以统一控制模型选择、token 预算和隐私策略。这一点和后面要讲的 TaoToken 统一 Key 思路是一致的——凭证收口在可信层能力层不碰密钥。3. TaoToken 前置统一 Key 与通道配置3.1 为什么 MCP 场景需要统一 KeyMCP 的 Sampling 能力让 Server 可以请求 Host 调模型但很多自研 Agent 场景里Host 本身就是你自己写的 Python 程序模型调用还是得自己发。这时候如果每个 Server、每个脚本都各自配一份模型 Key管理会非常乱轮换麻烦、权限不清、用量分散。TaoToken 的思路是提供一个统一 API 通道你用一份 Key 就能访问多个模型。对 MCP 项目来说这意味着模型调用层可以统一收口MCP Server 专注暴露能力不碰模型凭证。官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 基地址https://taotoken.net/api3.2 获取 Key 与可用入口先到控制台创建 API Key控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content创建后把 Key 存到环境变量不要硬编码进代码export TAOTOKEN_API_KEYsk-你的key如果你要验证模型通道是否通可以直接用模型对话页面试一条模型对话https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content长期做编码或 Agent 开发可以看 Coding PlanCoding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content接入文档在这里参数细节以文档为准接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content3.3 config.toml 骨架很多 Python 项目用config.toml管理配置下面是一份可直接改的骨架把模型通道和 MCP Server 配置分开[model] provider taotoken base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY default_model claude-sonnet-4-20250514 timeout_seconds 60 max_retries 3 [mcp] # MCP Server 启动配置 transport stdio [mcp.servers.db-query] command python args [db_server.py] enabled true [mcp.servers.fs] command python args [fs_server.py] enabled true [logging] level INFO # 日志写文件避免污染 stdio 协议通道 file mcp_demo.log关键点api_key_env指向环境变量名而不是 Key 本身这样配置文件可以进版本库logging.file把日志落盘避免 stdout 被污染。3.4 settings.json 骨架如果你用的是 Claude Desktop 或类似宿主配置走settings.jsonClaude Desktop 里叫claude_desktop_config.json。下面这份骨架同时演示了 MCP Server 注册和模型通道环境变量注入{ mcpServers: { db-query: { command: python, args: [/path/to/db_server.py], env: { DB_PATH: /path/to/data.db, TAOTOKEN_API_KEY: ${TAOTOKEN_API_KEY}, TAOTOKEN_BASE_URL: https://taotoken.net/api } }, fs: { command: python, args: [/path/to/fs_server.py], env: { ALLOWED_DIR: /path/to/project } } } }注意env里通过${TAOTOKEN_API_KEY}引用系统环境变量不要把明文 Key 写进 JSON。不同宿主对环境变量展开的支持程度不一样如果发现没生效改成在启动脚本里export后再拉起宿主。4. 可复制配置Python MCP Server 与 Client4.1 环境准备推荐用 uv 管理项目依赖解析快uv init mcp-demo cd mcp-demo uv add mcp[cli]用 pip 也行pip install mcp[cli]4.2 编写 Server数据库查询服务创建db_server.py暴露三个工具执行只读 SQL、列出表、查看表结构。注意所有调试输出走 stderr。import json import sqlite3 import sys from pathlib import Path from mcp.server import Server from mcp.server.stdio import stdio_server import mcp.types as types server Server(db-query-server) DB_PATH Path(__file__).parent / data.db def log(msg: str): # 关键日志走 stderr不污染 stdout 协议通道 print(msg, filesys.stderr) def get_db(): return sqlite3.connect(str(DB_PATH)) server.list_tools() async def handle_list_tools() - list[types.Tool]: return [ types.Tool( nameexecute_sql, description执行只读 SQL 查询仅支持 SELECT 语句返回 JSON 格式结果, inputSchema{ type: object, properties: { sql: { type: string, description: SQL 查询语句必须以 SELECT 开头 } }, required: [sql] } ), types.Tool( namelist_tables, description列出数据库中的所有表名, inputSchema{type: object, properties: {}} ), types.Tool( namedescribe_table, description查看指定表的字段结构包括字段名、类型、是否主键, inputSchema{ type: object, properties: { table_name: { type: string, description: 要查看结构的表名 } }, required: [table_name] } ) ] server.call_tool() async def handle_call_tool(name: str, arguments: dict) - list[types.TextContent]: conn get_db() cursor conn.cursor() try: if name execute_sql: sql arguments[sql].strip() if not sql.upper().startswith(SELECT): return [types.TextContent(typetext, text错误仅支持 SELECT 查询)] cursor.execute(sql) columns [desc[0] for desc in cursor.description] rows cursor.fetchall() result {columns: columns, rows: rows, count: len(rows)} return [types.TextContent( typetext, textjson.dumps(result, ensure_asciiFalse, indent2) )] elif name list_tables: cursor.execute(SELECT name FROM sqlite_master WHERE typetable) tables [row[0] for row in cursor.fetchall()] return [types.TextContent( typetext, textjson.dumps(tables, ensure_asciiFalse) )] elif name describe_table: table_name arguments[table_name] cursor.execute(fPRAGMA table_info({table_name})) columns cursor.fetchall() schema [ { name: col[1], type: col[2], not_null: bool(col[3]), primary_key: bool(col[5]) } for col in columns ] return [types.TextContent( typetext, textjson.dumps(schema, ensure_asciiFalse, indent2) )] return [types.TextContent(typetext, textf未知工具{name})] except Exception as e: # 错误通过 isError 语义返回不抛异常 return [types.TextContent(typetext, textf执行失败{str(e)})] finally: conn.close() async def main(): log(db-query-server 启动等待 stdio 连接) async with stdio_server() as (read_stream, write_stream): await server.run( read_stream, write_stream, server.create_initialization_options() ) if __name__ __main__: import asyncio asyncio.run(main())4.3 编写 Client连接并调用创建db_client.py演示完整的初始化、列工具、调工具流程import asyncio from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client async def main(): server_params StdioServerParameters( commandpython, args[db_server.py] ) async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: # 初始化握手协商能力 await session.initialize() # 列出可用工具 tools await session.list_tools() print(可用工具) for tool in tools.tools: print(f - {tool.name}: {tool.description}) # 调用 list_tables result await session.call_tool(list_tables, {}) print(f\n数据库表{result.content[0].text}) # 调用 execute_sql result await session.call_tool( execute_sql, {sql: SELECT * FROM users LIMIT 5} ) print(f\n查询结果{result.content[0].text}) if __name__ __main__: asyncio.run(main())4.4 模型通道接入统一 Key 调用如果你的 Agent 需要在 MCP 工具调用之外直接调模型用统一通道收口。下面是一个最小调用示例基地址指向 TaoTokenimport os from openai import OpenAI client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlhttps://taotoken.net/api ) resp client.chat.completions.create( modelclaude-sonnet-4-20250514, messages[ {role: user, content: 用一句话解释 MCP 协议的作用} ] ) print(resp.choices[0].message.content)这样模型凭证只在一处配置MCP Server 通过 Sampling 或 Host 层统一调用不会散落到各个 Server 里。5. 验证请求与成功结果5.1 准备测试数据库先造一个data.db方便验证python -c import sqlite3 conn sqlite3.connect(data.db) c conn.cursor() c.execute(CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT, email TEXT)) c.execute(\INSERT INTO users (name, email) VALUES (张三, zhangsanexample.com)\) c.execute(\INSERT INTO users (name, email) VALUES (李四, lisiexample.com)\) conn.commit() conn.close() print(data.db 初始化完成) 5.2 运行 Client 验证python db_client.py预期输出可用工具 - execute_sql: 执行只读 SQL 查询仅支持 SELECT 语句返回 JSON 格式结果 - list_tables: 列出数据库中的所有表名 - describe_table: 查看指定表的字段结构包括字段名、类型、是否主键 数据库表[users] 查询结果{ columns: [id, name, email], rows: [[1, 张三, zhangsanexample.com], [2, 李四, lisiexample.com]], count: 2 }看到这个输出说明 stdio 传输、JSON-RPC 消息、工具注册、参数校验、结果返回整条链路都通了。5.3 验证模型通道单独验证统一 Key 是否可用python -c import os from openai import OpenAI client OpenAI(api_keyos.environ[TAOTOKEN_API_KEY], base_urlhttps://taotoken.net/api) resp client.chat.completions.create( modelclaude-sonnet-4-20250514, messages[{role: user, content: 回复 OK 两个字母即可}] ) print(resp.choices[0].message.content) 返回内容里出现 OK说明模型通道正常。如果报 401检查 Key 是否过期如果报连接错误检查 base_url 是否写成了https://taotoken.net/api注意结尾没有斜杠。5.4 集成到宿主环境把 Server 注册到 Claude Desktop 的配置文件macOS 路径~/Library/Application Support/Claude/claude_desktop_config.jsonWindows 路径%APPDATA%\Claude\claude_desktop_config.json{ mcpServers: { db-query: { command: python, args: [/absolute/path/to/db_server.py], env: { DB_PATH: /absolute/path/to/data.db } } } }重启宿主后直接用自然语言问「帮我查一下 users 表里有哪些人」模型会自动调用execute_sql工具完成查询。这里路径一定要用绝对路径相对路径在宿主启动子进程时工作目录不确定很容易找不到文件。6. 本篇常见错排查6.1 Client 报 JSON 解析失败最常见的原因是 Server 里用了print()往 stdout 输出调试信息。JSON-RPC 要求 stdout 只能有协议消息任何多余字符都会导致解析失败。解决办法所有日志走sys.stderr或者用 logging 写到文件。6.2 工具列表为空检查server.list_tools()装饰器是否注册成功以及initialize()是否在list_tools()之前调用。MCP 是有状态会话没握手就列工具Server 可能还没完成能力协商。6.3 调用工具报「未知工具」工具名大小写敏感execute_sql和Execute_SQL是两个不同的名字。另外确认 Client 调用的名字和 Server 注册的name字段完全一致。6.4 模型通道 401 或 403先确认环境变量TAOTOKEN_API_KEY在当前 shell 里能读到echo $TAOTOKEN_API_KEY如果为空说明 export 没生效或者宿主启动时没继承环境变量。Claude Desktop 这类 GUI 应用不一定继承你终端里的环境变量需要在配置文件的env字段里显式传入或者写进系统级环境变量后重启应用。6.5 连接超时检查 base_url 是否写对。正确写法是https://taotoken.net/api不要多加路径后缀也不要漏掉协议头。如果网络环境有代理确认代理配置不会拦截该域名。6.6 Server 启动后立即退出多半是asyncio.run(main())没被调用或者stdio_server()上下文没正确进入。检查if __name__ __main__:块是否存在以及main()里是否await server.run(...)。6.7 数据库文件找不到DB_PATH用相对路径时工作目录取决于宿主怎么启动子进程。统一改成绝对路径或者在 Server 里用Path(__file__).parent / data.db基于脚本位置解析。7. 继续往下走接入文档与 Coding PlanMCP 的上手成本确实低一个 Python 文件就能写出可用 Server但它的想象空间在于标准化带来的组合能力任何可以被 API 化的能力都能通过 MCP 无缝接入大模型。而模型通道这一层用统一 Key 收口之后你的 MCP 项目就只需要关心「暴露什么能力」不用再操心「用哪个模型、Key 怎么管」。如果你在接入过程中遇到参数问题优先查接入文档接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content想先验证模型通道是否通用模型对话页面发一条消息最快模型对话https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content如果你打算长期做编码类 Agent 或 MCP 工具链开发Coding Plan 会更合适Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content最后给一个实操建议先把db_server.py跑通确认 stdio 链路没问题再往里面加 Resources 和 Prompts。Tools 是最容易验证的部分Resources 涉及 URI 设计Prompts 涉及模板参数一步步来不容易乱。等这三个都跑顺了再考虑 Sampling 和远程 Streamable HTTP 传输那时候你对协议的理解已经足够支撑更复杂的架构了。
