企业官网建设流程全解析

1. Dify 里 MCP 插件到底解决了什么问题

如果你已经在用 Dify 搭工作流，大概率遇到过这种尴尬：工作流里想调一个外部工具，得先写 HTTP 请求节点、手动拼 JSON、再解析返回，工具一多，画布上全是请求节点，维护起来头大。MCP（Model Context Protocol）就是来收拾这个场面的——它把「工具怎么被发现、怎么被调用、返回什么结构」标准化了，Dify 只要接上 MCP，就能像插 U 盘一样把外部能力挂进来。

Dify 里的 MCP 相关插件，按角色分其实就两类：一类是当客户端，去连别人的 MCP 服务、发现并调用工具；另一类是当服务端，把 Dify 自己的工作流、对话流、工具发布成 MCP 服务，让别的 AI 客户端来调。围绕这两类，社区里衍生出了 Agent 策略插件、SSE/StreamableHTTP 传输插件、MCP Server 插件、工具兼容插件等一堆东西。很多人第一次看插件市场会懵：名字都带 MCP，到底该装哪个？

这篇就按「插件分类 → 可复制配置 → FastMCP 服务实现原理 → 调用链路验证 → 报错排查」的顺序走一遍。适合两类人：一是想在 Dify 工作流里接入 MCP 工具但不知道从哪下手的开发者；二是想自己用 FastMCP 写一个 MCP 服务、再挂到 Dify 上验证链路的同学。全程给可复制的 JSON 配置和启动命令，不空谈概念。

先说清楚一个前提：Dify 本身不内置 MCP 协议栈，MCP 能力是靠插件补上的。所以「Dify 中的 MCP」本质是「Dify 插件系统 + MCP 协议」的组合。理解这一点，后面看插件分类就不会乱。

2. Dify 中 MCP 插件的四类角色与选型

把插件按「谁连谁」拆开，逻辑立刻清晰。我按实际使用场景分成四类，每类给一个典型插件和适用场景。

第一类：扩展插件类型——把 Dify 应用发布为 MCP 服务。代表是hjlarry/mcp-server。它的作用是把 Dify 的工作流或对话流包装成一个 MCP Server，对外暴露 endpoint。适用场景：你已经在 Dify 里调好了一个复杂工作流（比如合同审查、数据清洗），想让 Claude Desktop、Cursor 这类外部客户端也能调用它。配置时在插件里填端点信息，外部客户端用 SSE 或 StreamableHTTP 连上来即可。

第二类：工具插件类型——让 Dify 当 MCP 客户端去调外部服务。代表是junjiem/mcp_sse（MCP SSE / StreamableHTTP）。它相当于一个 MCP 客户端，通过 HTTP with SSE 或 Streamable HTTP 传输方式发现并调用 MCP 工具。适用场景：你有一个远程 MCP 服务（比如公司内部的知识库查询服务），想在 Dify 工作流里直接调它的工具。装完插件后在节点里填 MCP 服务地址和工具配置 JSON。

第三类：Agent 策略插件类型——在 Agent 节点里支持 MCP 工具调用。代表是junjiem/mcp_see_agent（Agent 策略，支持 MCP 工具）和hjlarry/agent（MCP Agent 策略）。区别在于：前者同时支持 Function Calling 和 ReAct 两种策略，后者只支持 Function Calling。适用场景：你的工作流里有 Agent 节点，希望 Agent 在规划多步任务时能调用 MCP 工具。选型建议——需要 ReAct 推理循环就选前者，只需要简单函数调用选后者更轻。

第四类：垂直领域工具插件——偏应用的 MCP 封装。比如antv/visualization（AntV 可视化图表，支持 25+ 图表类型）、cdnxy/hellodb（数据库查询助手，Text2SQL）、joto/datafocus（幻觉可控的 Text2SQL + ChatBI）。这类插件本质是把某个垂直能力封装成 Dify 工具，部分通过 MCP 协议暴露。适用场景：你不想自己写 SQL 生成逻辑，直接装 HellDB 连上数据库就能问数。

