通过 MCP 与 Dify 集成

Documentation Index

Fetch the complete documentation index at: https://docs.xpertai.cn/llms.txt

Use this file to discover all available pages before exploring further.

​

🧩 第一步：准备 Dify 平台资源

• 知识库（Knowledge Base）：如 FAQ 文档、产品介绍等；
• 工作流（Workflow）：例如一个用于异常处理或审批的自动化流程；
• Chatflow：自定义的大模型对话流程。

​

✅ 所需信息

• Dify 的 API Key（建议使用具有对应资源权限的 Key）；
• 资源的唯一标识（如工作流 ID、Chatflow ID 等）；
• 其他资源访问所需的参数（如 Base URL、Agent ID 等）。

​

🛠️ 第二步：在 MCP 市场安装 Dify 工具模版

1. 进入 Xpert AI 平台的 MCP 工具市场；
2. 搜索关键词 “Dify”，即可看到官方提供的若干 Dify 集成模版：
   • Dify Chatflow 调用模版
   • Dify 工作流调用模版
   • Dify 知识库问答模版
3. 选择适合您需求的模版，点击 “安装”；
4. 在安装页面填写：
   • Dify 平台的 API Key
   • 目标资源的 ID（如 Chatflow ID、Workflow ID）
   • 可选：填写默认参数、环境变量配置等；
5. 安装完成后，MCP 工具会自动生成，并在“工具列表”中可见。

​

🧬 第三步：修改 MCP 工具代码以自定义参数和逻辑

import os
import requests

...

@mcp.tool()
def run_chatflow(input: str) -> Optional[str]:
   """
   调用 Dify 平台中的某个 Chatflow 对话流程，支持异常场景处理等应用。
   :param input: 用户输入的异常描述信息，将作为 Dify Chatflow 的主要上下文输入。
   :return: 返回 Dify 响应的核心文本内容
   """

   API_KEY = os.getenv("DIFY_API_KEY")
   CHATFLOW_ID = os.getenv("DIFY_CHATFLOW_ID")

   headers = {"Authorization": f"Bearer {API_KEY}"}
   payload = {
      "inputs": {"input": input},
      "response_mode": "blocking"
   }

   resp = requests.post(
      f"https://api.dify.ai/v1/chat-flows/{CHATFLOW_ID}/invoke",
      json=payload,
      headers=headers,
      timeout=20
   )

   if resp.status_code == 200:
      return resp.json().get("answer")  # 根据 Dify 的返回结构自行提取
   return None

​

💡 编写建议

• input 参数可以根据业务需要扩展，例如添加用户角色、业务类型等；
• 函数的 Docstring 是 提示大模型调用工具的关键描述信息，务必详细写明工具用途、输入要求与典型调用场景；
• 如需提取结构化结果（如 JSON 字段），可在返回逻辑中添加解析；
• 支持读取环境变量，确保敏感信息安全配置。

​

🧠 第四步：将 MCP 工具集成到智能体

1. 打开某个需要调用 Dify 资源的智能体编排页；
2. 点击“添加工具集”，选择您刚才创建的 Dify MCP 工具；
3. 自动保存智能体配置；
4. 接下来，您的智能体便具备调用 Dify Chatflow、工作流或知识库的能力，能在对话中根据用户输入智能触发相关逻辑。

​

✅ 示例应用场景

• 客户支持 Copilot：根据用户问题调用 Dify Chatflow，实现自动问答；
• 流程协同智能体：接入 Dify 工作流，实现销售审批、异常处理等；
• 知识搜索助手：集成 Dify 知识库，支持用户随时检索业务知识。

​

❓ 常见问题 FAQ

​

1. 🧠 大模型没有调用此工具？

• 检查大模型是否支持 工具调用能力；
• 查看 MCP 工具的 Docstring 是否详细、明确地描述了调用场景和参数用途；
• 检查智能体的提示词（Prompt）中是否引导模型识别场景和工具功能；
• 工具是否已正确绑定到该智能体。

​

2. 🧾 调用 MCP 工具时没有填写参数？

• 查看 MCP 工具函数中参数是否设置为可选（Optional）而非必填；
• 检查 Docstring 中是否清晰描述了参数的用途和要求；
• 考虑使用强制参数（无默认值）来提示模型 必须输入参数；
• 提供结构化提示词，让模型清晰知道输入参数应是什么内容。

​

3. 🔐 出现 “Unauthorized” 或 “401” 错误？

• 检查 API Key 是否正确粘贴，是否为有效的 Dify 平台 Key；
• 是否在 MCP 工具代码中正确地通过环境变量传入了 Key；
• 确认该 API Key 是否具备访问目标资源的权限（如 Chatflow、Workflow）。

​

4. 🆔 提示 “Resource Not Found” 或 “Invalid ID”？

• 检查传入的 Chatflow ID / Workflow ID 是否准确；
• 某些 ID 在 Dify 平台中可能为私有资源，请确认是否对 API Key 用户开放；
• 复制 ID 时避免空格或隐藏字符错误。

​

5. 🌐 MCP 工具调用 Dify 失败或无响应？

• 检查 Dify API 请求是否超时，可增加 timeout 参数（例如 timeout=30）；
• 验证当前网络环境是否能访问 https://api.dify.ai；
• 查看 MCP 工具代码中是否正确处理了异常，建议加入异常捕获和日志输出。

​

6. 🧪 模型调用工具后返回内容不完整或结构异常？

• 确认 Dify API 返回的结构（通常是 JSON），并正确提取所需字段（如 answer）；
• 可加入日志打印返回体以调试，或解析嵌套字段以获取完整信息；
• 若返回为 markdown 或 HTML，可加入后处理逻辑进行清洗。

​

7. 🤖 智能体调用工具时频率受限或报错？

• 检查 Dify 平台是否有调用频率限制（Rate Limit）；
• 对于高频调用场景，建议申请高权限的 API Key 或升级计划；
• 可在 MCP 工具中加入冷却时间、调用失败重试等策略。

​

8. 📦 MCP 工具无法连接成功？

• 判断 MCP 工具代码中是否使用了某些第三方 Python 包（如 requests, httpx, pydantic 等）；
• 若需要这些包，请确保在 requirements.txt 文件中添加对应依赖；
• 添加后重新部署工具，再尝试连接；
• 可通过查看日志信息判断是否为缺包导致的 ModuleNotFoundError 错误。

​

9. 🛠️ 如何调试 MCP 工具调用是否成功？

• 在 MCP 工具代码中打印 response.status_code 和 response.json()；
• 使用 Postman 或 curl 测试 Dify API 调用参数和响应结构；
• 使用 Xpert AI 的 MCP 工具测试台，模拟输入并观察调用日志。

​

10. 🔄 如何更新或升级 Dify 集成工具？

• 可通过 MCP 工具后台编辑代码，更新逻辑或 API 接口；
• 如模版有新版本，建议重新安装或复制模版代码进行对比合并；
• 更新后请记得保存工具集，确保生效。