ragflow 开启 mcp，从零开始的完整步骤和常见问题

你在 RAGFlow 里把知识库建好了，也想让 Cursor、Dify 之类的智能体直接查它，结果卡在「MCP 开关在哪、填什么、填完怎么知道通没通」。这篇按顺序走一遍：先确认你的部署形态能不能开 MCP，再讲配置项的填法，最后给一套验证和排错顺序。不讲概念，只讲动作。

你在 RAGFlow 里把知识库建好了，也解析完了，想着让 Cursor、Dify 这类智能体直接来查，结果卡在最前面：MCP 开关到底在哪、几个字段填什么、填完怎么知道通没通。这篇不铺概念，按动手顺序走一遍，先确认你的部署形态能不能开，再讲配置项的填法，最后给一套验证和排错顺序。

先提醒一句：MCP 只是把调用入口换了个协议，底下还是 RAGFlow 自己的检索链路。检索不通、切片不干净，开了 MCP 照样答非所问。所以别一上来就折腾开关，先把知识库本身能正常问答这一步确认掉。

动手前先确认三件事

第一件事是看你的部署形态。完整镜像部署一般带 MCP 相关组件，精简版或者自己裁过的镜像可能没装。不用猜，翻启动日志，看有没有对应服务起起来；日志里压根没这个进程，就先补组件再谈配置。

• 确认知识库已完成解析、能正常问答，底下的检索链路不通，开了 MCP 也白搭
• 想清楚方向：是让 RAGFlow 当 MCP 服务端给别的客户端调，还是把外部 MCP 工具挂进来，这两件事配置项完全不同，别混着填
• 把客户端的类型定下来，不同客户端支持的传输方式不一样，先定客户端再定配置，能少返工

方向这件事最容易被跳过。给外部客户端调用的场景，你要配的是服务地址、鉴权和可见知识库范围；挂外部工具的场景，你要配的是工具来源和参数。方向上错了，后面每个字段都会填得像模像样但就是不通。

配置入口与关键字段怎么填

MCP 开关一般在系统设置里，找到后启用并保存，然后按提示重启对应服务。这一步别省，很多改动不重启就是不生效，保存成功不等于生效。重启完再回来看开关状态，确认没被回滚。

填完别急着去客户端试。把地址、传输方式、鉴权信息原样抄一份记下来，客户端那边要用同一个口径。抄的时候注意区分「给客户端看的地址」和「服务自己监听的地址」，这两个在容器环境里经常不是一回事。

最小验证：三步确认真的通了

验证要分三层做，每层只回答一个问题，混在一起做最容易误判。顺序是：端点通不通、知识库有没有被调到、答得对不对。

1. 测端点连通用客户端自带的工具页面或者命令行直接请求端点，确认服务在监听、返回不是超时也不是 404。这一步只关心通不通，不关心内容。
2. 问一个只有你文档才答得上的问题在客户端里提一个答案只存在于你自己知识库里的问题，答案对不上说明检索没接进来，先别怪模型。
3. 回 RAGFlow 看日志日志为空就是客户端压根没连上，回去查地址和鉴权；日志里有这次调用但答非所问，才是检索、切片或阈值的问题。
4. 顺手量个延迟基线到 /tools/speed-test 测一下这条链路的响应，记下来，以后变慢能对照是不是最近改了什么。

也不一定非要走完三步才算成功。内部小范围试用的话，第一步和第二步过了就能先用起来；但如果是要让多个客户端共用，第三步的日志确认别跳过，不然出了问题是服务端还是客户端说不清。

常见卡点按这个顺序排

排错最忌东改一下西改一下。按下面的顺序走，每个卡点先定位在链路哪一段，再动手改，改完只验证这一段。

• 连不上：先查地址和端口，再看防火墙和容器端口映射，最后才怀疑版本或组件缺失
• 连上但没结果：查知识库有没有绑到这个端点、文档解析是否完成、召回是不是被阈值卡掉
• 鉴权失败：确认 Key 没有多余空格，客户端和服务端没用混两套鉴权头，配置前后一致
• 能答但引用错、答偏：问题在切片和检索环节，回知识库那边调，别在 MCP 层反复改配置

还有一种容易被误判的情况：端点通、日志也有，但回答时好时坏。多半是召回不稳定或者知识库里有重复、过期内容，这种跟 MCP 没关系，去查知识库质量。想先摸清各家客户端和工具的实际情况，可以到 /tools 目录里对照着选，再回来配。

MCP 只是换了个门，门后面的检索和切片没修好，换个门也进不去东西。