1. 为什么你的 Dify 智能体还只是个聊天机器人很多人第一次用 Dify 搭出来的东西本质上还是个套了壳的聊天窗口。你问它天气它说“我无法获取实时信息”你让它查订单它开始一本正经地编。问题不在模型不够聪明而在于它没有“手”——不能调用外部工具。大语言模型本身只能处理文本。它知道“银川到中卫有火车”这件事但不知道今天下午三点那趟车还有没有票。要让模型从“知道”变成“做到”必须给它接上外部能力查数据库、调 API、读文件、操作浏览器。这就是智能体 Agent 和普通聊天机器人的分界线。以前做这件事靠的是 Function Call。你得在代码里写一大段 JSON Schema把每个函数的名称、参数、描述都定义清楚然后塞进请求里发给模型。模型返回一个 tool_calls 字段你再解析出来去执行。这套流程能跑但有几个让人头疼的地方。第一提示词工程量大。每个工具都要写描述描述写得好不好直接影响模型能不能正确调用。我见过有人为了一个查询接口写了三百多字的 description调参调到怀疑人生。第二生态碎片化。百度地图的接口格式和高德的不一样Unity 的工具定义和 Blender 的又不同。每接一个新工具就要重新写一遍适配层。第三复用性差。你在 A 项目里调通的工具配置换到 B 项目基本要重来。MCP 协议的出现就是来解决这个问题的。Anthropic 在 2024 年 11 月发布了 Model Context Protocol把大模型和外部工具的连接方式标准化了。你可以把它理解成 USB-C 扩展坞不管你是显示器、硬盘还是网线只要插口对得上就能即插即用。MCP Server 就是那个“插口”它用统一的规范描述自己有哪些工具、每个工具接受什么参数、返回什么结果。Dify 作为 MCP Host只需要按照协议去发现和调用就行。Dify 从 v1.0.0 开始引入了插件机制MCP SSE / StreamableHTTP 插件就是专门用来连接远程 MCP 服务的。这意味着你不需要在本地部署 MCP Server直接连托管服务就能用。对于想快速验证智能体工作流的开发者来说这条路最省事。这篇文章要做的就是带你从零跑通一条完整的链路在 Dify 里装好 MCP 插件配置一个真实的 MCP 服务地址搭一个能调用外部工具的 Agent最后用一次端到端请求验证它真的能拿到实时数据。全程可复制不需要你懂底层协议实现。2. TaoToken 前置准备拿到可用的模型与 Key在 Dify 里搭智能体模型是大脑MCP 是手脚。大脑得先能正常工作手脚才有意义。所以第一步不是急着配 MCP而是先把模型接入搞定。Dify 本身不提供模型它需要你接入外部的大模型服务。你可以用 OpenAI、DeepSeek、通义千问也可以用 TaoToken 这类聚合平台。TaoToken 的好处是一个 Key 能调多个模型省去到处注册账号的麻烦。它的 API 地址是https://taotoken.net/api兼容 OpenAI 的接口格式Dify 里直接选 OpenAI 类型的供应商就能接。具体操作路径是这样的登录 TaoToken 控制台在 API Keys 页面创建一个新的 Key。创建的时候注意权限范围如果你只是测试给最小权限就行。Key 生成后复制保存页面刷新后就看不到了。然后回到 Dify进入“设置”-“模型供应商”找到 OpenAI 那一栏。如果你之前没配过点击“添加模型”。在弹出的表单里填三个关键信息Base URL 填https://taotoken.net/api注意不要加多余的路径。API Key 填你刚才复制的那串。模型名称填你要用的模型 ID比如gpt-4o或者deepseek-chat。填完之后点“保存”Dify 会发一个测试请求验证连通性。如果提示成功说明模型通道已经打通。这里有个细节要注意Dify 的模型供应商配置里有些版本会把 Base URL 和完整 Endpoint 分开填。如果你看到的是“API Base”字段填https://taotoken.net/api就行如果是“完整 URL”那要填https://taotoken.net/api/v1/chat/completions。以你实际界面为准不确定的话两个都试一下报错信息会告诉你哪个对。模型配好之后建议先在 Dify 的“模型对话”里简单测一下。随便问一句“你好”看能不能正常返回。这一步过了再往下走。如果这里就报 401那后面 MCP 配得再好也没用。另外提一句如果你打算长期跑编码类或 Agent 类任务可以考虑用 Coding Plan 套餐额度和并发会宽松一些。测试阶段用按量计费就行没必要一上来就买套餐。3. 可复制配置Dify MCP 插件安装与 JSON 片段模型通了之后接下来装 MCP 插件。Dify 的插件市场里搜“MCP SSE”能找到官方维护的 “MCP SSE / StreamableHTTP” 插件。点安装等它装完。装完之后在“已安装插件”列表里找到它点击“去授权”。这里就是配置 MCP 服务地址的地方。Dify 的 MCP 插件支持两种传输方式SSE 和 StreamableHTTP。SSE 是 Server-Sent Events适合长连接推送StreamableHTTP 是流式 HTTP兼容性更好。你连的 MCP 服务支持哪种配置里就写哪种。配置的 JSON 结构长这样{ mcpServers: { server_name1: { transport: sse, url: http://127.0.0.1:8000/sse, headers: {}, timeout: 50, sse_read_timeout: 50 }, server_name2: { transport: streamable_http, url: http://127.0.0.1:8002/mcp, headers: {}, timeout: 50 } } }mcpServers下面可以挂多个服务每个服务一个 key。transport字段决定用哪种协议url是 MCP 服务的地址。headers用来放认证信息如果服务需要 API Key就在这里加。timeout是请求超时秒数sse_read_timeout是 SSE 读取超时按需调整。如果你连的是托管服务比如魔搭社区上的 MCP配置会更简单。以 12306 的 MCP 为例从魔搭拿到 SSE 地址后配置写成{ mcpServers: { 12306-mcp: { transport: sse, url: https://mcp.api-inference.modelscope.net/你的ID/sse, headers: {}, timeout: 60, sse_read_timeout: 300 } } }注意这里的transport是sse不是streamable_http。魔搭托管的 MCP 目前以 SSE 为主。timeout给 60 秒sse_read_timeout给 300 秒因为查火车票这种操作可能涉及多次工具调用时间给宽一点不容易断。如果你用的是高德地图 MCP配置里要把 Key 拼在 URL 后面{ mcpServers: { amap-amap-sse: { transport: sse, url: https://mcp.amap.com/sse?key你在高德申请的Key, headers: {}, timeout: 60, sse_read_timeout: 300 } } }智谱搜索 MCP 类似Key 放在 Authorization 参数里{ mcpServers: { zhipu-web-search-sse: { transport: sse, url: https://open.bigmodel.cn/api/mcp/web_search/sse?Authorization你的APIKey, headers: {}, timeout: 60, sse_read_timeout: 300 } } }配置写完之后点保存。Dify 会尝试连接这些 MCP 服务如果地址通、协议对它会拉取工具列表。你可以在插件详情页看到每个 MCP 服务暴露了哪些工具每个工具的参数是什么。这一步成功说明 MCP 通道已经打通。有个坑要注意Dify 的 MCP 插件配置里transport字段的值必须是sse或streamable_http不能写http或sse_stream。写错了会报 “unsupported transport type”。另外 URL 末尾不要多加斜杠有些服务对路径敏感。4. 验证请求搭一个能查实时数据的 Agent配置保存成功只是第一步真正要验证的是Agent 能不能在对话中自动调用 MCP 工具并拿到真实结果。在 Dify 里创建一个 Agent 应用。应用类型选“Agent”不是“Chatflow”也不是“Workflow”。Agent 模式才会让模型自主决定什么时候调工具。创建完之后在编排页面找到“工具”区域添加你刚才配好的 MCP 工具。Dify 会把 MCP 服务暴露的工具列出来你勾选需要的。比如 12306 MCP 会提供query_tickets、get_station_list之类的工具。勾选之后这些工具就挂载到 Agent 上了。然后写系统提示词。提示词的作用是告诉 Agent 它的角色和调用工具的策略。比如你叫“火车侠”是 12306-MCP 专属 AI 助理专注于铁路出行服务。 你的核心任务是调用 MCP 工具时先获取工具列表再选择 12306-MCP 来回答。 需要了解清楚本 MCP 如何使用。查询车票、规划行程提供最优推荐。这段提示词的关键是“先获取工具列表再选择 12306-MCP”。有些模型会直接尝试调用工具而不先看工具描述导致参数传错。加上这句能提高调用准确率。模型选择上实测豆包 doubao-seed-1.6 在工具调用场景下表现比较稳DeepSeek R1 和 V3 有时候会跳过工具直接编答案。如果你用 TaoToken 接模型可以切到doubao-seed-1.6试试。配置完成后在预览窗口输入一个真实查询“明天银川到中卫的火车有哪些”Agent 的执行流程是这样的它先读取工具列表识别出query_tickets工具然后从用户问题里提取参数——出发站“银川”、到达站“中卫”、日期“明天”。接着发起 MCP 调用MCP Server 去查实时数据返回车次列表。Agent 拿到结果后整理成自然语言输出。如果一切正常你会看到类似这样的返回2025年6月23日银川到中卫的火车车次信息如下按出发时间排序 K195次01:15银川站发车03:28抵达中卫站历时2小时13分。 硬座24.5元有票、硬卧70.5元剩余18张、软卧108.5元剩余4张。 C8221次城际06:57银川站发车08:12抵达中卫南站历时1小时15分。 二等座37元有票、一等座60元有票、商务座112元剩余10张。 D8953次动车07:48银川站发车09:03抵达中卫南站历时1小时15分。 二等座65元有票、一等座104元有票、无座65元有票。 ...这个结果和 12306 App 上查到的时刻表一致说明 MCP 调用链路是通的。你可以在 Dify 的日志里看到完整的工具调用记录模型发了什么请求、MCP 返回了什么、最终输出是什么。这个日志对排障很有用。验证通过之后你可以把这个 Agent 发布成 API 或嵌入到网页里。Dify 支持一键发布发布后外部系统就能通过 HTTP 调用这个智能体。到这一步一个可复用的智能体工作流就算跑通了。5. 常见报错排查401、local proxy failed 与 reading choices配 MCP 的过程中报错是常态。我把几个高频错误和对应的排查思路列出来你遇到的时候可以对照着看。401 Unauthorized这个错误通常出现在两个地方模型调用和 MCP 调用。如果是模型调用报 401说明 TaoToken 的 API Key 有问题。检查三点Key 有没有复制完整前后不要有空格、Key 有没有过期或被禁用、Base URL 有没有写错。TaoToken 的 Base URL 是https://taotoken.net/api如果你写成了https://taotoken.net/v1就会 401。另外有些模型需要单独开通权限没开通也会返回 401。如果是 MCP 调用报 401说明 MCP 服务的认证信息不对。检查配置里的headers或 URL 参数。比如高德 MCP 的 Key 是拼在 URL 里的格式是?key你的Key少个问号或者参数名写错都会 401。智谱的 Key 放在Authorization参数里注意大小写。local proxy failed这个错误一般出现在 Dify 尝试连接 MCP 服务的时候。原因通常是网络不通。Dify 部署的环境如果访问不了 MCP 服务的地址就会报这个。排查方法先在 Dify 所在的机器上用curl测一下 MCP 地址通不通。比如curl -v https://mcp.api-inference.modelscope.net/你的ID/sse。如果 curl 也连不上说明是网络问题不是 Dify 配置问题。如果 curl 能通但 Dify 报错检查 Dify 的容器网络配置看是不是 DNS 解析有问题。还有一种情况是 MCP 服务本身挂了。托管服务偶尔会维护换个时间再试。reading choices 相关报错这个错误通常和模型返回格式有关。Dify 期望模型返回标准的 OpenAI 格式如果模型返回了非标准结构解析就会失败。常见于一些兼容接口实现不完整的模型。解决办法换一个模型试试。如果你用的是 TaoToken切到gpt-4o或doubao-seed-1.6这种兼容性好的模型。如果换模型后正常说明是原模型的接口兼容问题。另外检查 Dify 的模型供应商配置里有没有开启“流式输出”。有些模型在流式模式下返回格式会变关掉流式试试。OAuth 相关报错如果你连的 MCP 服务需要 OAuth 认证配置里要加oauth字段。Dify 的 MCP 插件支持 OAuth但配置比较复杂。一般托管服务会用 API Key 而不是 OAuth遇到 OAuth 报错先确认服务方的认证方式。工具调用返回空结果Agent 调了工具但返回空可能是参数传错了。在 Dify 日志里看模型实际传了什么参数。比如查火车票日期格式传成了2025/06/23而服务期望2025-06-23就会查不到。调整提示词明确告诉模型日期格式要求。CC Switch / Cline MCP / Codex auth.json 三件套如果你在 Dify 之外还用 CC Switch 或 Cline 配 MCP注意它们的配置格式和 Dify 不一样。CC Switch 用的是 TOMLCline 用的是 JSONCodex 用 auth.json。不管哪种核心三要素都是Base URL、API Key、Model ID。Base URL 填 TaoToken 的https://taotoken.net/apiKey 填你创建的 KeyModel ID 填具体模型名。三件套对齐了换哪个客户端都能通。6. 从验证到复用把 MCP 智能体接进你的工作流跑通一次验证请求之后下一步是让它变得可复用。Dify 的 Agent 应用可以发布成 API外部系统通过 HTTP 调用。发布路径是应用编排页面右上角“发布”-“访问 API”。Dify 会生成一个 Endpoint 和 API Key你拿着这两个东西就能在代码里调。调用示例import requests url https://你的Dify地址/v1/chat-messages headers { Authorization: Bearer 你的DifyAPIKey, Content-Type: application/json } payload { inputs: {}, query: 明天银川到中卫的火车有哪些, response_mode: blocking, user: user-001 } response requests.post(url, headersheaders, jsonpayload) print(response.json())这样你的其他系统就能通过 API 调用这个智能体不用每次都打开 Dify 界面。如果你想把 MCP 能力嵌入到已有的工作流里Dify 的 Workflow 模式也支持 MCP 工具节点。在 Workflow 里加一个“工具”节点选择 MCP 工具配置好参数映射就能把 MCP 调用编排进更复杂的流程。比如先查天气再查火车票最后生成出行建议。MCP 生态还在快速扩张。魔搭社区上已经有上百个 MCP 服务覆盖地图、搜索、数据库、代码执行等场景。你可以在魔搭的 MCP 广场上找需要的服务拿到 SSE 地址后按前面的配置格式填进 Dify 就行。一个实用的技巧把常用的 MCP 配置存成一个 JSON 文件换 Dify 环境的时候直接粘贴不用重新写。配置里的 Key 用环境变量替换避免泄露。最后说一个我踩过的坑Dify 的 MCP 插件在保存配置后如果修改了 MCP 服务端的工具定义Dify 不会自动刷新工具列表。你需要手动在插件页面点一下“刷新”或者重新保存配置才能拉到最新的工具。这个在调试自定义 MCP Server 的时候特别容易遇到工具明明加了但 Dify 里看不到就是缓存没刷新。跑通这条链路之后你可以尝试把多个 MCP 服务挂到同一个 Agent 上。比如同时接高德地图和 12306让 Agent 自己决定什么时候查地图、什么时候查火车。这才是 MCP 真正的价值让模型自主编排多个外部能力完成复杂任务。
Dify MCP 保姆级教程来了！从零搭建可复用智能体工作流
1. 为什么你的 Dify 智能体还只是个聊天机器人很多人第一次用 Dify 搭出来的东西本质上还是个套了壳的聊天窗口。你问它天气它说“我无法获取实时信息”你让它查订单它开始一本正经地编。问题不在模型不够聪明而在于它没有“手”——不能调用外部工具。大语言模型本身只能处理文本。它知道“银川到中卫有火车”这件事但不知道今天下午三点那趟车还有没有票。要让模型从“知道”变成“做到”必须给它接上外部能力查数据库、调 API、读文件、操作浏览器。这就是智能体 Agent 和普通聊天机器人的分界线。以前做这件事靠的是 Function Call。你得在代码里写一大段 JSON Schema把每个函数的名称、参数、描述都定义清楚然后塞进请求里发给模型。模型返回一个 tool_calls 字段你再解析出来去执行。这套流程能跑但有几个让人头疼的地方。第一提示词工程量大。每个工具都要写描述描述写得好不好直接影响模型能不能正确调用。我见过有人为了一个查询接口写了三百多字的 description调参调到怀疑人生。第二生态碎片化。百度地图的接口格式和高德的不一样Unity 的工具定义和 Blender 的又不同。每接一个新工具就要重新写一遍适配层。第三复用性差。你在 A 项目里调通的工具配置换到 B 项目基本要重来。MCP 协议的出现就是来解决这个问题的。Anthropic 在 2024 年 11 月发布了 Model Context Protocol把大模型和外部工具的连接方式标准化了。你可以把它理解成 USB-C 扩展坞不管你是显示器、硬盘还是网线只要插口对得上就能即插即用。MCP Server 就是那个“插口”它用统一的规范描述自己有哪些工具、每个工具接受什么参数、返回什么结果。Dify 作为 MCP Host只需要按照协议去发现和调用就行。Dify 从 v1.0.0 开始引入了插件机制MCP SSE / StreamableHTTP 插件就是专门用来连接远程 MCP 服务的。这意味着你不需要在本地部署 MCP Server直接连托管服务就能用。对于想快速验证智能体工作流的开发者来说这条路最省事。这篇文章要做的就是带你从零跑通一条完整的链路在 Dify 里装好 MCP 插件配置一个真实的 MCP 服务地址搭一个能调用外部工具的 Agent最后用一次端到端请求验证它真的能拿到实时数据。全程可复制不需要你懂底层协议实现。2. TaoToken 前置准备拿到可用的模型与 Key在 Dify 里搭智能体模型是大脑MCP 是手脚。大脑得先能正常工作手脚才有意义。所以第一步不是急着配 MCP而是先把模型接入搞定。Dify 本身不提供模型它需要你接入外部的大模型服务。你可以用 OpenAI、DeepSeek、通义千问也可以用 TaoToken 这类聚合平台。TaoToken 的好处是一个 Key 能调多个模型省去到处注册账号的麻烦。它的 API 地址是https://taotoken.net/api兼容 OpenAI 的接口格式Dify 里直接选 OpenAI 类型的供应商就能接。具体操作路径是这样的登录 TaoToken 控制台在 API Keys 页面创建一个新的 Key。创建的时候注意权限范围如果你只是测试给最小权限就行。Key 生成后复制保存页面刷新后就看不到了。然后回到 Dify进入“设置”-“模型供应商”找到 OpenAI 那一栏。如果你之前没配过点击“添加模型”。在弹出的表单里填三个关键信息Base URL 填https://taotoken.net/api注意不要加多余的路径。API Key 填你刚才复制的那串。模型名称填你要用的模型 ID比如gpt-4o或者deepseek-chat。填完之后点“保存”Dify 会发一个测试请求验证连通性。如果提示成功说明模型通道已经打通。这里有个细节要注意Dify 的模型供应商配置里有些版本会把 Base URL 和完整 Endpoint 分开填。如果你看到的是“API Base”字段填https://taotoken.net/api就行如果是“完整 URL”那要填https://taotoken.net/api/v1/chat/completions。以你实际界面为准不确定的话两个都试一下报错信息会告诉你哪个对。模型配好之后建议先在 Dify 的“模型对话”里简单测一下。随便问一句“你好”看能不能正常返回。这一步过了再往下走。如果这里就报 401那后面 MCP 配得再好也没用。另外提一句如果你打算长期跑编码类或 Agent 类任务可以考虑用 Coding Plan 套餐额度和并发会宽松一些。测试阶段用按量计费就行没必要一上来就买套餐。3. 可复制配置Dify MCP 插件安装与 JSON 片段模型通了之后接下来装 MCP 插件。Dify 的插件市场里搜“MCP SSE”能找到官方维护的 “MCP SSE / StreamableHTTP” 插件。点安装等它装完。装完之后在“已安装插件”列表里找到它点击“去授权”。这里就是配置 MCP 服务地址的地方。Dify 的 MCP 插件支持两种传输方式SSE 和 StreamableHTTP。SSE 是 Server-Sent Events适合长连接推送StreamableHTTP 是流式 HTTP兼容性更好。你连的 MCP 服务支持哪种配置里就写哪种。配置的 JSON 结构长这样{ mcpServers: { server_name1: { transport: sse, url: http://127.0.0.1:8000/sse, headers: {}, timeout: 50, sse_read_timeout: 50 }, server_name2: { transport: streamable_http, url: http://127.0.0.1:8002/mcp, headers: {}, timeout: 50 } } }mcpServers下面可以挂多个服务每个服务一个 key。transport字段决定用哪种协议url是 MCP 服务的地址。headers用来放认证信息如果服务需要 API Key就在这里加。timeout是请求超时秒数sse_read_timeout是 SSE 读取超时按需调整。如果你连的是托管服务比如魔搭社区上的 MCP配置会更简单。以 12306 的 MCP 为例从魔搭拿到 SSE 地址后配置写成{ mcpServers: { 12306-mcp: { transport: sse, url: https://mcp.api-inference.modelscope.net/你的ID/sse, headers: {}, timeout: 60, sse_read_timeout: 300 } } }注意这里的transport是sse不是streamable_http。魔搭托管的 MCP 目前以 SSE 为主。timeout给 60 秒sse_read_timeout给 300 秒因为查火车票这种操作可能涉及多次工具调用时间给宽一点不容易断。如果你用的是高德地图 MCP配置里要把 Key 拼在 URL 后面{ mcpServers: { amap-amap-sse: { transport: sse, url: https://mcp.amap.com/sse?key你在高德申请的Key, headers: {}, timeout: 60, sse_read_timeout: 300 } } }智谱搜索 MCP 类似Key 放在 Authorization 参数里{ mcpServers: { zhipu-web-search-sse: { transport: sse, url: https://open.bigmodel.cn/api/mcp/web_search/sse?Authorization你的APIKey, headers: {}, timeout: 60, sse_read_timeout: 300 } } }配置写完之后点保存。Dify 会尝试连接这些 MCP 服务如果地址通、协议对它会拉取工具列表。你可以在插件详情页看到每个 MCP 服务暴露了哪些工具每个工具的参数是什么。这一步成功说明 MCP 通道已经打通。有个坑要注意Dify 的 MCP 插件配置里transport字段的值必须是sse或streamable_http不能写http或sse_stream。写错了会报 “unsupported transport type”。另外 URL 末尾不要多加斜杠有些服务对路径敏感。4. 验证请求搭一个能查实时数据的 Agent配置保存成功只是第一步真正要验证的是Agent 能不能在对话中自动调用 MCP 工具并拿到真实结果。在 Dify 里创建一个 Agent 应用。应用类型选“Agent”不是“Chatflow”也不是“Workflow”。Agent 模式才会让模型自主决定什么时候调工具。创建完之后在编排页面找到“工具”区域添加你刚才配好的 MCP 工具。Dify 会把 MCP 服务暴露的工具列出来你勾选需要的。比如 12306 MCP 会提供query_tickets、get_station_list之类的工具。勾选之后这些工具就挂载到 Agent 上了。然后写系统提示词。提示词的作用是告诉 Agent 它的角色和调用工具的策略。比如你叫“火车侠”是 12306-MCP 专属 AI 助理专注于铁路出行服务。 你的核心任务是调用 MCP 工具时先获取工具列表再选择 12306-MCP 来回答。 需要了解清楚本 MCP 如何使用。查询车票、规划行程提供最优推荐。这段提示词的关键是“先获取工具列表再选择 12306-MCP”。有些模型会直接尝试调用工具而不先看工具描述导致参数传错。加上这句能提高调用准确率。模型选择上实测豆包 doubao-seed-1.6 在工具调用场景下表现比较稳DeepSeek R1 和 V3 有时候会跳过工具直接编答案。如果你用 TaoToken 接模型可以切到doubao-seed-1.6试试。配置完成后在预览窗口输入一个真实查询“明天银川到中卫的火车有哪些”Agent 的执行流程是这样的它先读取工具列表识别出query_tickets工具然后从用户问题里提取参数——出发站“银川”、到达站“中卫”、日期“明天”。接着发起 MCP 调用MCP Server 去查实时数据返回车次列表。Agent 拿到结果后整理成自然语言输出。如果一切正常你会看到类似这样的返回2025年6月23日银川到中卫的火车车次信息如下按出发时间排序 K195次01:15银川站发车03:28抵达中卫站历时2小时13分。 硬座24.5元有票、硬卧70.5元剩余18张、软卧108.5元剩余4张。 C8221次城际06:57银川站发车08:12抵达中卫南站历时1小时15分。 二等座37元有票、一等座60元有票、商务座112元剩余10张。 D8953次动车07:48银川站发车09:03抵达中卫南站历时1小时15分。 二等座65元有票、一等座104元有票、无座65元有票。 ...这个结果和 12306 App 上查到的时刻表一致说明 MCP 调用链路是通的。你可以在 Dify 的日志里看到完整的工具调用记录模型发了什么请求、MCP 返回了什么、最终输出是什么。这个日志对排障很有用。验证通过之后你可以把这个 Agent 发布成 API 或嵌入到网页里。Dify 支持一键发布发布后外部系统就能通过 HTTP 调用这个智能体。到这一步一个可复用的智能体工作流就算跑通了。5. 常见报错排查401、local proxy failed 与 reading choices配 MCP 的过程中报错是常态。我把几个高频错误和对应的排查思路列出来你遇到的时候可以对照着看。401 Unauthorized这个错误通常出现在两个地方模型调用和 MCP 调用。如果是模型调用报 401说明 TaoToken 的 API Key 有问题。检查三点Key 有没有复制完整前后不要有空格、Key 有没有过期或被禁用、Base URL 有没有写错。TaoToken 的 Base URL 是https://taotoken.net/api如果你写成了https://taotoken.net/v1就会 401。另外有些模型需要单独开通权限没开通也会返回 401。如果是 MCP 调用报 401说明 MCP 服务的认证信息不对。检查配置里的headers或 URL 参数。比如高德 MCP 的 Key 是拼在 URL 里的格式是?key你的Key少个问号或者参数名写错都会 401。智谱的 Key 放在Authorization参数里注意大小写。local proxy failed这个错误一般出现在 Dify 尝试连接 MCP 服务的时候。原因通常是网络不通。Dify 部署的环境如果访问不了 MCP 服务的地址就会报这个。排查方法先在 Dify 所在的机器上用curl测一下 MCP 地址通不通。比如curl -v https://mcp.api-inference.modelscope.net/你的ID/sse。如果 curl 也连不上说明是网络问题不是 Dify 配置问题。如果 curl 能通但 Dify 报错检查 Dify 的容器网络配置看是不是 DNS 解析有问题。还有一种情况是 MCP 服务本身挂了。托管服务偶尔会维护换个时间再试。reading choices 相关报错这个错误通常和模型返回格式有关。Dify 期望模型返回标准的 OpenAI 格式如果模型返回了非标准结构解析就会失败。常见于一些兼容接口实现不完整的模型。解决办法换一个模型试试。如果你用的是 TaoToken切到gpt-4o或doubao-seed-1.6这种兼容性好的模型。如果换模型后正常说明是原模型的接口兼容问题。另外检查 Dify 的模型供应商配置里有没有开启“流式输出”。有些模型在流式模式下返回格式会变关掉流式试试。OAuth 相关报错如果你连的 MCP 服务需要 OAuth 认证配置里要加oauth字段。Dify 的 MCP 插件支持 OAuth但配置比较复杂。一般托管服务会用 API Key 而不是 OAuth遇到 OAuth 报错先确认服务方的认证方式。工具调用返回空结果Agent 调了工具但返回空可能是参数传错了。在 Dify 日志里看模型实际传了什么参数。比如查火车票日期格式传成了2025/06/23而服务期望2025-06-23就会查不到。调整提示词明确告诉模型日期格式要求。CC Switch / Cline MCP / Codex auth.json 三件套如果你在 Dify 之外还用 CC Switch 或 Cline 配 MCP注意它们的配置格式和 Dify 不一样。CC Switch 用的是 TOMLCline 用的是 JSONCodex 用 auth.json。不管哪种核心三要素都是Base URL、API Key、Model ID。Base URL 填 TaoToken 的https://taotoken.net/apiKey 填你创建的 KeyModel ID 填具体模型名。三件套对齐了换哪个客户端都能通。6. 从验证到复用把 MCP 智能体接进你的工作流跑通一次验证请求之后下一步是让它变得可复用。Dify 的 Agent 应用可以发布成 API外部系统通过 HTTP 调用。发布路径是应用编排页面右上角“发布”-“访问 API”。Dify 会生成一个 Endpoint 和 API Key你拿着这两个东西就能在代码里调。调用示例import requests url https://你的Dify地址/v1/chat-messages headers { Authorization: Bearer 你的DifyAPIKey, Content-Type: application/json } payload { inputs: {}, query: 明天银川到中卫的火车有哪些, response_mode: blocking, user: user-001 } response requests.post(url, headersheaders, jsonpayload) print(response.json())这样你的其他系统就能通过 API 调用这个智能体不用每次都打开 Dify 界面。如果你想把 MCP 能力嵌入到已有的工作流里Dify 的 Workflow 模式也支持 MCP 工具节点。在 Workflow 里加一个“工具”节点选择 MCP 工具配置好参数映射就能把 MCP 调用编排进更复杂的流程。比如先查天气再查火车票最后生成出行建议。MCP 生态还在快速扩张。魔搭社区上已经有上百个 MCP 服务覆盖地图、搜索、数据库、代码执行等场景。你可以在魔搭的 MCP 广场上找需要的服务拿到 SSE 地址后按前面的配置格式填进 Dify 就行。一个实用的技巧把常用的 MCP 配置存成一个 JSON 文件换 Dify 环境的时候直接粘贴不用重新写。配置里的 Key 用环境变量替换避免泄露。最后说一个我踩过的坑Dify 的 MCP 插件在保存配置后如果修改了 MCP 服务端的工具定义Dify 不会自动刷新工具列表。你需要手动在插件页面点一下“刷新”或者重新保存配置才能拉到最新的工具。这个在调试自定义 MCP Server 的时候特别容易遇到工具明明加了但 Dify 里看不到就是缓存没刷新。跑通这条链路之后你可以尝试把多个 MCP 服务挂到同一个 Agent 上。比如同时接高德地图和 12306让 Agent 自己决定什么时候查地图、什么时候查火车。这才是 MCP 真正的价值让模型自主编排多个外部能力完成复杂任务。
