1. 为什么要在 Dify 里接 MCP Server：从手写客户端到插件一键接入
如果你最近在折腾 Agent 工具链，大概率会遇到一个尴尬：MCP Server 写好了，本地用客户端跑得挺顺，但一到 Dify 里就不知道从哪下手。我一开始的想法也很朴素——直接接口调用不就行了？结果发现 Dify 的插件市场里已经有人把这件事做成了图形化操作，搜一下 MCP 就能看到 ReAct（支持 MCP 工具）、MCP Server、AntV 可视化图表这几类插件。其中 ReAct 插件就是本篇的主角，它让 Dify 的 Agent 节点直接具备调用外部 MCP Server 的能力，不用你写一行胶水代码。
先说清楚 MCP 是什么。MCP（Model Context Protocol）可以理解成一套“工具插座标准”：你的 MCP Server 把能力（查数据库、调 Prometheus、读文件、发请求）按统一协议暴露出来，任何支持 MCP 的客户端都能插上去用。Dify 通过 ReAct 插件扮演的就是这个“客户端”角色。适合谁？适合已经有一个部署好的 MCP Server、想在 Dify 里快速搭出 Agent 工具链的开发者；也适合不想维护自研调用层、希望用可视化方式编排工具调用的团队。
Dify 里支持 MCP 调用的应用类型有三种：工作流（Workflow）、Chatflow、Agent 智能助手。实际测试下来，核心调用都发生在 Agent 节点或 Agent 应用里——工作流里也是靠一个 Agent 节点去承接 MCP 工具。所以你可以理解为：Dify 负责编排和界面，ReAct 插件负责把 MCP 工具“翻译”给 Agent 用，Agent 负责决定什么时候调哪个工具。
这里有个前置认知很重要：MCP Server 的地址不能填127.0.0.1。因为 Dify 如果是容器化部署，127.0.0.1指向的是 Dify 容器自己，不是你的宿主机。这个坑后面排障章节会专门讲。另外，多工具鉴权如果每个都单独配 Key，管理起来会很碎，我在实践里用 TaoToken 做统一 Key/API 通道，把模型调用和工具链的鉴权收敛到一处，后面 §2 会展开。
本篇交付三样东西：可复制的插件配置参数、MCP Server 连接验证步骤、以及时间字段踩坑的排查清单。时间这块是重灾区，我第一次调试时 Agent 汇总出来的报告时间直接是 16 开头的年份，差了一年，最后靠时区设置 + 时间工具 + 提示词限定才掰回来。
2. TaoToken 统一 Key 通道：多工具鉴权的前置准备
在正式配 Dify 插件之前，先把鉴权通道理顺，不然后面每接一个工具就要翻一次 Key，很容易乱。TaoToken 在这里的角色是统一 Key/API 通道：你用它生成一个 Key，然后在 Dify 的模型供应商配置、以及需要走模型能力的工具链里复用同一个通道，减少多工具各自维护鉴权的成本。官网入口是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 地址是 https://taotoken.net/api （这个不加 UTM）。
具体怎么落地？分两步。第一步，在 TaoToken 控制台创建 API Key，路径是 console 页面，进去后找 API Keys 管理。第二步，回到 Dify，在“设置 → 模型供应商”里选择兼容 OpenAI 接口的供应商类型，把 Base URL 填成https://taotoken.net/api，API Key 填你刚创建的那串，Model ID 按你实际要用的模型填。这三件套（Base URL + Key + Model ID）是后面所有配置的基准，缺一个都会报鉴权或模型找不到的错。
如果你用的是 Claude Code 这类编码工具，TaoToken 也提供对应的接入方式，Base URL 同样是https://taotoken.net/api，Key 复用同一个，Model ID 按工具要求填。这样你在 Dify 里跑 Agent、在本地跑编码助手，用的是同一套鉴权，不用记多套 Key。对于长期编码和 Agent 场景，可以考虑 Coding Plan，把额度集中管理；如果只是想先验证模型通不通，用模型对话页面快速发一条请求就行。
这里要强调一个安全边界：TaoToken 是合规的 API 通道，不是所谓“中转”灰产，你按官方文档配置即可。配置完成后，建议先在 Dify 的模型供应商里点“测试”或发一条最小请求，确认返回正常，再往下接 MCP 插件。因为如果模型通道本身不通，后面 Agent 调 MCP 工具时报的错会混在一起，排查成本翻倍。
我踩过的坑是：一开始把 Base URL 末尾多写了一个斜杠，导致请求路径拼接异常，报 404。后来对照文档改成https://taotoken.net/api就正常了。所以配置类字段建议直接复制，别手敲。另外 Key 不要写进前端或公开仓库，Dify 里配置在服务端环境即可。
3. 可复制配置：Dify 工作流 + ReAct 插件接入 MCP Server
这一节给你能直接抄的配置。先明确目标：在 Dify 工作流里加一个 Agent 节点，Agent 策略选 ReAct（支持 MCP 工具），填入你的 MCP Server 地址，配上提示词，跑通一次工具调用。
第一步，创建应用。在 Dify 里新建一个工作流（Chatflow 也是一种特殊工作流）。进入编排画布后，点击开始节点右侧的“+”号，添加一个 Agent 节点。
第二步，配置 Agent 策略。在 Agent 节点的策略下拉里，选择你已安装的 ReAct（支持 MCP 工具）插件。如果下拉里没有，先去插件市场搜 MCP 安装。
第三步，填 MCP Server 地址。这里给一个配置片段，你可以按自己环境替换：
{ "mcp_server_url": "http://your-host:8000/sse", "transport": "sse", "timeout_seconds": 30, "max_iterations": 10 }注意your-host不要写127.0.0.1，要写 Dify 容器能访问到的宿主机 IP 或域名。transport按你的 MCP Server 实际协议填，常见是sse。max_iterations建议先设 10，后面时间排查会用到。
第四步，把 MCP 提示词作为工具。在 Agent 节点的工具列表里，勾选你需要的 MCP 工具，同时额外加一个“获取当前时间”工具和一个“获取时间戳”工具。这一步是时间踩坑的关键，后面细说。
第五步，填提示词。给一个可复制的模板：
你是运维分析助手。你可以调用 MCP 工具查询 Prometheus 指标。 规则： 1. 必须先调用“获取当前时间”工具拿到当前时间，再基于该时间计算查询区间。 2. 所有时间计算必须基于获取到的当前时间，禁止自行假设年份。 3. 输出报告时使用 Markdown 格式。第六步，填输入请求，把 Agent 的输出作为用户提示词给到后续节点。如果你不需要后续 LLM 节点，可以直接用 Agent 的输出作为最终结果——我第一次调试时就是因为多加了一个 LLM 节点，导致 Agent 自己汇总的报告被覆盖，去掉后就正常了。
关于时区，在 Agent 策略的设置图标里点开，把时区从默认的 UTC 调整为“亚洲/上海”。这个设置不点，Agent 拿到的时间就是 UTC，和北京时间差 8 小时，查 Prometheus 数据时会偏。
如果你用的是 Cline MCP 或 Codex 这类工具，配置逻辑类似，都是 Base URL + Key + Model ID 三件套，只是配置文件位置不同。比如 Codex 的auth.json里填 Key，Base URL 指向https://taotoken.net/api，Model ID 按需填。CC Switch 场景下也是同一套 Key 复用。
4. 验证请求与成功结果：从报错到跑出报告
配置完别急着下结论，先做最小验证。在 Agent 节点里输入一个简单问题，比如“查询最近 5 分钟的 CPU 使用率”。点运行，观察结果。
如果第一次没出结果，别慌，点开 Agent 策略的详情看每一步。我第一次调试时，详情里第一步的时间是 16 开头的年份，明显不对——这就是没加时间工具、Agent 自己瞎猜年份导致的。加上“获取当前时间”工具后，时间变成 2023 年开头，但还是不对，因为时区是 UTC。调整时区为亚洲/上海后，时间对了，但查 Prometheus 数据时还是差一年。
问题出在哪？Agent 虽然拿到了当前时间，但计算查询区间时没有严格基于这个时间，而是自己又推了一年。解决办法是在提示词里加硬性要求：“必须基于获取的当前时间计算”，同时把 Agent 最大迭代次数调到 10，给它足够的步骤去纠正。最终时间掰过来了，报告也生成了。
成功的结果长这样：Agent 先调用获取当前时间工具，拿到类似2024-xx-xx xx:xx:xx的时间；然后调用获取时间戳工具拿到 Unix 时间戳；接着调用 MCP 工具查询 Prometheus，查询区间基于当前时间计算；最后输出一份 Markdown 报告，包含指标数值和分析结论。
如果你不需要流程图形式，直接用 Dify 的 Agent 智能助手也行。添加 MCP 工具和时间工具 → 配置提示词 → 输入问题 → 一次就能跑出结果。我实测时没要求必须 Markdown，它给的是 JSON，也能用。通过日志可以追踪迭代过程，看每一步调了什么工具、返回了什么。
验证通过的标志：Agent 详情里能看到工具调用链完整，时间字段正确，报告内容基于真实查询数据而非编造。如果这三点都满足，说明接入成功。
5. 本篇常见错排查：401、local proxy failed、时间偏差、OAuth
这一节对照真实报错给你排查清单。
401 Unauthorized：模型通道鉴权失败。检查 Dify 模型供应商里的 Base URL 是否为https://taotoken.net/api，Key 是否复制完整（别带空格），Model ID 是否拼写正确。三件套缺一不可。如果用的是 Claude Code 或 Codex，检查auth.json或对应配置文件里的 Key 和 Base URL。
local proxy failed / connection refused：MCP Server 地址填了127.0.0.1。Dify 容器里的127.0.0.1指向容器自身，不是宿主机。改成宿主机的局域网 IP 或域名，确保 Dify 容器能访问到。如果是 Docker 部署，可以用host.docker.internal（视平台支持情况）或直接写宿主机 IP。
reading choices 报错：通常是模型返回格式不符合预期，或者 Agent 迭代次数不够导致中途截断。把max_iterations调到 10，检查提示词是否要求了明确的输出格式。如果模型通道本身不稳定，也会出现这个错，先单独测模型对话确认通道正常。
时间偏差一年：这是本篇最典型的坑。排查顺序：第一，Agent 策略设置里时区是否改为亚洲/上海；第二，工具列表里是否加了“获取当前时间”和“获取时间戳”工具；第三，提示词里是否明确要求“必须基于获取的当前时间计算”。三者缺一，Agent 就可能自己猜年份。我踩过的坑就是只加了时间工具但没改时区，结果差 8 小时，后来又因为提示词没限定，差了一年。
OAuth 相关报错：如果你的 MCP Server 需要 OAuth 鉴权，检查 token 是否过期、回调地址是否配置正确。Dify 插件层面目前对 OAuth 的支持取决于插件实现，建议先在 MCP Server 侧用 curl 验证 token 有效，再接入 Dify。
调试功能不适配 Agent：Dify 1.5.0 的调试功能对 Agent 支持不完整，只有结果没有过程，每次都是重新调用。这时候靠变量监控和输出重构来定位，或者把 Agent 输出直接作为最终结果，减少中间节点干扰。
排查原则：先隔离模型通道，再隔离 MCP Server，最后看 Agent 编排。每一步都用最小请求验证，别一上来就跑完整流程。
6. 把 Key 通道和 MCP 工具链串起来：下一步怎么走
接入跑通之后，你手里其实有了两套可复用的东西：一套是 TaoToken 的统一 Key 通道，一套是 Dify + ReAct 插件的 MCP 调用能力。下一步可以做的方向有几个。
第一，把更多 MCP Server 接进来。你可以在插件市场继续找 ReAct 兼容的工具，或者自己写 MCP Server 暴露内部能力。每接一个，鉴权都复用同一个 TaoToken Key，不用重复配置。
第二，反向玩法：用 MCP Server 插件把 Dify 应用暴露成 MCP 服务。这样你的 Dify 工作流本身就成了一个可被其他 MCP 客户端调用的工具，适合做能力复用。
第三，长期编码和 Agent 场景，可以考虑 Coding Plan 把额度集中管理。如果你只是验证模型通不通，用模型对话页面快速发请求即可。接入文档在 doc 页面，API Keys 在 console 页面，按需取用。
最后给一个实用技巧：时间字段的坑不只出现在 Prometheus 查询，任何涉及时间计算的 MCP 工具都可能遇到。养成习惯——Agent 提示词里永远加一句“必须基于获取的当前时间计算”，工具列表里永远带一个获取当前时间的工具，时区永远先检查。这三条能帮你省下大量排查时间。
如果你在配置过程中遇到 401 或 local proxy failed，先回 §5 对照排查；如果模型通道没问题但 Agent 行为异常，重点看提示词和迭代次数。把最小验证跑通，再扩展复杂流程，比一上来就搭大工作流稳得多。
