背景：AI 大潮下的中台建设
在 AI 浪潮席卷而来的当下，我们团队紧跟技术趋势，近期致力于构建企业级 AI 中台。我们的技术栈涵盖了 OCR 识别、智能语音交互、语音数字人、知识库 以及 AI Agent 等核心模块。
AI中台和数字孪生系统的结合，赋予数字孪生系统 语音交互，智能播报，业务助手等能力。 从“可视”到“可听、可说、可思”
为了验证 AI 在实际业务中的落地能力，我们利用 AI Agent 进行了多轮业务预演。在预演过程中，为了让 Dify 智能体具备操作本地文件、查询本地数据库等“手脚”能力，我们决定通过 MCP (Model Context Protocol) 协议接入自研的 FastMCP 服务。
然而，在将 Dify（运行于 Docker 环境）与本地 FastMCP 服务对接时，我们遇到了一系列网络协议与连通性问题。本文将复盘从服务启动到最终配置成功的全流程，重点解决 Docker 网络隔离 导致的连接难题。
核心步骤
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）。
最后，关注公号“ITMan彪叔” 可以添加作者微信进行交流，及时收到更多有价值的文章。
