1. 为什么大模型需要 MCP 这层“外挂”大模型本身只会“说”不会“做”。你问它今天数据库里有多少用户它能给你编一个看起来很像真的数字但它没法真的去查。MCPModel Context Protocol就是解决这个问题的标准协议它把外部能力查数据库、调接口、跑脚本包装成模型能看懂的工具清单模型自己决定什么时候调用、传什么参数。适合谁适合正在做本地 Agent、想让 LLM 真正操作数据的开发者尤其是用 LangChain/LangGraph 这套技术栈的人。我试过最直观的场景让模型自己判断“892 等于几”这种纯计算题不查库而“帮我查 users 表里年龄最小的是谁”就自动去执行 SQL。整个过程不需要你写 if-else 路由模型通过 ReAct 模式自己完成 Reason Act。这篇就按这个场景从零把 MCP 服务端、客户端注册、统一 Key 接入、调用验证、报错排查全部跑一遍。核心链路分三段第一段写一个 MySQL MCP 服务用 fastmcp 把 SQL 执行封装成 tool第二段用 MultiServerMCPClient 把服务注册进客户端配合 create_react_agent 让模型自主选工具第三段把大模型请求地址和 Key 统一到 TaoToken避免每个项目到处散落 sk-xxx。跑通之后你会得到一个闭环用户输入 → 模型判断 → 调用 MCP → 返回真实结果。环境准备不复杂Python 3.10 即可依赖一次装齐pip install pymysql fastmcp langchain langchain-openai langgraph langchain-mcp-adapters本地 MySQL 要能连上建一个 test_db 库和 users 表随便塞几条数据。这一步别偷懒后面验证全靠它。MCP 服务端和客户端是两个独立进程通过 stdio 通信所以路径、命令、参数三者必须对得上这是后面 90% 报错的根源。2. TaoToken 统一 Key 的前置准备与接入文档在写客户端之前先把大模型这一侧的接入方式定下来。很多人的痛点是MCP 工具写好了但模型请求地址和 Key 散落在各个脚本里换一个模型就要改一遍 base_url。TaoToken 的作用就是提供一个统一的 Key 和入口模型对话、编码、Agent 调用都走同一套凭证配置一次到处复用。你需要先拿到两样东西API Key 和 Base URL。Key 在控制台的 API Keys 页面创建Base URL 统一用https://taotoken.net/api。注意这里不要带任何多余路径OpenAI 兼容的客户端会自动拼/v1/chat/completions这类后缀。创建 Key 的入口在这里控制台 API Keyshttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite拿到 Key 之后建议先别急着写 Agent用最小请求验证一下 Key 和地址是否通。可以直接用 curl 打一发curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d { model: gpt-4o, messages: [{role: user, content: 只回复 ok}] }返回里能看到choices[0].message.content就说明 Key 没问题。这一步很关键因为后面 Agent 报错时你分不清是 MCP 的问题还是 Key 的问题先把模型侧单独验证掉排障范围直接砍一半。模型名称Model ID要和你实际要用的保持一致比如gpt-4o、claude-3-5-sonnet这类。TaoToken 的接入文档里有完整的模型列表和参数说明配置前扫一眼能省很多试错接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite如果你后面要做长期编码或 Agent 任务可以考虑 Coding Plan额度模型和按量调用不一样适合高频跑 Agent 的场景Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite前置准备就三件事Key、Base URL、Model ID。这三个值后面会同时出现在客户端配置里建议先写进环境变量别硬编码在脚本里不然提交代码时容易泄露。3. 可复制的 MCP 服务端与客户端配置先写服务端mysql_mcp.py。核心是用 fastmcp 初始化一个服务把 SQL 执行封装成app.tool()装饰的函数模型看到的就是这个函数的描述和参数。数据库连接配置单独抽出来方便改import pymysql from fastmcp import FastMCP import json app FastMCP(MySQL MCP) DB_CONFIG { host: 127.0.0.1, user: root, port: 3308, password: 123456, database: test_db, charset: utf8mb4, cursorclass: pymysql.cursors.DictCursor } def run_query(sql: str): conn pymysql.connect(**DB_CONFIG) try: with conn.cursor() as cursor: cursor.execute(sql) if sql.strip().lower().startswith(select): rows cursor.fetchall() return {rows: json.loads(json.dumps(rows, defaultstr))} else: conn.commit() return {status: success, rows_affected: cursor.rowcount} finally: conn.close() app.tool() def query_mysql(sql: str) - dict: 执行 MySQL 查询语句 参数: sql: 要执行的 SQL 语句 (SELECT / INSERT / UPDATE / DELETE) try: return run_query(sql) except Exception as e: return {error: str(e)} if __name__ __main__: app.run(transportstdio)注意transportstdio这是本地进程间通信方式客户端会用同样的方式启动它。端口 3308 是我本地 MySQL 的映射端口你按自己的改。test_db和users表要提前建好否则第一次调用就会返回连接或表不存在的错误。再写客户端test_mcp.py。这里把 Base URL、Key、Model ID 三件套集中配置MCP 服务通过MultiServerMCPClient注册指定启动命令和脚本绝对路径import asyncio import os from langchain_mcp_adapters.client import MultiServerMCPClient from langgraph.prebuilt import create_react_agent from langchain_openai import ChatOpenAI BASE_URL https://taotoken.net/api API_KEY os.getenv(TAOTOKEN_API_KEY, sk-你的Key) MODEL_NAME gpt-4o async def main(): try: client MultiServerMCPClient({ MySQL-MCP: { command: python, args: [os.path.abspath(mysql_mcp.py)], transport: stdio } }) tools await client.get_tools() if not tools: raise ValueError(未获取到任何工具) llm ChatOpenAI( base_urlBASE_URL, openai_api_keyAPI_KEY, modelMODEL_NAME, timeout60.0, max_retries2 ) agent create_react_agent(llm, tools) while True: user_input input(\n请输入需求或输入 exit 退出\n ) if user_input.strip().lower() exit: break async for chunk in agent.astream({messages: user_input}): print(chunk) except Exception as e: print(f程序初始化失败: {e}) if __name__ __main__: asyncio.run(main())三件套对照表配置时逐项核对配置项值说明Base URLhttps://taotoken.net/api不带 /v1 后缀客户端自动拼API Key控制台创建建议走环境变量Model ID如gpt-4o与文档列表一致MultiServerMCPClient的 key这里是MySQL-MCP只是内部标识可以同时注册多个服务比如再加一个 Redis 或 Web API模型会在多个工具里自己挑。create_react_agent负责把工具清单塞进模型的上下文模型按 Reason Act 循环决定调用哪个。4. 验证请求与成功结果配置写完先跑服务端确认它能独立启动python mysql_mcp.py如果卡住不动是正常的stdio 模式在等客户端连接。接着另开一个终端跑客户端export TAOTOKEN_API_KEYsk-你的Key python test_mcp.py第一次输入先来个纯计算题验证模型不会乱调工具请输入需求或输入 exit 退出 892等于几预期结果是模型直接回答 91不触发 MySQL 工具。这一步验证的是模型的判断能力如果它跑去查库了说明工具描述写得太宽泛把query_mysql的 docstring 收窄一点。再来真实查询 帮我查询users表有哪些数据正常会看到 astream 输出里出现 tool_call参数是{sql: SELECT * FROM users}然后工具返回 rows模型把结果整理成自然语言。接着试一个需要推理的 帮我查询users表中年龄最小的是谁模型会自己生成SELECT * FROM users ORDER BY age ASC LIMIT 1这类 SQL而不是让你手写。最后试建表写入 帮我创建一个book表并写入一些数据模型会先CREATE TABLE再INSERT返回rows_affected。到这里闭环就跑通了用户输入 → 模型判断 → 调用 MCP → 真实执行 → 结果回传。验证成功的标志有三个get_tools()返回非空列表、astream 里能看到 tool_call 和 tool_result、数据库里确实多了数据。三个都满足说明服务端、客户端、Key 三侧全部打通。5. 本篇常见报错排查清单排障按“先模型侧、再 MCP 侧、最后路径”的顺序能最快定位。401 UnauthorizedKey 错了或没带上。检查Authorization: Bearer sk-xxx是否完整环境变量是否真的导出成功。用第 2 节的 curl 单独验证curl 通了说明 Key 没问题问题在客户端代码。local proxy failed / connection refusedBase URL 写错常见的是多写了/v1或少了https。统一用https://taotoken.net/api让客户端自己拼路径。reading choices 报错 / 返回体解析失败通常是模型名不对或者返回的不是标准 OpenAI 格式。核对 Model ID 是否在文档列表里别自己编一个。OAuth / 认证相关报错如果你用的是 Claude Code 这类工具认证方式可能不是纯 Key。Claude Code 接入时三件套要写全Base URL、Key、Model ID缺一个都会认证失败。参考接入文档里的 ClaudeCodeAnthropic 配置说明。未获取到任何工具get_tools()返回空。检查mysql_mcp.py路径是否是绝对路径command用的python是否在当前环境可用。可以手动python mysql_mcp.py看是否报错。数据库连接失败端口、密码、库名对不上。先在本地用mysql -h127.0.0.1 -P3308 -uroot -p手动连一次确认能连上再跑 MCP。SQL 执行报错但模型说成功工具里except把错误吞了返回{error: ...}模型可能没正确解读。把错误信息打印出来看别只看模型回复。排障时记住一个原则模型侧和 MCP 侧分开验证。curl 验证模型手动跑服务端验证 MCP两边都单独通了再合起来问题一定出在连接处。6. 从跑通到用起来统一 Key 与后续扩展跑通第一个闭环之后真正省事的地方在于统一 Key。你后面再加 Redis MCP、Web API MCP模型侧完全不用改还是同一个 Base URL 和 Key只在MultiServerMCPClient里多注册一个服务就行。工具越多模型自主编排的价值越大。想验证更多模型或对比不同模型在 Agent 场景下的表现可以直接在模型对话里试模型对话https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite长期跑编码或 Agent 任务按量调用成本会上去Coding Plan 更适合高频场景。Key 和文档入口再放一次方便你直接跳API Keyshttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite最后提醒一句这个 MySQL MCP 只适合学习生产环境一定要加 SQL 执行限制比如只允许 SELECT、禁止 DROP/DELETE或者加白名单。模型再聪明也可能生成不可逆的语句权限收窄是底线。把工具描述写清楚、把危险操作挡在服务端才是能长期用的 Agent 闭环。