集成 MCP 工具
你可以在 Dify 的 Agent 和 Workflow 应用中,直接集成来自外部 MCP 服务器的工具。除了使用 Dify 内置插件外,还可以接入 MCP 生态系统中的第三方服务,持续扩展你的应用功能。
本文介绍了如何在 Dify 内集成和使用 MCP 工具。如果你希望将自己的 Dify 应用发布为 MCP 服务器,请参考此链接。
目前仅支持接入使用 HTTP 传输协议的 MCP 服务器 。
MCP 服务器管理界面
登录 Dify 后,在左侧导航栏中依次点击 工具 → MCP,即可进入外部 MCP 服务器的管理页面。在这里,你可以统一管理所有为自身应用配置的 MCP 服务器。
添加 MCP 服务器
点击 添加 MCP 服务器(HTTP),即可集成新的外部工具服务。需要填写如下信息:
-
服务器 URL:MCP 服务器的 HTTP 接口地址,例如集成 Notion 时为
https://api.notion.com/mcp
。 -
名称与图标:自定义服务器名称,建议选择能清晰体现工具用途的名字。Dify 会自动尝试获取服务器域名的图标,你也可以手动上传。
-
服务器标识符:Dify 用于区分服务器的唯一 ID。规则:小写字母、数字、下划线或连字符,最多 24 个字符。
服务器 ID 一旦创建即无法更改。如果更改服务器 ID,所有依赖该服务器工具的 Agent 或 Workflow 都会失效。这一设计对于应用迁移尤为重要。
授权与工具发现
添加服务器后,Dify 会自动执行如下操作:
- 检测可用工具:自动识别该服务器能提供哪些工具功能。
- 处理授权流程:如服务器需要身份验证,则自动发起 OAuth 授权流程。
- 获取工具定义:下载各工具的接口定义(schema)。
- 同步工具列表:将识别到的工具加入 Agent 或Workflow应用的构建页面。
当 Dify 成功获取到至少一个可用工具后,会在页面中显示该服务器的信息卡片:
管理已连接服务器
点击对应服务器卡片,可进行以下操作:
-
更新工具:重新从服务器获取最新工具信息,适用于服务方新增或调整功能后更新。
-
重新授权:点击授权状态,更新服务器的访问权限(如令牌失效需重新授权)。
-
编辑配置:可修改服务器信息。
更改服务器 URL 会触发重新授权,修改服务器 ID 会让已有应用失效!
- 移除服务器:断开服务器连接。此后所有依赖该服务器工具的应用都会报错,直到你重新连接或删除相关工具。
在应用中使用 MCP 工具
当服务器配置完成后,其下的工具会出现在应用构建时的工具选择区:
Agent 应用
- 在 Agent 配置界面,与内置工具并列显示 MCP 工具。
- 工具按服务器分组,例如:“Notion MCP » 创建页面”、“Linear MCP » 创建任务”等。
- 可一键”添加全部”,快速启用该服务器下的所有工具。
Workflow 应用
- 构建 Workflow 时,MCP 工具以可选节点类型出现。
- 每个工具节点都会指明归属服务器,便于定位和排查问题。
- 参数较为复杂的工具会自动生成 JSON 格式的结构化输入界面。
Workflows 中的 Agent 节点
在 Workflow 的 Agent 节点中,也可灵活选择 MCP 工具进行配置,使用方式与独立 Agent 一致。
按需定制 MCP 工具
将 MCP 工具添加到Agent节点或 Agent 应用中后,你可以根据实际需求灵活定制:
工具说明
可自定义工具的显示描述,调整为更贴合业务场景的说明信息,替换原 MCP 服务器自带描述。
参数配置(Reasoning Config)
每个工具参数可灵活选择两种模式:
-
自动(Auto):让 AI 根据上下文智能决定该参数值(默认)。
-
固定值(Fixed Value):设定为某个确定的值(支持静态文本或变量表达式),AI 不再推理此参数。
使用示例:
- 统一配置项,例如将搜索工具的
numResults
固定为 10。 - 预填写不应更改的参数,如特定的 API 地址、返回格式等。
- 通过减少 AI 需要处理的参数数量,简化工具调用逻辑。
例如,配置 Web 搜索工具时:
- 将
query
设置为”自动”,由 AI 动态生成搜索内容。 - 将
numResults
固定为 5,控制每次返回结果数量。 - 其他如过滤条件参数也可固定,以保证结果一致性。
应用迁移
当你导出包含 MCP 工具的 Dify 应用时:
- DSL 导出:导出的 DSL 文件会引用所用 MCP 服务器的唯一标识符(ID)。
- 环境迁移:迁移应用到其他环境时,需在目标环境添加相同 ID 的 MCP 服务器。这样可以确保工具引用关系保持不变。
- 应用共享:建议在文档中明确标注依赖的 MCP 服务器(包括 URL 和 ID),以便团队协作和环境同步。
常见问题排查
“未配置的服务器”: 授权失败或未获取到工具。请检查服务器 URL 并重新授权。
应用内工具缺失: 点击”更新工具” - 有可能外部服务更改了工具列表。
服务器变动导致应用失效: 如果修改服务器 ID 或移除服务器,应用会报错。需用原 ID 重新添加服务器,以恢复功能。
最佳实践
服务器 ID 保持一致性: 使用具备描述性的 ID 名,例如 github-mcp
或者 salesforce-api
。ID 一旦被应用引用,请勿更改。
多环境一致性: 开发、测试、生产等环境的 MCP 服务器配置应保持一致。
工具定制: 主动设置固定参数值,保证工具行为稳定、简化 AI 推理,仅将动态输入交由 AI 处理。
工具文档: 明确记录应用中用到的外部工具、定制内容及其用途,方便团队后续运维与协作。
逐步升级: 外部服务升级或变更 MCP 服务器时,应先在开发环境测试通过后,再同步到生产环境。
应急方案: 提前规划好关键外部 MCP 服务器不可用时的应用应对策略。