1. 为什么要在 Dify 里接 MCP：从“会聊天”到“能干活”
如果你已经用 Dify 搭过几个聊天助手或者工作流，大概率会遇到一个瓶颈：模型本身很聪明，但它被关在对话框里，拿不到实时数据，也操作不了外部系统。你问它今天某个城市的天气，它只能凭训练语料猜；你让它去抓一个网页的正文，它直接告诉你“我无法访问互联网”。这不是模型不行，而是它缺少一套标准化的“手和脚”。
MCP（Model Context Protocol）解决的正是这个问题。你可以把它理解成 AI 世界的 USB-C 接口：不管外部工具是查天气、读数据库、抓网页还是调内部 API，只要封装成一个 MCP Server，任何支持 MCP 的客户端都能用同一套协议去发现工具、传参、拿结果。Dify 从 1.x 版本开始，通过插件市场里的 MCP 相关插件，把这条链路打通了——Agent 节点可以声明使用 MCP 工具，工作流里的 Agent 策略节点也能挂载 MCP Server。
这篇内容面向的是已经在用 Dify、想把手头工作流接上外部工具的同学。我会把重点放在三件事上：Agent 节点怎么声明 MCP 工具、MCP Server 怎么注册进 Dify、以及如何用一套统一的 Key/API 通道（TaoToken）把模型调用和工具调用的凭证管理收拢到一处。全程给可复制的配置片段，最后跑一次端到端验证，确保你不是“配完看着像成功”，而是真的能拿到工具返回的结果。
需要提前说清楚：MCP Server 本身不神秘，它就是一个按协议暴露 tools 列表的 HTTP 服务，Dify 负责把用户意图翻译成对某个 tool 的调用。真正容易踩坑的地方在配置格式、超时参数和凭证通道，这些我会在后面的章节逐个拆开。
2. 前置准备：TaoToken 统一 Key 与 Dify 侧环境
在动手改 Dify 配置之前，先把“凭证从哪来”这件事定下来。很多同学接 MCP 时最乱的就是 Key 满天飞：模型一个 Key、每个 MCP Server 又一个 Key、工作流里还硬编码几个。一旦要换环境或者轮换凭证，就得满仓库找。我的做法是走一条统一的 API 通道，把模型调用和工具调用需要的凭证都从同一个入口拿，配置里只引用环境变量，不写死明文。
TaoToken 在这里扮演的就是这个统一通道的角色。它提供兼容 OpenAI 风格的 API 入口，Dify 里配置模型供应商时可以直接填它的地址和 Key；同时你申请到的 Key 也能用于后续需要鉴权的 MCP 工具调用场景。官网入口是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 基址是 https://taotoken.net/api （这个地址不加 UTM 参数，配置时直接用）。
具体操作上，你需要先拿到一个 API Key。进入控制台创建即可，地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite 。创建完之后，在 API Keys 页面可以查看和管理，页面是 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。如果你后面要跑长期编码或者 Agent 类任务，可以关注 Coding Plan 页面 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，它更适合高频调用场景。
Dify 侧需要准备的东西不多：一个能正常访问的 Dify 实例（社区版或云版都行），以及插件市场的安装权限。如果你用的是自托管 Dify，确认容器能出网访问你选的 MCP Server 地址；如果是内网 MCP Server，确保 Dify 所在网络能路由到它。这两点看着基础，但实测下来一半的“工具调不通”都卡在这里。
注意：不要把 API Key 直接写进 Dify 的插件配置 JSON 里再提交到 Git。用 Dify 的环境变量功能，或者至少在配置里用占位符，运行时再注入。后面第 3 节的 settings.json 骨架会演示这种写法。
3. 可复制配置：settings.json 骨架与 MCP 工具注册
这一节是全文的核心，给你一份可以直接改改就用的配置骨架。Dify 里 MCP 的配置入口有两个：一个是在 Agent 应用的工具授权里填 JSON，另一个是在工作流的 Agent 策略节点里填 MCP 服务配置。两者的 JSON 结构基本一致，都是“服务名 -> 连接参数”的映射。
先看单服务的最小骨架。假设你要接一个查天气的 MCP Server，它的 SSE 地址是https://mcp.example.com/sse，需要带上你的 Key：
{ "weather-server": { "url": "https://mcp.example.com/sse?key=${MCP_WEATHER_KEY}", "headers": { "Authorization": "Bearer ${TAOTOKEN_API_KEY}" }, "timeout": 60, "sse_read_timeout": 300 } }这里有几个参数值得单独说。url是 MCP Server 的 SSE 端点，不同服务商路径不一样，有的把 Key 放 query，有的要求放 header，按对方文档来。headers里可以放统一鉴权头，如果你走 TaoToken 通道，把TAOTOKEN_API_KEY注入进来即可。timeout是建立连接的超时，单位秒；sse_read_timeout是读取 SSE 流的超时，抓网页、跑长任务时这个值要给够，否则工具还没返回就被掐断了。
多服务并存时，直接在同一个 JSON 里加键值对，用逗号隔开：
{ "weather-server": { "url": "https://mcp.example.com/sse?key=${MCP_WEATHER_KEY}", "timeout": 60, "sse_read_timeout": 300 }, "fetch-server": { "url": "https://mcp-fetch.example.com/sse", "headers": { "Authorization": "Bearer ${TAOTOKEN_API_KEY}" }, "timeout": 60, "sse_read_timeout": 600 } }fetch-server的sse_read_timeout给到 600，是因为抓取网页正文并做总结可能耗时较长，给足缓冲。你可以按实际工具的平均耗时调整，原则是“宁可略大，不要卡边界”。
在 Dify 的 Agent 应用里，进入工具菜单，添加 MCP 相关插件后，把上面的 JSON 粘进授权框。在工作流里，拖出 Agent 节点，策略选支持 MCP 的 ReAct 策略，然后在 MCP 服务配置里填同样的 JSON。模型选择上，你可以用 TaoToken 通道里配置好的模型，也可以先用 Dify 自带供应商，但建议统一走一条通道，方便后面排查。
配置完保存后，Dify 会去拉取每个 MCP Server 的 tools 列表。如果 JSON 格式没问题、网络通、鉴权对，你会在工具列表里看到类似weather-server.weather_forecast、fetch-server.fetch这样的条目。看到这些条目，说明注册成功了，接下来才是真正调用。
4. 端到端验证：一次 Agent 调用 MCP 工具的完整过程
配置对不对，跑一次就知道。我建议先用 Agent 应用做验证，因为它的调试窗口能看到完整的思考链和工具调用记录，比工作流更容易定位问题。
在 Agent 的提示词里加一句引导，让模型知道有工具可用：
你是一个助手。当用户的问题需要实时数据或外部信息时，优先检查可用工具并调用，不要凭记忆回答。然后在右侧调试窗口输入一个必须用工具才能答对的问题，比如“帮我查一下北京未来三天的天气”。点击发送后，观察 Agent 的思考过程。正常情况下你会看到这样的链路：模型先判断自己不知道实时天气，然后从工具列表里选中weather-server.weather_forecast，构造参数{"city": "北京"}，发起调用；MCP Server 返回结构化天气数据；模型读取结果，组织成自然语言回复给你。
如果你在工作流里验证，流程类似：开始节点接收输入，Agent 节点挂载 MCP 配置并执行，结束节点输出 Agent 的 text。跑完后点开 Agent 节点的执行日志，能看到它调用了哪个 tool、传了什么参数、返回了什么。这一步的日志是排障的关键，后面第 5 节会反复用到。
验证成功的标志有三个：一是工具列表里能看到注册的 tool；二是调用日志里有明确的 tool call 记录；三是最终回复里包含只有工具才能提供的信息（比如实时温度、网页正文摘要）。三个都满足，说明你的 MCP 工具链在 Dify 里跑通了。
提示：第一次验证时，尽量选一个响应快、参数简单的工具，比如查天气或查时间。抓网页、跑数据库这类工具变量多，不适合作为首个验证对象。
5. 本篇常见错排查：从 JSON 报错到工具不触发
即使配置看起来没问题，实际跑的时候还是会遇到各种报错。我把踩过的坑按出现频率排一下，你对照着查。
第一种，JSON 解析失败。Dify 的配置框对 JSON 格式很严格，多一个逗号、少一个引号都会报错。常见的是在最后一个键值对后面加了逗号，或者用了中文引号。解决办法是把 JSON 贴到任意一个 JSON 校验工具里过一遍，确认合法再粘回去。另外注意${VAR}这种占位符在 JSON 里是合法字符串，但如果你的 Dify 版本不支持环境变量注入，就得换成实际值。
第二种，连接超时或 401。如果日志里出现connection timeout，先确认 Dify 所在网络能不能访问 MCP Server 的域名和端口。如果是 401 或 403，检查鉴权头或 query 里的 Key 是否正确、是否过期。走 TaoToken 通道的话，确认 API Key 是在有效期内，并且有对应工具的调用权限。
第三种，工具注册成功但模型不调用。这是最让人抓狂的情况：工具列表里明明有，模型就是不用。原因通常是提示词没引导到位，或者模型本身对工具调用的支持较弱。解决办法是在提示词里明确写“需要外部信息时优先调用工具”，并且换一个工具调用能力强的模型。另外，有些 MCP Server 的 tool 描述写得很模糊，模型看不懂什么时候该用，这种情况只能换工具或自己包一层描述更清晰的 Server。
第四种，SSE 流中断。抓网页或跑长任务时，如果sse_read_timeout设得太小，工具还没返回完连接就断了，日志里会看到read timeout或stream closed。把sse_read_timeout调大，比如从 300 调到 600 甚至 900，再试一次。
第五种，工作流里 Agent 节点输出为空。检查结束节点有没有正确引用 Agent 节点的输出字段，通常是text。如果 Agent 节点执行成功但结束节点拿不到值，多半是字段名写错了。
排障时如果卡在接入环节，可以去接入文档页面 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 对照检查配置项；如果是 Key 的问题，去 API Keys 页面 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 确认状态。想先单独验证模型通道是否正常，可以用模型对话页面 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=chat&utm_campaign=rewrite 发一条消息试试，排除模型侧的问题。
6. 把工具链跑稳：统一通道与后续扩展
跑通一次调用只是开始，真正要稳定用起来，还得把凭证和配置管理收拢。我现在的做法是：所有模型调用和需要鉴权的 MCP 工具调用，都走 TaoToken 这一条通道，Dify 里只保留环境变量引用，不出现明文 Key。这样换环境时只改变量，不动配置；轮换凭证时也只改一处。
如果你后面要接更多 MCP Server，建议按功能分组命名，比如weather-*、fetch-*、db-*，配置里一眼能看出哪个服务负责什么。超时参数按工具类型区分：查询类 60 秒够用，抓取和计算类给到 300 到 600 秒。每次新增工具后，先用一个最小问题验证它能被调用，再放进正式工作流，避免多个变量混在一起排查。
长期跑编码或 Agent 类任务的话，Coding Plan 页面 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 里有更适合高频调用的方案，可以按自己的调用量评估。如果你用的是 Claude Code 这类编码工具，Anthropic 兼容入口在 https://taotoken.net/claudecode-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=claudecode-anthropic&utm_campaign=rewrite ，配置方式类似，都是把基址和 Key 填进去。
最后留一个实操建议：每次改完 MCP 配置，不要直接在生产工作流上试，先复制一个测试工作流，用最小输入跑一遍，确认工具调用日志正常，再合并回去。这个习惯能帮你省下大量“改一处崩一片”的时间。
