1. Dify 接 MCP 工具调用为什么总在 401 上翻车

Dify 里配好 MCP 工具、Agent 策略也选了 ReAct，结果一跑工作流就弹 401，这种场景我见过太多次。401 是 HTTP 语义里最直白的一类错误——未授权，它跟 404（地址不对）、500（服务端炸了）不一样，问题几乎一定出在“身份凭证”这条链路上：要么请求根本没带凭证，要么带了但服务端不认，要么凭证是对的但发给了错误的 endpoint。

先把 Dify 调用 MCP 的链路拆开看。Dify 本身不直接执行 MCP 协议，它靠插件（比如 MCP SSE 工具插件）把远端 MCP Server 暴露的 SSE 地址注册进来，Agent 节点在推理时通过这个插件向 MCP Server 发起 HTTP 请求，请求里带上你在插件配置里填的 headers。所以一次工具调用至少经过三层：Dify 工作流 → MCP SSE 插件 → 远端 MCP Server。401 可能发生在任意一层，但绝大多数情况卡在“插件发出的请求头里没有合法凭证”或“凭证对应的 endpoint 不是你以为的那个”。

这里要引入一个关键概念：MCP 工具调用本质上是一次带鉴权的 HTTP 请求。很多同学在本地用 Python 跑 MCP Server 时没加鉴权，http://127.0.0.1:8000/sse直接就能连，于是误以为 MCP 不需要 Key。可一旦把 endpoint 换成需要鉴权的托管服务，请求头里没有Authorization: Bearer xxx，服务端第一件事就是回 401。这就是为什么“本地能跑、Dify 里 401”成了高频现象。

那为什么要把 endpoint 改到 TaoToken？因为 TaoToken 提供统一的模型与工具调用入口，把鉴权、路由、配额这些事收敛到一处，你只需要在 Dify 插件里填一个 Base URL 加一个 Key，不用自己维护一堆分散的 MCP Server 地址。它的 API 入口是https://taotoken.net/api，模型对话、Coding Plan、控制台、API Keys 都有独立页面。对 Dify 这种要频繁调工具的编排场景来说，统一入口能显著减少“这个工具用 A 地址、那个工具用 B 地址”带来的鉴权混乱。

这篇就按排查清单的方式走：先复现 401，再逐层定位是密钥、地址还是工具声明的问题，最后给出可复制的 endpoint 与鉴权配置片段，并用 curl 验证调用成功。适合已经在 Dify 里搭过 Chatflow、装过 MCP SSE 插件、但被 401 卡住的同学。下面每一步都能直接跟着做。

2. TaoToken 前置准备：Key、Base URL 与 MCP endpoint 怎么对齐

在动 Dify 之前，先把 TaoToken 这边的三样东西准备好，不然后面排查会失去基准。第一样是 API Key，去控制台的 API Keys 页面创建，格式通常是一串以特定前缀开头的长字符串。创建后立刻复制保存，很多平台只显示一次。第二样是 Base URL，也就是https://taotoken.net/api，注意这个地址不带任何查询参数，是纯入口。第三样是你要调用的模型或工具的 Model ID，比如某个具体的模型标识，这个 ID 必须和你在 Dify 里声明的完全一致，大小写都不能错。

这里有个容易踩的坑：Base URL 和完整 endpoint 不是一回事。Base URL 是根，实际请求路径是在它后面拼出来的。比如模型对话可能是/api/v1/chat/completions这类路径，而 MCP 的 SSE 地址又是另一套路径。你在 Dify 插件里填的应该是完整的、能直接发起请求的 URL，而不是只填 Base URL。很多人 401 就是因为把 Base URL 当成了完整 endpoint 填进去，请求打到了根路径，服务端自然不认。

为了把三件套对齐，建议先在本地用 curl 验证 Key 本身是有效的。打开终端，执行下面这条命令，把$TAOTOKEN_KEY换成你真实的 Key：

curl -i https://taotoken.net/api/v1/models \ -H "Authorization: Bearer $TAOTOKEN_KEY"

如果返回 200 并且列出模型列表，说明 Key 和 Base URL 这一层是通的。如果这里就返回 401，那问题根本不在 Dify，而是 Key 本身无效、过期，或者复制时带了空格换行。这一步是整个排查的地基，地基不稳后面全是白费。

确认 Key 有效后，再确认你要接入的 MCP 工具在 TaoToken 侧的 endpoint 形态。MCP over SSE 的地址通常以/sse结尾，但具体路径要以文档为准。去接入文档页面查清楚：这个工具的 SSE 地址是https://taotoken.net/api/...还是别的路径。把完整地址记下来，后面 Dify 插件里要一字不差地填进去。

还有一点，Dify 的 MCP SSE 插件配置里支持headers字段，这是放鉴权信息的地方。格式是 JSON，键值对。TaoToken 用的是标准的 Bearer 方案，所以 headers 里应该是：

{ "Authorization": "Bearer 你的Key" }

注意Bearer和 Key 之间有一个空格，这个空格漏了就是 401。我见过至少三次因为漏空格导致的排查，最后发现是复制粘贴时把空格吃掉了。建议配置完后用cat -A或者编辑器显示不可见字符的功能检查一遍。

