1. 云 Dify 连本地 MCP 服务报 failed to get endpoint URL 到底卡在哪你如果在云端的 Dify 里配置了一个 MCP 工具点保存或调用时直接抛出failed to get endpoint URL第一反应通常是“我地址写错了”。但实际排查下来这个报错覆盖的范围比想象中宽它可能是 Dify 根本没拿到一个合法的 URL也可能是拿到了 URL 但请求发不出去还可能是协议、路径、端口映射任意一环对不上。先把概念对齐。MCP 是 Model Context Protocol你可以把它理解成“给大模型用的 USB 接口标准”模型通过这个协议去调用外部工具、读文件、查数据库。Dify 作为编排平台支持把 MCP Server 挂进来当工具用。问题在于云 Dify 跑在公网服务器上而你的 MCP Server 往往跑在自己电脑或内网机器上两边不在同一个网络里。failed to get endpoint URL本质上是 Dify 在“我该往哪个地址发请求”这一步就没走通。这个报错最常见的三类根因我按出现频率排一下第一类是地址暴露问题。本地服务监听的是127.0.0.1或localhost这个地址只有本机自己能访问云 Dify 从公网发请求过来DNS 解析或连接直接失败Dify 拿不到有效 endpoint就报这个错。第二类是端口映射与路径问题。你把本地端口映射出去了但映射的是httpDify 侧要求https或者映射到了根路径而 MCP 服务实际挂在/mcp子路径上。excerpt 里提到的“没加 /mcp 一直不通”就是典型。第三类是协议不匹配。MCP 有 stdio、SSE、HTTP 等传输方式云 Dify 通过 URL 接入时走的是 HTTP/SSE 类传输如果你本地起的是 stdio 模式那它压根不监听端口自然没有 endpoint URL 可给。这篇就围绕config.toml这个配置骨架把地址怎么写、端口怎么映射、协议怎么选讲清楚最后给你一段能直接复制的 curl 验证命令让你在填进 Dify 之前先自己确认服务是活的。适合正在用云 Dify 接本地 MCP、被这个报错卡住的同学。2. TaoToken 前置先把模型侧和 MCP 侧的网络边界理清在动手改config.toml之前有个容易被忽略的前置动作确认你的模型调用链路和 MCP 调用链路是两条独立的线。很多人把 Dify 里的模型配置和 MCP 工具配置混在一起排查结果越查越乱。模型侧也就是 Dify 里对话用的 LLM如果你用的是兼容 OpenAI 协议的服务可以走 TaoToken 的 API 接入。它的 Base URL 是https://taotoken.net/api在 Dify 的模型供应商里选 OpenAI 兼容类型把 Base URL 和 API Key 填进去即可。这一步和 MCP 报错没有直接关系但它能帮你排除“是不是整个 Dify 的网络都出不去”这种全局性问题——如果模型对话正常说明 Dify 出网没问题那failed to get endpoint URL就锁定在 MCP 这一侧。MCP 侧才是重点。云 Dify 要访问你的本地 MCP Server中间必须有一座“桥”。这座桥的作用是把内网服务暴露成一个公网可访问的 HTTPS 地址。注意这里的关键词是 HTTPS不是 HTTP。云 Dify 在多数版本里对 MCP endpoint 的校验会要求https://开头你填http://可能连保存都过不去或者保存了但请求阶段失败。所以前置准备清单是这样的你的本地 MCP Server 要能正常启动并且在本地用 curl 能访问通。这一步没通后面全白搭。你要有一个能把本地端口映射到公网 HTTPS 地址的通道。这个通道给你一个形如https://xxxx.example.com的公网域名。你要清楚你的 MCP Server 挂载的路径。是根路径/还是/mcp还是/sse。这个路径要拼在公网域名后面。关于 API Key 的获取和模型对话的调试可以到 TaoToken 的控制台里创建地址是https://taotoken.net/consoleAPI Keys 管理在https://taotoken.net/api-keys。如果你打算长期跑编码类 Agent 或者把 MCP 工具链固定下来Coding Plan 会更省心入口在https://taotoken.net/coding-plan。这些是模型侧的准备和 MCP 的 endpoint 是两码事但建议一起配好免得来回切换。有一点要提醒不要把 MCP Server 直接连到生产数据库上。MCP 工具能执行的操作权限不小本地测试阶段用测试库或者只读账号这是基本的安全习惯。3. config.toml 骨架endpoint URL 填写规范与可复制片段现在进入正题。MCP Server 的配置通常放在一个config.toml里不同实现比如某些 Python 或 Node 的 MCP 框架字段名略有差异但核心结构一致。下面给一份通用骨架你按自己用的框架对照调整。# config.toml - MCP Server 配置骨架 [server] # 服务监听地址。关键云 Dify 要访问不能只监听 127.0.0.1 host 0.0.0.0 # 监听端口和你的端口映射保持一致 port 8080 # 传输协议云 Dify 通过 URL 接入时用 http 或 sse不要用 stdio transport http [mcp] # MCP 挂载路径。Dify 里填的 URL 要带上这个路径 path /mcp # 是否启用 SSE部分 Dify 版本走 SSE 传输 sse_enabled true [endpoint] # 对外暴露的公网地址必须是 https public_url https://your-tunnel-domain.example.com # 完整 endpointDify 里就填这个 full_endpoint https://your-tunnel-domain.example.com/mcp几个字段逐个说清楚。host 0.0.0.0是最容易踩的坑。如果你写127.0.0.1服务只接受本机回环连接端口映射工具从外部转发进来的请求会被拒绝。写0.0.0.0表示监听所有网卡映射通道才能把流量送进来。这是failed to get endpoint URL的高频原因之一。transport字段决定服务以什么方式对外。云 Dify 通过 URL 接入对应的是 HTTP 或 SSE 传输。如果你本地配的是stdio服务不会开端口也就没有 URL 可填。stdio 模式适合本地进程间调用不适合云 Dify 这种跨网络场景。path /mcp是挂载路径。Dify 里填的完整 URL 必须是公网域名 path。excerpt 里说“之前一直没通是没加 /mcp”就是这个原因。你本地http://127.0.0.1:8080/mcp能通不代表公网地址不加/mcp也能通。public_url和full_endpoint是给你自己对照用的。真正填进 Dify 的是full_endpoint那个值。注意协议头必须是https://不是http://。如果你用的是 Cline 或 Claude Code 这类客户端配置结构会不一样。Cline 的 MCP 配置通常在 settings JSON 里Claude Code 走的是~/.claude/settings.json或项目级配置。但不管哪个客户端三件套是固定的Base URLendpoint、Key如果需要鉴权、Model ID模型侧。MCP 这一侧主要是 Base URL 和路径鉴权看你的 MCP Server 有没有开。再强调一次路径拼接规则本地地址公网映射后Dify 里应填http://127.0.0.1:8080/mcphttps://xxx.example.comhttps://xxx.example.com/mcphttp://127.0.0.1:8080/ssehttps://xxx.example.comhttps://xxx.example.com/ssehttp://127.0.0.1:8080/https://xxx.example.comhttps://xxx.example.com/映射通道给你的域名通常不带路径路径要你自己按 MCP Server 的实际挂载点补上。补错了就是 404 或连接超时Dify 侧表现可能就是failed to get endpoint URL。4. 连通性验证curl 请求与成功结果对照配置写完别急着填进 Dify。先在本地和公网两个层面各验证一次。这一步能帮你把问题范围缩小到“服务本身”还是“映射通道”。第一步本地验证。启动你的 MCP Server然后开一个终端# 本地直连确认服务活着 curl -i http://127.0.0.1:8080/mcp预期结果返回 HTTP 状态码可能是 200、400 或 405取决于 MCP Server 对 GET 的处理。关键是你能看到响应头说明服务在监听、路径对得上。如果返回Connection refused说明服务没起来或者端口不对如果返回 404说明/mcp路径不对。第二步公网验证。用映射通道给你的公网域名# 公网地址验证注意是 https curl -i https://your-tunnel-domain.example.com/mcp预期结果和本地验证类似的响应。如果这一步超时说明映射通道没把流量送到本地检查映射工具是否在运行、端口是否填对。如果返回 502 或 503说明通道通了但后端服务没响应回到第一步检查本地服务。第三步模拟 Dify 的请求方式。MCP 的 HTTP 传输通常用 POST 发 JSON-RPC 请求# 模拟 MCP 初始化请求 curl -i -X POST https://your-tunnel-domain.example.com/mcp \ -H Content-Type: application/json \ -d { jsonrpc: 2.0, id: 1, method: initialize, params: { protocolVersion: 2024-11-05, capabilities: {}, clientInfo: {name: test, version: 1.0} } }预期结果返回一个 JSON-RPC 响应包含result字段和 serverInfo。如果返回Method not found说明路径对了但方法不支持检查 MCP Server 版本。如果返回 401说明需要鉴权你需要在 Dify 里补上对应的 Header 或 Token。三步都通过之后再把https://your-tunnel-domain.example.com/mcp填进 Dify 的 MCP 配置里。这时候如果还报failed to get endpoint URL问题就不在地址本身而在 Dify 侧的解析或网络策略比如 Dify 所在环境对某些域名有出网限制。验证通过后你可以在 Dify 里建一个简单的对话流挂上这个 MCP 工具发一句会触发工具调用的话看返回是否正常。模型侧如果要用 TaoToken模型对话调试入口在https://taotoken.net/models可以先用它确认模型链路是通的再叠加 MCP 工具。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth报错不止failed to get endpoint URL一个实际排查中你会遇到一串。下面按真实报错对照给排查方向。401 Unauthorized。MCP Server 开了鉴权但 Dify 侧没带 Token。检查你的 MCP 配置里有没有AuthorizationHeader值是不是Bearer token。有些 MCP 实现用 API Key 放在 query 参数里那就把 Key 拼到 URL 后面。注意别把 Key 写进会公开的配置文件里。local proxy failed。这个通常出现在你本地用了某种转发工具的场景。含义是本地转发进程没起来或者转发规则配错了。检查转发工具的日志确认它监听的本地端口和 MCP Server 的端口一致且转发目标是127.0.0.1:8080这种正确地址。如果转发工具要求 HTTPS 上游而你的 MCP 是 HTTP也会报这个。reading choices 相关报错。这类错误一般出现在模型侧返回结构解析时比如你用的是 OpenAI 兼容接口但返回体里没有choices字段。排查方向是模型 Base URL 和 Model ID 是否匹配。如果你在 Dify 里同时配了模型和 MCP先单独测模型对话确认模型返回正常再挂 MCP。TaoToken 的接入文档在https://taotoken.net/doc里面有 Base URL 和 Model ID 的对照说明。OAuth 相关报错。部分 MCP Server 或客户端走 OAuth 授权流程报错可能是invalid_client、redirect_uri mismatch。检查你在授权平台注册的回调地址是否和实际使用的一致。云 Dify 场景下回调地址往往要填 Dify 的公网地址这个容易填错。如果 MCP Server 不强制 OAuth可以先关掉鉴权把链路跑通再逐步加回来。连接超时但本地正常。这是最迷惑的一种。本地 curl 通公网 curl 超时。原因通常是映射通道只监听了 IPv4 而你的域名解析到 IPv6或者通道有访问白名单没放行 Dify 的出口 IP。检查通道的访问控制设置必要时临时放开来源限制测试。路径重复或缺失。有人填成https://xxx.example.com/mcp/mcp有人填成https://xxx.example.com。前者是映射通道本身带了路径你又加了一次后者是漏了/mcp。对照第 3 节的表格逐字核对。协议头写错。填了http://但 Dify 要求https://。有些映射通道同时提供 http 和 https你复制的时候可能复制到了 http 那个。以https://为准。排查顺序建议固定下来先本地 curl再公网 curl再 POST 模拟最后填 Dify。每一步的报错对应不同层不要跳步。跳步的结果就是所有问题混在一起越查越乱。6. 把链路固定下来从临时验证到长期可用临时验证通过不代表长期可用。映射通道的域名可能会变本地服务重启后端口可能被占这些都会让原本能用的 MCP 突然报failed to get endpoint URL。所以最后说几个让链路稳定的做法。第一把 MCP Server 做成开机自启或进程守护。用 systemd 或者 pm2 这类工具保证服务挂了能自动拉起。服务不在endpoint 自然拿不到。第二映射通道选固定域名的那种。临时域名每次重启都变你就要反复改 Dify 配置。固定域名省事很多。第三把config.toml里的public_url和full_endpoint写成注释或者环境变量引用别硬编码。换通道的时候只改一处。第四Dify 侧配置改完后先点测试再保存。很多版本有“测试连接”按钮能当场告诉你通不通比保存后调用再报错效率高。如果你打算把这套 MCP 工具链用在日常编码或 Agent 工作流里模型侧建议固定一个稳定的接入方式。TaoToken 的 Coding Plan 适合长期跑编码类任务入口在https://taotoken.net/coding-plan需要看模型列表和调试对话用https://taotoken.net/modelsAPI Key 管理在https://taotoken.net/api-keys。接入文档在https://taotoken.net/doc里面有各客户端的配置示例。把这些和 MCP 的 endpoint 分开管理出问题的时候能快速定位是哪一侧。最后留一个实用习惯每次改完config.toml先跑一遍第 4 节的三条 curl把输出贴到记事本里存着。下次再报failed to get endpoint URL对比一下哪一步的输出变了问题基本就锁定了。这比从头猜地址快得多。