选型口诀：要发布 Dify 能力给别人用 → MCP Server 插件；要调外部 MCP 工具 → MCP SSE 插件；Agent 节点要调 MCP → Agent 策略插件；要现成的垂直能力 → 应用类插件。

这里有个容易踩的坑：mcp_compat_dify_tools这个插件是把 Dify 工具的 API 转成 MCP 兼容 API，和mcp-server把工作流发布为 MCP 服务不是一回事。前者针对「工具」，后者针对「工作流/对话流」。装之前先想清楚你要暴露的是工具还是流程。

3. 可复制的 MCP 插件配置片段

这一节给能直接抄的配置。先说明：MCP 服务配置的 JSON 格式以官方文档为准，下面给的是通用结构，字段名按你实际用的插件微调。

场景一：在 Dify 工作流里用 MCP SSE 插件调外部 MCP 服务。

装好junjiem/mcp_sse后，在节点配置里填 MCP 服务信息。典型配置长这样：

{ "mcpServers": { "weather-service": { "url": "https://your-mcp-host/mcp", "transport": "streamable_http", "headers": { "Authorization": "Bearer YOUR_MCP_TOKEN" } }, "local-tools": { "command": "python", "args": ["-m", "my_mcp_server"], "transport": "stdio" } } }

注意transport字段：远程服务用streamable_http或sse，本地进程用stdio。Streamable HTTP 是当前推荐的主流远程传输方式，兼容标准 HTTP 流式语义，比纯 SSE 更灵活。

场景二：把 Dify 工作流发布为 MCP 服务（MCP Server 插件）。

装好hjlarry/mcp-server后，在插件配置里指定要暴露的工作流和端点路径。配置片段：

{ "endpoint": "/mcp", "server_name": "dify-workflow-server", "workflows": [ { "app_id": "your-dify-app-id", "name": "contract_review", "description": "合同审查工作流" } ] }

发布后，外部客户端（如 Cherry Studio）用这个 endpoint 连上来，就能看到contract_review这个工具。

场景三：Agent 策略插件配置 MCP 工具列表。

在 Agent 节点选好策略（Function Calling 或 ReAct）后，配置工具列表和 MCP 服务：

{ "agent_strategy": "function_calling", "tools": ["dify_builtin_tool"], "mcp_servers": { "internal_kb": { "url": "https://kb.internal/mcp", "transport": "streamable_http" } } }

如果你用的是 Claude Code 这类客户端去连 Dify 发布的 MCP 服务，配置要写全三件套——Base URL、Key、Model ID。以 Claude Code 的 settings 为例：

{ "mcpServers": { "dify-published": { "type": "http", "url": "https://your-dify-host/mcp", "headers": { "Authorization": "Bearer YOUR_DIFY_MCP_KEY" } } } }

Model ID 在客户端侧指定，比如claude-sonnet-4-5之类，具体看你客户端支持哪个。Base URL 就是 Dify 发布 MCP 服务后给出的 endpoint。

场景四：Cline MCP 配置连 Dify 工具。

如果你用 Cline 这类编辑器插件，MCP 配置通常放在cline_mcp_settings.json：

{ "mcpServers": { "dify-tools": { "url": "https://your-dify-host/mcp", "transport": "streamable_http", "headers": { "Authorization": "Bearer YOUR_KEY" } } } }

三件套同样要齐：Base URL（上面的 url）、Key（Authorization 里的 token）、Model ID（Cline 侧选模型时指定）。

配置写完别急着跑，先确认插件版本和 Dify 版本匹配。比如mcp_compat_dify_tools要求 Dify 1.2.0+，版本不够装了也白装。

4. FastMCP 服务实现原理与启动验证

FastMCP 是 MCP 协议的 Python 高层框架，核心价值是把 JSON-RPC 的通信细节、Schema 构造全藏起来，你只管写业务函数。它的实现原理可以拆成四块：协议封装、模块化组合、中间件机制、传输适配。