最后，把 Model ID 也准备好。Dify 的 Agent 节点在调用工具时，有时需要指定模型，这个模型 ID 必须和 TaoToken 侧支持的列表一致。如果你在 Dify 里填了一个 TaoToken 不认识的模型名，可能不会直接 401，但会在工具调用阶段报别的错。为了减少变量，先把模型 ID 也核对一遍。三件套齐了，再进 Dify 配置。

3. 可复制配置：Dify MCP SSE 插件与 Agent 节点的完整片段

这一节给可直接复制的配置。先装插件：在 Dify 插件市场搜 MCP SSE，需要两个——一个是 Agent 策略集合（支持 MCP SSE 发现和调用工具），一个是 MCP SSE 工具插件。装完后在工具列表里能看到“通过 SSE 发现和调用 MCP 工具”。

点开 MCP SSE 插件，添加 SSE 地址。这里填的 JSON 就是鉴权配置的核心。把下面这段复制进去，替换你的Key和实际的 SSE 路径：

{ "taotoken_mcp": { "url": "https://taotoken.net/api/mcp/sse", "headers": { "Authorization": "Bearer 你的Key" }, "timeout": 60, "sse_read_timeout": 300 } }

几个字段说明：url是完整 SSE 地址，必须以https://开头；headers里放鉴权，键名是Authorization，值是Bearer加 Key；timeout是连接超时秒数；sse_read_timeout是读取超时，MCP 工具调用可能耗时较长，设大一点避免中途断开。如果你有多个 MCP 服务，就在这个 JSON 里加多个键，每个键对应一个服务配置。

保存后，进工作流。创建一个 Chatflow，删掉默认 LLM 节点，加一个 Agent 节点。Agent 策略必须选ReAct (Support MCP Tools)。为什么不用 Function Calling？实测下来 Function Calling 在调 MCP 工具时经常报找不到call_tool方法，尤其是用 fastmcp 框架开发的服务，即使补了call_tool也还是报错。ReAct 稳定得多，直接选它。

工具列表这里必须手动添加，点右侧加号，选“通过 SSE 发现和调用 MCP 工具”，把刚才配的taotoken_mcp加进来。MCP 服务器字段再贴一次同样的 JSON，确保和插件里一致。指令（提示词）也要写，告诉 Agent 什么时候用这个工具。比如：

使用中文回复。 当用户提问涉及数据查询、模型调用等需要外部工具的场景时， 使用 taotoken_mcp 工具完成。

查询变量填query，最大迭代次数设 3 或更高，否则保存不了。最后把 Agent 的输出连到直接回复节点，变量选Agent.text。发布预览。

这里有个细节：Dify 的 Agent 节点在发起工具调用时，会把插件里配的 headers 原样带上。所以只要插件里的Authorization是对的，请求就能通过鉴权。如果插件里没配 headers，或者配错了，Agent 发出的请求就是裸的，服务端直接 401。这就是为什么“插件配置”和“Agent 工具列表”两处都要核对——它们共享同一份鉴权信息，任何一处不一致都会出问题。

配置完成后，建议先在 Dify 里点一次“测试”或跑一个最简单的 query，观察日志。如果还是 401，别急着改 Dify，先用下一节的 curl 复现，把问题锁定在 HTTP 层。

4. 验证请求：用 curl 复现 401 再验证调用成功

排查 401 最有效的方法是把 Dify 这一层剥掉，直接用 curl 打 MCP endpoint。这样能明确区分是“凭证问题”还是“Dify 配置问题”。

先复现 401。故意不带 Authorization 头，请求 SSE 地址：

curl -i -N https://taotoken.net/api/mcp/sse

-N是关闭缓冲，方便看 SSE 流。预期返回：

HTTP/1.1 401 Unauthorized Content-Type: application/json {"error":"missing or invalid authorization header"}

看到 401 就对了，说明服务端确实在鉴权，且你的请求没带凭证。这一步确认了“401 的来源是缺凭证”，而不是地址写错（地址错会是 404）。

接着带上正确的 Key 再打一次：

curl -i -N https://taotoken.net/api/mcp/sse \ -H "Authorization: Bearer $TAOTOKEN_KEY"

如果返回 200 并且开始输出 SSE 事件流（类似event: endpoint或data: {...}），说明鉴权通过，endpoint 正确。这时候问题就锁定在 Dify 侧了——要么插件里 headers 没配对，要么 Agent 节点没引用到正确的工具。

再进一步，模拟一次完整的 MCP 工具调用。MCP over SSE 的调用流程是先建立 SSE 连接拿到消息端点，再 POST 请求过去。用 curl 可以分两步：

# 第一步：建立 SSE 连接，观察返回的 endpoint 事件 curl -N https://taotoken.net/api/mcp/sse \ -H "Authorization: Bearer $TAOTOKEN_KEY" \ -H "Accept: text/event-stream"

在返回的流里会看到一个endpoint事件，里面包含一个用于发送消息的 URL。拿到这个 URL 后，第二步 POST 一个 JSON-RPC 请求：

