在 Dify 中通过 MCP 集成本地 FastMCP 服务避坑指南

<font style="color:rgb(6, 10, 38);">背景：AI 大潮下的中台建设</font>

<font style="color:rgb(6, 10, 38);">在 AI 浪潮席卷而来的当下，我们团队紧跟技术趋势，近期致力于构建企业级 </font><font style="color:rgb(6, 10, 38);">AI 中台</font><font style="color:rgb(6, 10, 38);">。我们的技术栈涵盖了 </font><font style="color:rgb(6, 10, 38);">OCR 识别</font><font style="color:rgb(6, 10, 38);">、</font><font style="color:rgb(6, 10, 38);">智能语音交互</font><font style="color:rgb(6, 10, 38);">、</font><font style="color:rgb(6, 10, 38);">语音数字人</font><font style="color:rgb(6, 10, 38);">、</font><font style="color:rgb(6, 10, 38);">知识库</font><font style="color:rgb(6, 10, 38);"> 以及 </font><font style="color:rgb(6, 10, 38);">AI Agent</font><font style="color:rgb(6, 10, 38);"> 等核心模块。</font>

<font style="color:rgb(6, 10, 38);"></font>

<font style="color:rgb(6, 10, 38);"></font>

<!-- 这是一张图片，ocr 内容为： -->

<font style="color:rgb(6, 10, 38);"></font>

<!-- 这是一张图片，ocr 内容为： -->

<font style="color:rgb(6, 10, 38);background-color:rgb(235, 245, 255);">AI中台和数字孪生系统的结合，赋予数字孪生系统 语音交互，智能播报，业务助手等能力。 </font><font style="color:rgb(6, 10, 38);background-color:rgb(235, 245, 255);">从“可视”到“可听、可说、可思” </font>

<!-- 这是一张图片，ocr 内容为： -->

<font style="color:rgb(6, 10, 38);"></font>

<!-- 这是一张图片，ocr 内容为： -->

<font style="color:rgb(6, 10, 38);">为了验证 AI 在实际业务中的落地能力，我们利用</font><font style="color:rgb(6, 10, 38);"> </font><font style="color:rgb(6, 10, 38);">AI Agent</font><font style="color:rgb(6, 10, 38);"> </font><font style="color:rgb(6, 10, 38);">进行了多轮业务预演。在预演过程中，为了让 Dify 智能体具备操作本地文件、查询本地数据库等“手脚”能力，我们决定通过</font><font style="color:rgb(6, 10, 38);"> </font><font style="color:rgb(6, 10, 38);">MCP (Model Context Protocol)</font><font style="color:rgb(6, 10, 38);"> </font><font style="color:rgb(6, 10, 38);">协议接入自研的</font><font style="color:rgb(6, 10, 38);"> </font><font style="color:rgb(6, 10, 38);">FastMCP</font><font style="color:rgb(6, 10, 38);"> </font><font style="color:rgb(6, 10, 38);">服务。</font>

<font style="color:rgb(6, 10, 38);">然而，在将 Dify（运行于 Docker 环境）与本地 FastMCP 服务对接时，我们遇到了一系列网络协议与连通性问题。本文将复盘从服务启动到最终配置成功的全流程，重点解决 </font><font style="color:rgb(6, 10, 38);">Docker 网络隔离</font><font style="color:rgb(6, 10, 38);"> 导致的连接难题。</font>

核心步骤

1. 服务端启动：监听所有网卡

默认情况下，FastMCP 可能只监听本地回环地址，这会导致外部（包括 Docker 容器）无法访问。\
关键点：必须在初始化 FastMCP 时指定 host="0.0.0.0"，而不仅仅是 run 方法。

from fastmcp import FastMCP

#  正确做法：在构造函数中指定 host 和 port
mcp = FastMCP("MyLocalServer", host="0.0.0.0", port=8000)

# ... 定义工具 ...

if __name__ == "__main__":
    # 指定传输协议为 http (即 streamable-http)
    mcp.run(transport="http")

2. Dify 插件配置：选择正确的传输协议

Dify 的 MCP 插件支持多种协议，FastMCP 默认使用的是较新的 Streamable HTTP 协议，而非旧的 SSE。

• 插件要求：确保 Dify 的 "MCP SSE / StreamableHTTP" 插件已安装且为最新版。
• 配置格式：必须显式指定 transport 字段。

3. 网络穿透：解决 Docker 隔离问题

这是最容易报错的地方。Dify 运行在 Docker 容器中，容器内的 127.0.0.1 指向容器自身，而非宿主机。

• 错误配置：http://127.0.0.1:8000/mcp（Dify 会尝试连接自己，导致 Connection refused）。
• 正确配置：使用 host.docker.internal 让容器访问宿主机网络。

️ 最终可用配置模板

在 Dify 的 工具 -> MCP SSE -> 工具设置 中，填入以下 JSON：

{
    "my-local-fastmcp": {
        "transport": "streamable_http",
        "url": "http://host.docker.internal:8000/mcp",
        "headers": {},
        "timeout": 60
    }
}

---

注意，有时候，需要配置没有格式化的json。

常见问题速查表

报错信息	可能原因	解决方案
Connection refused	地址写成了 127.0.0.1	改为 host.docker.internal
Unsupported protocol	transport 字段缺失或错误	确保填写 streamable_http，且 URL 无多余空格
404 Not Found	URL 路径错误	检查 URL 末尾是否需要加 /mcp 或 /
Timeout	防火墙拦截	开放宿主机 8000 端口，或检查 host="0.0.0.0" 是否生效

总结

• 服务端：FastMCP(..., host="0.0.0.0")
• 协议：transport: "streamable_http"
• 地址：host.docker.internal (Docker 环境)

你可以直接复制上面的内容。如果你们团队用的是 Linux 服务器部署 Dify，记得提醒同事把 host.docker.internal 换成服务器的局域网 IP（如 192.168.x.x）。

<font style="color:rgb(37, 41, 51);">最后，关注公号“ITMan彪叔” 可以添加作者微信进行交流，及时收到更多有价值的文章。</font>