超实用！Dify 快速接入本地 MCP 服务：config.toml 配置与连通性验证

1. 本地 MCP 服务接进 Dify卡在哪一步Dify 接入本地 MCP 服务这件事说穿了就是让 Dify 里的 Agent 能通过 HTTP 通道把请求发给跑在你本机上的 MCP Server再把工具执行结果拿回来喂给大模型。听起来简单但真正动手时大部分人卡在三个地方一是 MCP Server 到底该用哪种 transport 暴露出来二是 Dify 的 MCP 插件配置里那串 JSON 到底怎么写才不报错三是配完之后怎么确认链路真的通了而不是 Agent 假装调用了工具。我自己第一次配的时候MCP Server 明明在本地跑着curl 也能通但 Dify 里就是提示连接失败折腾了半天才发现是 transport 类型和端口路径对不上。所以这篇不打算重复讲 MCP 是什么协议、为什么需要它而是直接聚焦一件事你手上已经有一个本地 MCP 服务怎么用一份可复制的 config.toml 骨架和 settings.json 关键字段把它稳稳当当地接进 Dify并且用一次真实请求验证整条调用链路。适合谁看如果你已经用 Spring AI、FastMCP 或者自己写的 HTTP 服务把 MCP Server 跑起来了现在想让 Dify 的 Agent 能调用它那这篇就是给你写的。如果你还没写 MCP Server建议先把服务端跑通再回来因为 Dify 这边只认 HTTP 地址服务端没起来配置写得再漂亮也没用。2. 前置准备TaoToken 通道与本地 MCP 服务就位在动 Dify 配置之前有两件事必须先确认好否则后面排障会多花一倍时间。第一件是模型通道。Dify 里的 Agent 需要调用大模型来理解用户意图、决定调哪个工具所以你得有一个稳定的模型 API 入口。我这边习惯用 TaoToken 做统一通道它的 API 地址是https://taotoken.net/api兼容 OpenAI 风格的调用方式在 Dify 的模型供应商配置里填上 Base URL 和 API Key 就能用。API Key 在控制台的 API Keys 页面生成地址是https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapikeys。如果你还没配模型先去把这一步做了不然后面 Agent 跑不起来。第二件是本地 MCP 服务。假设你已经有一个跑在127.0.0.1:8000的 MCP Server暴露的是 SSE 端点/sse。确认它活着的最简单方式是用 curl 打一下curl -N http://127.0.0.1:8000/sse如果能看到持续输出的事件流类似event: endpoint开头的内容说明服务端正常。如果连接被拒绝先检查服务是否启动、端口是否被占用。这一步别跳过我见过太多人 Dify 配了半天最后发现是本地服务根本没起来。注意Dify 只支持 HTTP 协议的 MCP 服务调用stdio 类型的本地服务需要先通过 SSE 或 streamable_http 方式暴露成 HTTP 端点否则 Dify 连不上。3. 可复制配置config.toml 骨架与 settings.json 关键字段这一节是核心直接给可复制的配置。分两部分MCP Server 侧的 config.toml 骨架和 Dify 侧的 settings.json 字段。3.1 MCP Server 侧 config.toml 骨架如果你用的是支持 TOML 配置的 MCP Server 框架比如某些 Python 或 Rust 实现下面这份骨架可以直接改[server] name local-weather-mcp version 1.0.0 transport sse host 127.0.0.1 port 8000 sse_endpoint /sse message_endpoint /mcp/message [server.timeout] request 50 sse_read 50 [tools.weather] enabled true description 根据城市名称获取天气预报关键字段说明transport决定暴露方式Dify 能接的是sse和streamable_httpsse_endpoint是 Dify 配置里要填的 URL 路径message_endpoint是 SSE 模式下客户端回传消息的路径别写错。如果你用的是 Spring AI 的 webflux starter配置项名字会略有不同但核心就是spring.ai.mcp.server.type和端口路径。3.2 Dify 侧 settings.json 关键字段Dify 的 MCP 插件配置支持两种 JSON 格式一种是扁平的多服务写法一种是带mcpServers包裹的写法。两种都行我习惯用后者结构更清晰{ mcpServers: { local_weather: { transport: sse, url: http://127.0.0.1:8000/sse, headers: {}, timeout: 50, sse_read_timeout: 50 }, local_db: { transport: streamable_http, url: http://127.0.0.1:8002/mcp, headers: { Authorization: Bearer your-token-if-needed }, timeout: 50 } } }字段对照表字段作用建议值transport传输协议类型sse 或 streamable_httpurlMCP 服务完整地址含端口和路径headers自定义请求头需要鉴权时填timeout请求超时秒数50sse_read_timeoutSSE 读取超时50这里有个坑url必须写完整路径包括/sse或/mcp不能只写到端口。我第一次配的时候只写了http://127.0.0.1:8000Dify 直接报连接失败补上路径就好了。4. 验证请求一次跑通本地 MCP 调用链路配置填完之后别急着在 Agent 里问复杂问题先用一个最小请求验证链路。4.1 在 Dify 里创建测试 Agent进入 Dify 的 Agent 编排页面Agent 策略选支持 MCP 工具的那个通常是 Agent 策略里带 MCP 标识的选项。LLM 选你通过 TaoToken 配好的模型。然后在工具配置区域把上面那段 settings.json 贴进 MCP 服务配置框保存。保存后 Dify 会尝试连接你的本地 MCP 服务如果配置正确工具列表里应该能看到local_weather下面挂的getWeatherByCity工具。如果看不到说明连接没通跳到第 5 节排障。4.2 发一次真实请求在 Agent 的对话输入框里输入帮我查一下西安的天气预期行为Agent 识别出需要调用天气工具通过 MCP 通道请求本地服务本地服务返回「晴天」Agent 把结果组织成自然语言回复你。如果你在本地 MCP Server 的日志里看到类似Received tools/call request: getWeatherByCity的记录说明链路完全通了。这一步的验证价值在于它同时验证了 Dify 到 MCP Server 的网络连通、transport 协议匹配、工具注册和参数传递四个环节。4.3 用 curl 单独验证 MCP 端点如果 Dify 里看不到工具可以先绕过 Dify直接用 curl 验证 MCP 端点是否正常响应curl -N -H Accept: text/event-stream http://127.0.0.1:8000/sse正常的话会返回 SSE 事件流包含 endpoint 信息和后续的工具列表事件。如果这一步就不通问题在 MCP Server 侧跟 Dify 无关。5. 本篇常见错排查配不通常见就下面几种情况对着查基本能解决。连接被拒绝Connection refusedMCP Server 没启动或者端口写错。先curl本地地址确认服务活着。如果服务在 Docker 里跑注意127.0.0.1在容器内指向容器本身需要用宿主机的实际 IP 或host.docker.internal。transport 类型不匹配服务端暴露的是 SSEDify 配置里写了streamable_http或者反过来。看服务端日志里实际监听的协议类型两边保持一致。SSE 的 URL 通常以/sse结尾streamable_http 通常以/mcp结尾。URL 路径不完整只写了http://127.0.0.1:8000没带/sse。Dify 不会自动补路径必须写全。工具列表为空连接通了但看不到工具通常是 MCP Server 侧的工具注册没生效。检查服务端代码里工具是否通过ToolCallbackProvider或类似机制正确暴露重启服务后再试。超时设置太短本地服务如果首次调用有冷启动50 秒一般够用。如果频繁超时把timeout和sse_read_timeout都调到 120 试试。Dify 容器网络隔离如果 Dify 是 Docker 部署的容器内的127.0.0.1不是你的宿主机。需要把 URL 里的127.0.0.1换成宿主机的局域网 IP或者配置host.docker.internal映射。排障时如果发现是模型通道的问题比如 Agent 不调用工具、回复异常可以去 TaoToken 的接入文档核对 Base URL 和模型名配置https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc。6. 稳定调用与后续扩展链路跑通之后有几个实践细节能让它更稳。第一本地 MCP 服务的端口别用随机端口固定下来写进配置避免每次重启后 Dify 配置失效。第二如果 MCP 服务需要鉴权在 settings.json 的headers里加Authorization别把 token 硬编码在 URL 里。第三多个 MCP 服务可以同时配在同一个 JSON 里Dify 会分别连接工具列表会按服务名分组Agent 调用时按需选择。如果你打算长期用 Dify 跑编码类或 Agent 类任务频繁调用模型和工具可以看看 TaoToken 的 Coding Plan走套餐方式比按量计费更划算地址是https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcodingplan。想先验证模型对话效果的话模型对话入口在https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentchat。最后说个我踩过的坑Dify 的 MCP 插件版本更新后settings.json 的字段名偶尔会变比如sse_read_timeout在某些版本里叫read_timeout。如果配置明明没问题却连不上先去插件文档确认当前版本的字段名别死磕旧配置。