协议封装：装饰器自动生成 Schema。MCP 协议定义了 Tools、Resources、Prompts 三大组件。FastMCP 用装饰器把它们映射成 Python 函数：

from fastmcp import FastMCP mcp = FastMCP("DemoServer") @mcp.tool def multiply(a: float, b: float) -> float: """两数相乘""" return a * b @mcp.resource("weather://{city}/today") async def get_weather(city: str): return await fetch_weather_api(city) @mcp.prompt def analyze_users(user_ids: list[int]) -> str: return f"分析用户 {user_ids} 的行为数据"

@mcp.tool装饰器会读函数签名和类型注解，自动生成 MCP 需要的 JSON Schema。客户端调tools/list时，服务器返回的就是这些自动生成的描述。@mcp.resource支持 URI 模板动态访问，@mcp.prompt用于标准化 LLM 交互模板。

模块化组合：静态导入 vs 动态挂载。FastMCP 支持把多个子服务器组合成一个主服务器。静态导入（Importing）是复制子服务器的工具到主服务器，适合固化功能；动态挂载（Mounting）是实时链接，子服务器变更自动生效，适合迭代开发：

main_mcp = FastMCP("MainApp") weather_mcp = FastMCP("WeatherService") @weather_mcp.tool def get_forecast(city: str) -> str: return f"{city} 明天晴" main_mcp.mount(weather_mcp, prefix="weather")

挂载后，主服务器上工具名变成weather_get_forecast，前缀避免命名冲突。

中间件机制：责任链模式。FastMCP 2.9+ 引入中间件，支持在工具调用、资源访问等阶段插入横切逻辑（鉴权、日志、限流）：

from fastmcp.middleware import Middleware from fastmcp.exceptions import ToolError class AuthMiddleware(Middleware): async def on_call_tool(self, context): if not validate_token(context.request): raise ToolError("权限不足") return await call_next(context)

中间件支持嵌套挂载，父子服务器可以分层处理——全局鉴权放父服务器，局部日志放子服务器。

传输适配：Stdio / HTTP-SSE / Streamable HTTP。本地调试用 Stdio，通过标准输入输出管道传 JSON-RPC；远程服务用 HTTP-SSE 或 Streamable HTTP。Streamable HTTP 是当前推荐方案，兼容分块传输和 HTTP/2 多路复用，不依赖特定帧格式。

启动 FastMCP 服务并验证。写一个最小服务：

# server.py from fastmcp import FastMCP mcp = FastMCP("TestServer") @mcp.tool def add(a: int, b: int) -> int: return a + b if __name__ == "__main__": mcp.run(transport="streamable-http", host="0.0.0.0", port=8000)

启动命令：

python server.py

服务起来后，用 curl 验证工具列表：

curl -X POST http://localhost:8000/mcp \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

正常返回里能看到add工具的定义，包含自动生成的 inputSchema。再调一次工具：

curl -X POST http://localhost:8000/mcp \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"add","arguments":{"a":3,"b":5}}}'

返回{"result":{"content":[{"type":"text","text":"8"}]}}就说明服务通了。这一步验证完，再把这个 endpoint 填到 Dify 的 MCP SSE 插件里，链路就打通了。

5. 调用链路常见报错排查

链路跑不通时，按「客户端 → 传输 → 服务端」的顺序排查。下面列几个真实会遇到的报错。

报错一：401 Unauthorized。现象是 Dify 插件调 MCP 服务时返回 401。原因通常是 Authorization header 没带或 token 过期。排查：先确认 MCP 服务端是否要求鉴权，再检查插件配置里的headers.Authorization格式是不是Bearer YOUR_TOKEN。如果服务端用的是自定义 header 名（比如X-API-Key），别照抄 Bearer。

