> ## 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.

# 通过 MCP 与 Dify 集成

为了进一步释放企业数字资源的潜能，**Xpert AI 多智能体平台** 已支持通过 **MCP** 与 **Dify 平台** 进行深度集成，涵盖 **知识库**、**工作流**、**Chatflow** 等关键能力。

通过本教程，您将学会如何在 Xpert AI 平台中配置 MCP 工具，集成 Dify 的核心资源，并赋能 AI 智能体调用这些工具，实现更智能、专业的业务自动化流程。

***

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

在集成之前，您需要在 [Dify 平台](https://cloud.dify.ai/) 准备好希望接入的资源，例如：

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

### ✅ 所需信息

请准备以下信息，供后续工具配置时使用：

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

***

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

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

***

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

进入“代码”，您可以对工具逻辑进行细粒度定制，示例如下：

```python title=main.py theme={null}
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 工具。

***

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

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

***

## ✅ 示例应用场景

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

***

当然可以，以下是为这篇教程新增的“**常见问题 FAQ**”章节，覆盖了在使用 Xpert AI 平台集成 Dify 资源过程中用户可能遇到的问题及解答。

***

## ❓ 常见问题 FAQ

在集成与使用 Dify 工具的过程中，您可能会遇到以下问题：

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

**可能原因与解决方法：**

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

**建议**：在描述中加入清晰的意图引导，例如：“当用户提出XXX问题时，请调用此工具进行处理”。

***

### 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` 错误。

**建议**：在开发或调试 MCP 工具时，优先在本地完整测试所有依赖项，再部署到平台中。

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

**建议操作：**

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

***

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

**操作建议：**

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

***

如有更多未覆盖的问题，欢迎加入我们的开发者社群或联系技术支持获得帮助。