curl -i -X POST "上一步拿到的endpoint URL" \ -H "Authorization: Bearer $TAOTOKEN_KEY" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {} }'

如果返回 200 并且 body 里列出了工具清单，说明整条链路通了。tools/list是 MCP 协议里列工具的标准方法，能列出来就证明鉴权、地址、协议版本都对。

把 curl 验证通过的这套配置，原样搬到 Dify 插件里。注意 curl 里的Authorization头，在 Dify 插件 JSON 里就是headers.Authorization，值完全一样。如果 curl 通了但 Dify 还 401，那问题一定在 Dify 的配置细节：比如 JSON 格式错了、Key 里混入了空格、或者 Agent 节点引用的工具不是这个插件。

实测下来，90% 的 Dify MCP 401 都能用这套 curl 流程定位。先复现 401，再带 Key 验证，最后模拟工具调用，三步走完，问题在哪一层一目了然。

5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth

这一节把高频报错逐个对照。先看最典型的 401：

HTTP 401 Unauthorized {"error":"invalid api key"}

原因通常是三种：Key 复制时带了首尾空格或换行；Bearer和 Key 之间漏了空格；Key 已过期或被删除。排查动作：用echo -n "$TAOTOKEN_KEY" | wc -c看长度是否符合预期，用cat -A看有没有隐藏字符。然后在 Dify 插件 JSON 里重新粘贴一次，确保"Authorization": "Bearer xxx"格式正确。

第二种，local proxy failed或类似的连接失败：

local proxy failed: dial tcp 127.0.0.1:8000: connect: connection refused

这个报错说明 Dify 试图连一个本地地址，但本地没有服务在跑。常见于你把 SSE 地址填成了http://127.0.0.1:8000/sse，而 Dify 部署在容器或远程服务器上，它访问不到你本机的 127.0.0.1。解决方法是把 endpoint 换成 TaoToken 的公网地址https://taotoken.net/api/...，让 Dify 能直接访问。这也是把 endpoint 改到 TaoToken 的核心收益之一——不用再操心本地服务暴露和网络可达性。

第三种，reading choices相关报错：

error reading choices: unexpected end of JSON input

这个通常不是鉴权问题，而是返回体不是预期的 JSON 结构。可能原因：endpoint 填成了模型对话地址而不是 MCP SSE 地址，导致返回格式不匹配；或者 SSE 流被中途截断。排查动作：用 curl 直接打这个地址，看返回的 Content-Type 是text/event-stream还是application/json。MCP SSE 必须是前者。如果返回的是 JSON，说明地址填错了，去文档里核对正确的 SSE 路径。

第四种，OAuth 相关报错：

OAuth token exchange failed

如果你用的是需要 OAuth 的 MCP 服务，而 Dify 插件只配了静态 Bearer，就会出这个。TaoToken 的 API Key 方案是静态 Bearer，不需要 OAuth 流程，所以只要用 Key 就不会碰到这个错。如果你确实需要 OAuth，得在插件里走对应的授权流程，但大多数 Dify + MCP 场景用静态 Key 就够了。

再补一个容易忽略的：工具声明环节出错。表现是鉴权通过了（curl 能列工具），但 Dify Agent 调用时报“找不到工具”或“tool not found”。这通常是 Agent 节点的工具列表没添加，或者指令里没告诉 Agent 用哪个工具。回到 Agent 配置，确认工具列表里勾选了taotoken_mcp，指令里明确提到了工具名。ReAct 策略下，Agent 靠指令来决定调哪个工具，指令写得太模糊它就不调。

对照表总结一下：

把这张表存下来，下次报错直接对号入座。

6. 把 endpoint 收敛到 TaoToken 后的长期用法

排查完 401，更重要的是让这套配置长期稳定。把 endpoint 统一到 TaoToken 之后，你只需要维护一份 Key 和一份 Base URL，Dify 里所有 MCP 工具、模型调用都走同一个入口。这带来的直接好处是：换 Key 时只改一处，加新工具时不用重新配鉴权，配额和用量也在一个控制台里看。

如果你后续要在 Dify 里做更复杂的 Agent 编排，比如多个工具串联、长流程任务，建议把 Coding Plan 也用上。它适合长期编码和 Agent 场景，能减少频繁调用时的额度管理麻烦。模型对话页面可以用来单独验证某个模型是否可用，接入文档页面则放着完整的 endpoint 路径和参数说明，配之前先翻一遍能省很多试错。

日常维护上，养成两个习惯。第一，任何 endpoint 变更后，先用 curl 打一次tools/list，确认鉴权通过再回 Dify 改配置。第二，Dify 插件里的 JSON 和 Agent 节点里的 MCP 服务器 JSON 保持一致，改一处就两处都改。这两条做到，401 基本不会再找上门。

最后留一个实用技巧：在 Dify 工作流里加一个“代码”节点，在调用 MCP 工具前先打印一下当前配置的 endpoint 和 headers 是否存在（不要打印 Key 明文），这样出问题时能快速确认配置有没有被正确加载。这个节点在调试阶段特别有用，上线前删掉即可。