Dify MCP 集成实验01环境地基与首个 MCP Server——MCP 新版 SDK 如何从零跑通Dify 实验系列 · MCP 集成 01/6 | 实验编号DIFY-107-01基于 Dify 1.16.1 实测2026-081. 业务场景先讲一个我们实际遇到的场景。一家做客服工单 SaaS 的公司交付一个「企业级 AI 智能体系统集成」项目外部系统数据要通过 MCP 进 Dify。交付工程师开工后的第一件事不是写业务逻辑而是把开发环境搭起来、跑通第一个 server——就像盖楼先打地基。第一个工具选什么一个「当前时间」工具记录工单创建时间戳、排障时取基准时间、看板定时任务的调度基准。它无外部依赖、参数少、结果确定是最简单的真实工具适合当第一个 server 练手。我们第一次接这类需求时第一反应是「装个 SDK 写个 server 能有多难」。真正动手才发现——第一个坑不在业务在地基SDK 2.0 把旧 API 整个换掉、Python 3.14 装不上 wheel、Dify 只消费远程 HTTP 端点根本不走 stdio——环境没搭对后面 02-06 的实验全部白搭。这个实验就是先把地基打牢。这不是个例。任何「外部系统数据要进 Dify」的集成都是这个模式Dify 只消费远程 HTTP/SSE 端点源码确认无 stdio——server 必须能部署成可访问的 HTTP 端点后续 02-06 实验的「Dify 连接」假设才成立。2. 场景痛点这个流程的痛点在起步阶段体现得最直接SDK 版本坑mcp 2.0.0 是 2026 新版API 大改——mcp.server.fastmcp模块不存在旧教程里的 FastMCP 写法全部过时照网上教程装直接报错。Python 版本不兼容3.14 装 mcp 有 wheel 兼容风险——环境没搭对后面所有实验全白搭。部署形态不清不知道 Dify 只消费远程 HTTP 端点在 stdio 模式下折腾半天永远接不进 Dify。端点路径不明streamable-http 默认端点/mcp配置错路径全链路 404——跑通了也连不上。本质上环境地基决定了后面 02-06 全部实验能不能跑——地基没打牢上层全悬空。3. 方案为什么是 MCP 官方 SDK Streamable HTTP打通 MCP Server 开发环境地基最直接的路就是官方 SDK 2.0 Streamable HTTP 部署。选它的理由官方 SDK 2.0 一套代码三传输MCPServer类 server.tool()装饰器 run(transport...)——stdio开发验证/ streamable-http部署形态/ sse 一条代码切换Streamable HTTP 是 Dify 接入形态Dify 只消费远程 HTTP/SSE 端点server 必须部署成可访问的 HTTP 端点——本实验就是把这个形态跑通与 106-01 插件同一业务需求time_tool 插件的需求用 MCP 再实现一遍天然构成「插件 vs MCP 同需求双实现」的对照起点。这篇文章我们就用它搭第一个 MCP Server——「当前时间」工具走完 SDK 安装 → server 结构 → 工具定义 → stdio 本地验证 → Streamable HTTP 部署的全生命周期。4. 整体架构HTTP本地开发机Python 3.11 venv mcp 2.0.0uv 管理dify107_01_time_serverstdio 模式本地客户端验证Streamable HTTP 端点uvicorn :8901/mcpDify 服务器Docker ComposeapiFastAPIweb控制台工具页 MCP tab107-03 实测经 SSRF 代理接入链路很清晰本地开发机Python venv server→ Streamable HTTP 端点 → Dify 服务器api/web。关键设计是 stdio 模式先本地验证工具逻辑再以 streamable-http 部署成 Dify 可访问的端点——先证明工具对再证明能连。5. 模块设计5.1 环境三件套本实验核心# 1. 建 venv一次Python 3.113.14 装 mcp 有 wheel 兼容风险106 教训延续cddify-107/tmpuv venv--python3.11venv311# 2. 装 SDK官方 mcp 2.0.0自动带 uvicorn/starlette/anyiouv pipinstall--pythonvenv311 mcp# 3. 启动 Streamable HTTP 部署Dify 接入形态venv311/Scripts/python server.py http# → http://0.0.0.0:8901/mcp5.2 Server 骨架与工具定义SDK 2.0 新 APIfrommcp.server.mcpserverimportMCPServer serverMCPServer(namedify107_01_time_server,version1.0.0,description客服工单 SaaS 时间基准工具,)server.tool()defget_current_time(timezone:strlocal)-dict:返回当前时间、时区与 UTC 偏移可选参数 timezone...# 三传输stdio开发验证/ streamable-http部署形态/ sseif__name____main__:server.run(transportstdioifsys.argv[1:][stdio]elsestreamable-http,host0.0.0.0,port8901)注意mcp 2.0.0是 2026 新版API 大改——mcp.server.fastmcp模块不存在旧教程里的 FastMCP 写法全部过时新 API 在mcp.server.mcpserverMCPServer 类 server.tool()装饰器 run(transport...)。6. 运行验证输入预期结果stdio 调用UTC82026-08-05 20:43:53offset8h通过stdio 调用UTC-52026-08-05 07:43:53offset-5h时差正确通过stdio 调用UTC12次日00:43:53通过HTTP 端点 tools/list返回get_current_time工具通过HTTP 调用local 默认本地时区 8h 正确通过错误路径无效参数isErrorTrue 中文错误信息透传通过7. 实战坑坑现象修复mcp 2.0.0 API 大改mcp.server.fastmcp模块不存在旧教程 FastMCP 写法全报错新 APIMCPServerserver.tool()run(transport...)实测Python 3.14 不兼容3.14 装 mcp 有 wheel 风险106 教训延续uv venv --python 3.11uv pip install mcp实测list_tools 返回结构返回的不是 list 也不是元组是ListToolsResult对象访问listing.tools分页字段驼峰nextCursor实测pydantic 字段别名协议 JSON 字段驼峰isError写res.isError报 AttributeErrorPython 属性访问用 snake_caseres.is_error实测工具错误返回server 内 raise ValueError客户端收到isErrorTrue “Error executing tool xxx: 信息”错误信息透传实测默认端点路径run(transportstreamable-http)默认端点/mcp用streamable_http_path参数可改实测Windows 路径MSYS/d/路径在 Windows 程序里报错一律D:\格式106 教训延续8. 实验文档及源码获取实验文档完整操作步骤DIFY-107-01环境地基与首个MCP Server.mdServer 源码server.py | dify107_01_time_server 目录交付验证记录环境搭建 双模式验证 对照表初稿验证记录-01-环境地基与首个MCP Server.md全部目录dify-107/experiments | dify-107/dsl | dify-107/servers | dify-107/delivery文章聚焦核心配置与采坑点实验的完整分步操作节点搭建/参数表/调试指引见实验文档原文。下一篇Dify MCP 集成实验02工具进阶与协议原语——MCP 三原语如何落地 你在这个实验的场景里踩过什么坑欢迎评论区分享你的实战经验。
Dify MCP 集成实验01环境地基与首个 MCP Server——MCP 新版 SDK 如何从零跑通Dify 实验系列 · MCP 集成 01/6 | 实验编号DIFY-107-01基于 Dify 1.16.1 实测2026-081. 业务场景先讲一个我们实际遇到的场景。一家做客服工单 SaaS 的公司交付一个「企业级 AI 智能体系统集成」项目外部系统数据要通过 MCP 进 Dify。交付工程师开工后的第一件事不是写业务逻辑而是把开发环境搭起来、跑通第一个 server——就像盖楼先打地基。第一个工具选什么一个「当前时间」工具记录工单创建时间戳、排障时取基准时间、看板定时任务的调度基准。它无外部依赖、参数少、结果确定是最简单的真实工具适合当第一个 server 练手。我们第一次接这类需求时第一反应是「装个 SDK 写个 server 能有多难」。真正动手才发现——第一个坑不在业务在地基SDK 2.0 把旧 API 整个换掉、Python 3.14 装不上 wheel、Dify 只消费远程 HTTP 端点根本不走 stdio——环境没搭对后面 02-06 的实验全部白搭。这个实验就是先把地基打牢。这不是个例。任何「外部系统数据要进 Dify」的集成都是这个模式Dify 只消费远程 HTTP/SSE 端点源码确认无 stdio——server 必须能部署成可访问的 HTTP 端点后续 02-06 实验的「Dify 连接」假设才成立。2. 场景痛点这个流程的痛点在起步阶段体现得最直接SDK 版本坑mcp 2.0.0 是 2026 新版API 大改——mcp.server.fastmcp模块不存在旧教程里的 FastMCP 写法全部过时照网上教程装直接报错。Python 版本不兼容3.14 装 mcp 有 wheel 兼容风险——环境没搭对后面所有实验全白搭。部署形态不清不知道 Dify 只消费远程 HTTP 端点在 stdio 模式下折腾半天永远接不进 Dify。端点路径不明streamable-http 默认端点/mcp配置错路径全链路 404——跑通了也连不上。本质上环境地基决定了后面 02-06 全部实验能不能跑——地基没打牢上层全悬空。3. 方案为什么是 MCP 官方 SDK Streamable HTTP打通 MCP Server 开发环境地基最直接的路就是官方 SDK 2.0 Streamable HTTP 部署。选它的理由官方 SDK 2.0 一套代码三传输MCPServer类 server.tool()装饰器 run(transport...)——stdio开发验证/ streamable-http部署形态/ sse 一条代码切换Streamable HTTP 是 Dify 接入形态Dify 只消费远程 HTTP/SSE 端点server 必须部署成可访问的 HTTP 端点——本实验就是把这个形态跑通与 106-01 插件同一业务需求time_tool 插件的需求用 MCP 再实现一遍天然构成「插件 vs MCP 同需求双实现」的对照起点。这篇文章我们就用它搭第一个 MCP Server——「当前时间」工具走完 SDK 安装 → server 结构 → 工具定义 → stdio 本地验证 → Streamable HTTP 部署的全生命周期。4. 整体架构HTTP本地开发机Python 3.11 venv mcp 2.0.0uv 管理dify107_01_time_serverstdio 模式本地客户端验证Streamable HTTP 端点uvicorn :8901/mcpDify 服务器Docker ComposeapiFastAPIweb控制台工具页 MCP tab107-03 实测经 SSRF 代理接入链路很清晰本地开发机Python venv server→ Streamable HTTP 端点 → Dify 服务器api/web。关键设计是 stdio 模式先本地验证工具逻辑再以 streamable-http 部署成 Dify 可访问的端点——先证明工具对再证明能连。5. 模块设计5.1 环境三件套本实验核心# 1. 建 venv一次Python 3.113.14 装 mcp 有 wheel 兼容风险106 教训延续cddify-107/tmpuv venv--python3.11venv311# 2. 装 SDK官方 mcp 2.0.0自动带 uvicorn/starlette/anyiouv pipinstall--pythonvenv311 mcp# 3. 启动 Streamable HTTP 部署Dify 接入形态venv311/Scripts/python server.py http# → http://0.0.0.0:8901/mcp5.2 Server 骨架与工具定义SDK 2.0 新 APIfrommcp.server.mcpserverimportMCPServer serverMCPServer(namedify107_01_time_server,version1.0.0,description客服工单 SaaS 时间基准工具,)server.tool()defget_current_time(timezone:strlocal)-dict:返回当前时间、时区与 UTC 偏移可选参数 timezone...# 三传输stdio开发验证/ streamable-http部署形态/ sseif__name____main__:server.run(transportstdioifsys.argv[1:][stdio]elsestreamable-http,host0.0.0.0,port8901)注意mcp 2.0.0是 2026 新版API 大改——mcp.server.fastmcp模块不存在旧教程里的 FastMCP 写法全部过时新 API 在mcp.server.mcpserverMCPServer 类 server.tool()装饰器 run(transport...)。6. 运行验证输入预期结果stdio 调用UTC82026-08-05 20:43:53offset8h通过stdio 调用UTC-52026-08-05 07:43:53offset-5h时差正确通过stdio 调用UTC12次日00:43:53通过HTTP 端点 tools/list返回get_current_time工具通过HTTP 调用local 默认本地时区 8h 正确通过错误路径无效参数isErrorTrue 中文错误信息透传通过7. 实战坑坑现象修复mcp 2.0.0 API 大改mcp.server.fastmcp模块不存在旧教程 FastMCP 写法全报错新 APIMCPServerserver.tool()run(transport...)实测Python 3.14 不兼容3.14 装 mcp 有 wheel 风险106 教训延续uv venv --python 3.11uv pip install mcp实测list_tools 返回结构返回的不是 list 也不是元组是ListToolsResult对象访问listing.tools分页字段驼峰nextCursor实测pydantic 字段别名协议 JSON 字段驼峰isError写res.isError报 AttributeErrorPython 属性访问用 snake_caseres.is_error实测工具错误返回server 内 raise ValueError客户端收到isErrorTrue “Error executing tool xxx: 信息”错误信息透传实测默认端点路径run(transportstreamable-http)默认端点/mcp用streamable_http_path参数可改实测Windows 路径MSYS/d/路径在 Windows 程序里报错一律D:\格式106 教训延续8. 实验文档及源码获取实验文档完整操作步骤DIFY-107-01环境地基与首个MCP Server.mdServer 源码server.py | dify107_01_time_server 目录交付验证记录环境搭建 双模式验证 对照表初稿验证记录-01-环境地基与首个MCP Server.md全部目录dify-107/experiments | dify-107/dsl | dify-107/servers | dify-107/delivery文章聚焦核心配置与采坑点实验的完整分步操作节点搭建/参数表/调试指引见实验文档原文。下一篇Dify MCP 集成实验02工具进阶与协议原语——MCP 三原语如何落地 你在这个实验的场景里踩过什么坑欢迎评论区分享你的实战经验。
![[光学原理与应用-521]：对光的错误理解与纠偏](http://pic.xiahunao.cn/yaotu/[光学原理与应用-521]：对光的错误理解与纠偏)