报错二：local proxy failed / connection refused。现象是插件报连接失败。原因分两种：一是 MCP 服务没起来，二是地址填错。排查：先在服务器上用 curl 直接打 MCP endpoint，确认服务活着；再检查 Dify 插件里填的 URL 是不是容器内能访问的地址。如果 Dify 跑在 Docker 里，localhost指的是容器自己，要用宿主机 IP 或容器网络别名。

报错三：reading choices / unexpected end of JSON input。现象是调用工具后解析返回失败。原因通常是传输方式不匹配——服务端用 Streamable HTTP，客户端却按纯 SSE 解析，或者反过来。排查：确认插件配置里的transport字段和服务端实际传输方式一致。Streamable HTTP 返回的是标准 HTTP 流，SSE 返回的是text/event-stream帧格式，两者解析逻辑不同。

报错四：OAuth 相关错误。现象是连某些托管平台（如 Composio）的 MCP 服务时报 OAuth 失败。原因通常是回调地址没配或 token 没刷新。排查：在托管平台侧确认 OAuth 应用的回调 URL 包含你的 Dify 实例地址，token 过期就重新授权。这类平台一般有内置的 OAuth 管理，按平台文档走。

报错五：工具列表为空。现象是插件连上了但看不到工具。原因可能是服务端tools/list返回空，或者插件过滤了。排查：用 curl 直接调tools/list看返回，如果服务端有工具但插件看不到，检查插件版本是否支持该传输方式。

报错六：Agent 节点不调用 MCP 工具。现象是 Agent 策略选了但工具没被触发。原因通常是策略和工具类型不匹配——比如选了只支持 Function Calling 的策略，却期望 ReAct 的多步推理。排查：确认 Agent 策略插件支持你要的调用模式，Function Calling 适合单步工具调用，ReAct 适合多步规划。

排查通用套路：先用 curl 绕过 Dify 直接打 MCP 服务，确认服务本身没问题；再检查 Dify 插件配置的 URL、transport、headers 三要素；最后看 Dify 日志里的具体报错。大部分问题出在传输方式不匹配和地址填错这两点上。

6. 从插件注册到服务响应的完整链路与接入建议

把整条链路串起来看：你在 Dify 里装 MCP 插件 → 插件注册工具/服务 → 工作流节点或 Agent 节点触发调用 → 插件按配置的传输方式发 JSON-RPC 请求 → MCP 服务端（可能是 FastMCP 写的，也可能是托管平台）解析请求、执行工具 → 返回结构化响应 → 插件解析后交给 Dify 后续节点。

这条链路里，FastMCP 扮演的是「服务端快速实现」的角色。它把 MCP 协议的 JSON-RPC 封装、Schema 生成、传输适配全包了，你写业务逻辑就行。Dify 插件扮演的是「客户端适配」角色，把 MCP 的工具发现和调用能力接进工作流。

如果你要自己搭一套，建议顺序是：先用 FastMCP 写一个最小 MCP 服务（就一个 add 工具），本地 curl 验证通；再在 Dify 里装 MCP SSE 插件，把这个服务配进去，跑通一次工具调用；最后再往上加复杂工具和 Agent 策略。别一上来就搞一堆工具，出错了不好定位。

接入时几个实用建议：传输方式优先选 Streamable HTTP，兼容性和性能都比纯 SSE 好；鉴权 token 别硬编码在配置里，用环境变量或 Dify 的凭据管理；MCP 服务端和 Dify 实例的网络要通，跨容器注意地址；Agent 策略按需选，Function Calling 够用就别上 ReAct，省 token。

需要拿 Key 或看接入文档的话，可以走 API Keys 和 接入文档；想先验证模型对话效果，用 模型对话；如果是长期跑编码或 Agent 任务，Coding Plan 更合适。官网入口在 这里，API 地址是https://taotoken.net/api。

最后补一个实测经验：Dify 插件市场里的 MCP 插件更新挺快，装之前先看插件详情页的版本要求和 Dify 版本是否匹配。我试过在 1.5.0 上装一个要求 1.6.0 的插件，装上了但配置页报错，换回兼容版本就好了。版本对齐这一步别省。