1. 从零写一个 Python MCP 服务为什么本地调试和线上调用总在 Key 上翻车如果你正在搜「python创建MCP服务 Dify1.6配置MCP服务工具」大概率已经踩过这样一个坑本地用 Python 写了个 MCP server跑起来挺顺结果一接到 Dify 1.6 的工具节点上要么连不上要么连上了但调用模型时 Key 又对不上。更烦的是本地调试用一套 Key线上 Dify 调用又换一套改来改去最后自己都记不清哪个 Key 对应哪个环境。MCPModel Context Protocol本质上是给大模型外挂「工具手」的一套协议。你可以把它理解成模型本身只会聊天但通过 MCP它能去查系统时间、读数据库、调内部接口。Python 因为生态好、写起来快成了很多人写 MCP 服务的首选语言。而 Dify 1.6 对 MCP 工具的支持让「低代码编排 自定义工具」这条路变得可行。问题就出在「统一」两个字上。一个最小可用的链路是这样的Python MCP server 暴露 SSE 接口 → Dify 1.6 把它注册成工具 → ChatFlow 里调用这个工具 → 工具内部如果还要调模型比如做二次总结又需要一个模型 Key。这三段里Key 分散在 MCP server 的环境变量、Dify 的模型供应商配置、以及可能的线上部署环境里。本地调试时你用的是测试 Key线上跑的是生产 Key一旦混用轻则 401重则调用到一半报local proxy failed。这篇就按「先跑通、再统一」的顺序来。我会先给你一份可以直接复制的 Python MCP server 骨架查系统时间 查系统信息两个工具然后讲 Dify 1.6 里怎么填字段最后把 TaoToken 的统一 Key 接进去让本地和线上共用一套凭证。全程不涉及任何网络加速工具纯本地 平台配置。适合谁看写过一点 Python、用过 Dify、想把自己的脚本变成模型可调用工具的人。不需要你懂 MCP 协议细节照着填就能跑。2. TaoToken 前置准备统一 Key 在 MCP Dify 链路里放在哪在动手写代码之前先把「Key 放哪」这件事想清楚否则后面一定返工。整条链路里需要模型能力的地方其实有两处。第一处是 Dify 里的 LLM 节点它负责理解用户意图、决定要不要调工具、以及把工具返回的结果组织成自然语言。第二处是你的 MCP 工具内部如果工具有「二次加工」需求比如把查到的系统信息丢给模型总结成一句话它自己也要能调模型。很多人只配了 Dify 的模型忘了工具内部也要 Key结果工具一执行就报认证失败。TaoToken 在这里的作用是提供一个统一的 API 入口和一套 Key让上面两处都指向同一个 Base URL 和同一个 Key。这样本地调试时你 export 的环境变量和线上 Dify 里填的是同一套东西不用来回切。具体要准备三样第一一个 TaoToken 的 API Key。去控制台的 API Keys 页面创建复制出来形如sk-xxxx的字符串。这个 Key 后面既填进 Dify 的模型供应商也写进 MCP server 的环境变量。第二确认 Base URL。TaoToken 的 API 入口是https://taotoken.net/api注意这个地址不带任何查询参数直接作为 OpenAI 兼容的 base_url 使用。如果你用的是 Anthropic 风格的调用比如 Claude Code 那类走的是另一套路径但本文的 MCP Dify 场景用 OpenAI 兼容格式就够了。第三想清楚 Model ID。Dify 里配置模型时需要填具体模型名比如claude-sonnet-4-5这类。你可以在模型对话页面先试一下哪个模型可用、返回正常再去 Dify 里填。别在 Dify 里盲填一个不存在的模型名否则报错信息会很含糊。提示把 Key 写进代码是坏习惯。MCP server 里用os.environ.get(TAOTOKEN_API_KEY)读取本地用.env或 shell export线上用部署平台的环境变量。这样同一份代码在两个环境都能跑。如果你还没创建 Key可以先到 API Keys 页面生成一个再回来继续。接入文档里对 Base URL 和鉴权头有更细的说明遇到 401 时对照着看。3. 可复制配置Python MCP server 骨架 Dify 1.6 工具字段这一节是全文的核心给你两份可以直接抄的东西一份 Python MCP server 代码一份 Dify 1.6 的工具配置字段说明。先看 Python 侧。下面这个query_system_info.py用fastmcp库定义了两个工具查当前系统时间、查系统版本信息。代码里预留了 TaoToken 的环境变量读取位置方便你后续在工具内部调模型。import os import platform import asyncio from datetime import datetime from fastmcp import FastMCP # 统一 Key本地 export线上用部署平台环境变量 TAOTOKEN_API_KEY os.environ.get(TAOTOKEN_API_KEY, ) TAOTOKEN_BASE_URL os.environ.get(TAOTOKEN_BASE_URL, https://taotoken.net/api) mcp FastMCP(name查询服务器信息MCP) mcp.tool( nameget_system_time, description获取当前系统的时间和日期 ) async def get_system_time(): 获取当前系统时间的工具函数 current_time datetime.now().strftime(%Y-%m-%d %H:%M:%S) return { status: success, data: {system_time: current_time}, message: 当前系统时间获取成功 } mcp.tool( nameget_system_info, description获取当前系统的版本和相关信息 ) async def get_system_info(): 获取系统版本信息的工具函数 system_info { system: platform.system(), node: platform.node(), release: platform.release(), version: platform.version(), machine: platform.machine(), processor: platform.processor() } return { status: success, data: system_info, message: 系统版本信息获取成功 } if __name__ __main__: # 使用 SSE 传输Dify 1.6 通过 SSE 地址接入 mcp.run(transportsse, host0.0.0.0, port8123)装依赖、启动pip install fastmcp python3 query_system_info.py启动后你会看到类似Uvicorn running on http://0.0.0.0:8123的日志说明 SSE 服务已经在 8123 端口监听。注意host0.0.0.0是为了让 Dify 能访问到如果你只在本地测用127.0.0.1也行但 Dify 在容器里跑的话必须用0.0.0.0加宿主机 IP。再看 Dify 1.6 侧。进入 Dify 平台找到「工具」或「MCP 服务」入口创建 MCP 服务需要填的字段如下字段填什么说明名称查询服务器信息MCP自定义方便识别类型SSEDify 1.6 支持 SSE 接入SSE 地址http://你的IP地址:8123/sse注意末尾/sse不能少鉴权按需本地测试可先不填超时30s工具执行慢可调大这里最容易错的是 SSE 地址。很多人只填http://IP:8123少了/sseDify 会连不上。另外你的IP地址要填 Dify 能访问到的地址如果 Dify 和 MCP server 在同一台机器用127.0.0.1如果 Dify 在 Docker 里用宿主机的局域网 IP别用localhost。如果你用的是 Cline MCP 或 Claude Code 那类客户端配置格式不太一样通常是 JSON 或 TOML。以 Cline MCP 为例配置片段长这样{ mcpServers: { query-system-info: { url: http://127.0.0.1:8123/sse, type: sse } } }而 Claude Code 的配置走的是另一套通常在settings.json里声明 MCP server。不管哪种客户端三件套都是Base URLSSE 地址、Key如果服务端要鉴权、Model ID工具内部调模型时用。这三样在 TaoToken 体系里可以统一成一套省得每个客户端配一遍。注意Dify 1.6 的 MCP 工具节点在 ChatFlow 里引用时工具列表是动态拉取的。如果创建 MCP 服务后看不到工具先点一下「刷新」或重新保存让 Dify 重新请求/sse拉取工具清单。4. 验证请求从本地 curl 到 Dify 工具调用的完整链路配置填完不代表通了必须走一遍完整验证。我习惯分三步先本地直连 MCP server再在 Dify 里单测工具节点最后在 ChatFlow 里跑一次真实对话。第一步本地验证 SSE 服务活着。用 curl 请求 SSE 端点curl -N http://127.0.0.1:8123/sse-N表示不缓冲你会看到持续输出的event: endpoint之类的事件流。如果卡住没输出说明服务没起来或端口不对。这一步只验证「服务在监听」不验证工具逻辑。第二步在 Dify 的工具页面点「测试」。Dify 1.6 会列出从 MCP server 拉到的工具选中get_system_time点运行。正常返回类似{ status: success, data: {system_time: 2025-09-23 14:32:10}, message: 当前系统时间获取成功 }如果这里报local proxy failed八成是 Dify 访问不到你的 MCP server 地址。检查三件事IP 是不是 Dify 能路由到的、端口有没有被防火墙挡、/sse后缀有没有漏。如果报reading choices之类的错误通常是工具返回结构不符合 Dify 预期确认返回的是合法 JSON。第三步在 ChatFlow 里引用。新建一个 ChatFlow加一个 LLM 节点在提示词里说明「你可以调用 get_system_time 工具获取时间」。然后在工具节点里挂上刚才创建的 MCP 服务。测试对话输入「现在几点了」观察 LLM 节点是否触发工具调用、工具返回后 LLM 是否把结果组织成自然语言。这一步如果 LLM 不调工具常见原因是提示词没引导、或者模型本身对工具调用支持不好。换个模型试试或者在提示词里更明确地写「必须调用工具获取时间不要自己编」。整个链路跑通后你会看到类似这样的执行日志用户提问 → LLM 决定调get_system_time→ MCP server 返回时间 → LLM 输出「现在是 2025-09-23 14:32:10」。到这一步本地调试和 Dify 调用就共用同一套 MCP 服务了。如果你在工具内部还要调模型做二次加工就在get_system_info里加一段用TAOTOKEN_API_KEY和TAOTOKEN_BASE_URL发请求的逻辑指向https://taotoken.net/api。这样工具内部的模型调用和 Dify 的模型调用走同一个入口Key 也统一了。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth跑这条链路报错基本集中在四类。我把真实遇到过的现象和排查路径列出来你对号入座。401 Unauthorized。这个最直接Key 不对或没传。分两种情况如果报错发生在 Dify 的 LLM 节点检查 Dify 模型供应商里填的 API Key 是不是 TaoToken 的 Key、Base URL 是不是https://taotoken.net/api。如果报错发生在 MCP 工具内部检查TAOTOKEN_API_KEY环境变量有没有 export 成功可以在代码里加一行print(bool(TAOTOKEN_API_KEY))确认。注意 Key 前后不要有空格复制时容易带上换行。local proxy failed。这个报错和网络代理无关别被名字误导。它通常表示 Dify 无法建立到 MCP server 的连接。排查顺序先在 Dify 所在机器上curl http://你的IP:8123/sse能通说明网络没问题不通就查 IP 和端口。Docker 部署的 Dify 访问宿主机服务要用宿主机的局域网 IP不能用127.0.0.1因为容器里的 localhost 是容器自己。reading choices 相关报错。这类错误一般出现在工具返回结果被 Dify 解析时。Dify 期望工具返回结构化的 JSON如果你的工具返回了非 JSON 字符串、或者 JSON 里字段类型不对就会解析失败。检查get_system_time的返回确保是dict而不是字符串拼接。另外status字段建议保留Dify 有些版本会读它判断成功与否。OAuth 相关报错。如果你在 Dify 里给 MCP 服务开了鉴权但 MCP server 没实现对应的 OAuth 流程就会报这个。本地调试阶段建议先关掉鉴权跑通再说。线上要开鉴权的话MCP server 侧需要实现 token 校验逻辑这部分超出最小示例范围可以后续单独加。还有一个隐蔽的坑MCP server 启动后如果你改了代码但没重启Dify 拉到的还是旧工具列表。改完代码记得CtrlC停掉再python3 query_system_info.py重启然后在 Dify 里刷新工具。提示排查时养成看两边日志的习惯。MCP server 侧的 uvicorn 日志会打印每个请求Dify 侧的执行日志会显示工具调用入参和返回。两边对着看问题定位快很多。6. 把 Key 收拢到一处长期编码与 Agent 场景的接入建议最小链路跑通后真正省心的是把 Key 收拢。本地调试、Dify 线上、以及你后续可能接的 Cline MCP、Claude Code 这些客户端全部指向同一个 Base URL 和同一套 Key。这样换 Key 时只改一处不用满世界找配置。具体做法本地用.env文件管理TAOTOKEN_API_KEY和TAOTOKEN_BASE_URLMCP server 启动时加载Dify 的模型供应商里填同样的 Base URL 和 Key其他客户端的配置里也填同一套。Model ID 可以按场景选但入口统一。如果你后面要做更复杂的 Agent 编排比如多个 MCP 工具串联、或者工具内部多次调模型建议把模型调用封装成一个公共函数统一从环境变量读 Key 和 Base URL。这样无论工具被 Dify 调还是被别的客户端调行为一致。需要长期跑编码类任务或 Agent 的可以看下 Coding Plan它适合把模型能力稳定接进日常开发流。只是验证模型连通性的模型对话页面点几下就能试。配置过程中卡在 Key 或地址上的接入文档里有字段说明API Keys 页面可以随时新建和轮换 Key。最后留一个实用习惯每次改完 MCP server 代码先本地curl一下/sse确认服务活着再去 Dify 点测试。两步都过了再进 ChatFlow 跑对话。这个顺序能帮你把「服务问题」和「编排问题」分开省掉大量来回试的时间。