ragflow 开启 mcp，从零开始的完整步骤和常见问题（开之前先确认三件事）

知识库已经跑在 RAGFlow 里，想让 Cursor、Claude Code 或者自建智能体直接检索它，卡点往往不是概念，而是服务端没开、端口没通、鉴权和知识库范围没配对上。这篇按「先确认版本与部署形态，再开服务，最后从客户端验一遍」的顺序讲，每一步都给可核对的检查动作。

知识库已经跑在 RAGFlow 里，想让 Cursor、Claude Code 或者自建智能体直接检索它，卡点往往不是概念，而是服务端没开、端口没通、鉴权和知识库范围没配对上。很多人照着旧教程改配置，改完重启，客户端还是连不上，最后才发现是版本里根本没有这个入口，或者绑定的地址压根到不了。

这篇按「先确认版本与部署形态，再开服务，最后从客户端验一遍」的顺序讲，每一步都给可核对的检查动作。检查不通过就停在那一步排查，别一口气全改完再回头看是哪个环节出的问题。

开之前先确认三件事

第一件是部署形态。Docker Compose 起的和源码起的，改配置的位置、重启的命令都不一样。升级前后的默认配置也可能变，别直接照抄网上旧教程里的文件路径和参数名，先看你自己这套是怎么跑的。

第二件是版本里到底有没有这个能力。去设置页找对应入口，或者翻仓库说明核对。老版本没有入口就是没有，不是藏起来了，硬找也没用，该升级就升级。第三件是先想清楚要暴露哪些知识库、给谁用。

• 确认部署形态：Docker Compose 还是源码，配置文件位置和重启命令先写下来
• 确认版本是否带 MCP 能力：看设置页入口，或去仓库说明核对，没有就升级
• 想清楚暴露范围：哪些知识库、给哪些人或哪些客户端用，先列名单
• 确认网络路径：客户端所在网络能不能到这台机器，中间有没有代理或防火墙

开启服务的操作顺序

在 RAGFlow 管理界面里找到 MCP 相关开关打开，同时设定监听地址与端口。只给内网或本机用就绑本机回环地址，别一上来绑所有网卡。端口挑一个没被占用的，改了记得同步告诉客户端那边。

1. 打开开关并设监听在管理界面启用 MCP，填写监听地址和端口；只本机用就绑回环地址，验证方式是在本机访问该端口能通、外网访问不通。
2. 生成并保存凭据生成访问用的 Token 或密钥，存在密码管理器或团队密钥库里；验证方式是客户端拿这份凭据能通过鉴权，明文别贴进聊天记录。
3. 重启并看日志重启对应容器或进程，回来翻日志找服务开始监听的那行；端口冲突一般会在日志里直接报出来，看到就换端口。
4. 本地先探一下在能访问这台机器的环境里，用 curl 或浏览器访问健康检查或根路径；验证标准是返回正常而不是连接被拒或超时。

curl -v http://127.0.0.1:<端口>/ ；能连上再看返回内容，连接被拒先查进程和端口占用

从客户端验通：先列工具再问问题

客户端这边配服务地址和凭据，传输方式要和 RAGFlow 侧实际开放的一致。命令行工具模式（stdio）和网络接口模式（HTTP）不能混，混了就是握手失败，报错还经常很含糊。

验的顺序很重要：先做「列出工具」这一小步。能看到检索类工具，说明握手成功；看不到就是连接或鉴权问题，别急着测问答。成功之后再发一条最简单的检索请求，问题里带上知识库里确实存在的词。

列工具

客户端能拉到工具清单，说明地址、传输方式、凭据三样都对上了

空结果

连上了但检索不到内容，先怀疑知识库没解析完或范围没勾上

鉴权失败

凭据过期、被截断或放错位置，检查是请求头还是配置文件

传输方式不匹配

stdio 和 HTTP 混用，表现通常是连不上或握手超时

• 配好地址和凭据，传输方式与 RAGFlow 侧保持一致
• 先调列工具，确认能看到检索类工具
• 再发一条带知识库内实词的检索请求
• 答不出内容就回查文档解析状态和知识库范围
• 跑通后把地址、凭据存放位置、可用工具清单记进团队文档

上线前的对照清单

下面这张表按「从网络到数据」的顺序排，哪一行不对就先修那一行，别跳着查。检查顺序和排查顺序一致，能省掉大量来回试的时间。

成本这块容易被忽略：每次问答会触发检索和模型调用，多人共用同一套服务时，调用量会叠起来。具体额度怎么算，到 /price-watch 核对当时的数字，别凭印象估。

什么情况下别急着开

知识库还在大量灌数据、文档解析没稳定的时候，先别开。开了 MCP 也只是一直返回空结果，排查起来反而多一层干扰，先把入库流程弄干净。这台机器直接暴露在公网且没有统一网关鉴权时，也不建议开放，走内网或加一层代理再谈。

还有一种情况：只想给一个人偶尔查资料。那用网页端检索更省事，MCP 更适合要嵌进开发流程或智能体循环的场景，比如让命令行助手在写代码时顺手检索内部文档。场景不对，配半天也是负担。