你在 RAGFlow 里已经堆好了知识库，问答效果也还行，但每次都得手动去网页里提问，或者自己写一层 HTTP 封装塞进 Agent，改一次接口就要动一次代码。这篇就是把 RAGFlow 封成 MCP 服务、让智能体直接调检索那一步讲清楚：先确认 RAGFlow 侧能对外提供什么，再决定 MCP 用哪种传输方式，最后在客户端把配置写对、用一句测试问句验证通。
你在 RAGFlow 里已经把文档传进去、解析也跑了，网页里问几句答得还行。但每次要么手动去网页提问，要么自己写一层 HTTP 封装塞进 Agent，接口一改就得动代码。用 MCP 接进去之后，智能体可以像调普通工具一样直接发起检索，你不用再维护那层薄封装。
这篇只讲一件事：把 RAGFlow 封成 MCP 服务、在智能体客户端配好、然后验证调通。顺序是先确认 RAGFlow 侧能对外提供什么，再决定 MCP 用哪种传输方式，最后写客户端配置，用一句测试问句验证。调不通的时候也有固定的排查顺序。
接之前先确认 RAGFlow 侧有什么
MCP 服务本身不产生检索能力，它只是把 RAGFlow 已有的接口包装成工具。所以第一步不是写代码，是确认 RAGFlow 那边到底对外暴露了什么。打开接口文档或试一次 curl，能看到返回结果才算通。
- 是否有对外开放的检索接口，以及鉴权方式：API Key 是放在请求头还是查询参数，很多封装脚本在这里写错
- 要暴露哪几个能力：只暴露检索是最小可用集，上传文档、建知识库属于写操作，权限要单独评估
- 知识库 ID 从哪来：多数封装要求把 ID 写进配置，智能体不会自己去猜
- RAGFlow 与 MCP 服务是否同机：跨机器先把网络可达性和端口放行确认掉
MCP 服务这一层怎么写
MCP 服务本质是一个进程，对外暴露若干工具，内部去调 RAGFlow 的接口，把结果整理成模型能读的文本返回。这层不需要复杂，重点是参数描述清楚、返回内容裁剪干净。
- 标准输入输出传输
- 本机或同机部署最省事，客户端直接拉起进程，不用管端口和鉴权
- HTTP 传输
- 跨机器或多人共用时才上，需要自己解决服务常驻和访问控制
- 工具描述
- 写清每个参数的含义和取值范围，描述含糊模型就爱传错参数
- 返回裁剪
- 只回片段正文加来源标识，不要把整篇文档塞回去，否则很快撑爆上下文
| 参数 | 要不要暴露 | 原因 |
|---|---|---|
| 查询语句 | 必须 | 检索的核心输入，缺了就没法用 |
| 返回条数 | 建议 | 控制上下文长度，也给模型一个调节旋钮 |
| 知识库 ID | 视情况 | 单库场景可以写死在配置里，多库场景才做成参数 |
| 上传文档 | 谨慎 | 写操作，需要单独评估权限和误操作风险 |
在智能体客户端把这段配进去
客户端配置分两种：本地进程方式要写清启动命令、参数和工作目录；远程方式写 URL 和鉴权头。命令和脚本位置一律用绝对路径，工作目录没设对是最常见的进程起不来原因。
- 写启动命令绝对路径指向解释器或可执行文件，参数里带上配置文件位置；写完先在终端手动跑一次，能阻塞等待输入才算正常
- 指定工作目录把工作目录设成脚本所在目录，否则脚本里用相对路径读配置会找不到文件
- 看工具列表配完重启客户端，看能否列出这个 MCP 服务提供的工具名；列得出来说明连接通了，列不出来就是启动或传输方式的问题
- 控制调用时机把检索工具设成按需调用，别设成每轮必调，否则无关闲聊也会打一次知识库，又慢又费额度
如果你的客户端支持显示工具调用记录，配完之后主动问一句需要查资料的问题，看它有没有真的去调检索工具。没调说明工具描述或调用条件写得不够明确。
验证与调优：先跑通再谈效果
验证要用一个你在 RAGFlow 网页里问过、确定有答案的问题。这样返回为空时能直接判断是链路问题还是检索问题，随便问一句定位不出来。
- 返回为空先查知识库侧：文档有没有解析入库、切分是否过碎、查询语句和文档用词差多远
- 返回内容太长就调小返回条数或加长度上限，观察是回答变差还是只是少了几句细节
- 把每次调用的查询语句和返回条数记下来，出问题时能分清是模型没调工具，还是调了但召回为空
- RAGFlow 解析状态和分块参数到站内资料库页面对照着看，不同切分策略对召回影响很大
| 现象 | 先查哪里 | 常见原因 |
|---|---|---|
| 客户端列不出工具 | MCP 服务启动 | 命令路径不对、工作目录没设、依赖没装 |
| 工具列出来但调用没反应 | 客户端调用配置 | 工具描述太含糊，模型不知道什么时候该调 |
| 调用了但返回为空 | RAGFlow 侧 | 知识库没解析、查询语句和文档用词差距大 |
| 返回内容被截断 | 返回条数与长度上限 | 条数设太多，单条片段太长 |
常见问题
RAGFlow 的 MCP 服务要自己写吗？
看你要暴露什么。只做检索的话，逻辑很薄：收一个查询、调 RAGFlow 的检索接口、把片段拼成文本返回。如果只是给自己用，直接写一个几十行的进程式 MCP 服务就够了，不用引框架。想要现成的可以到 MCP 服务器大全那页翻一翻有没有对口的实现。
智能体不回知识库内容，怎么判断是哪一环断了？
按顺序看三件事：客户端能不能列出这个 MCP 的工具（不能就是进程或传输问题）；模型有没有发起这次调用（没发起就是工具描述或触发条件的问题）；检索返回是不是空的（空的就是知识库侧的问题）。三步里哪一步断了，修的地方完全不同，别一上来就改提示词。
同一个 RAGFlow 能给多个智能体共用吗？
可以，但建议把 MCP 服务做成独立进程或独立服务，各客户端连同一个地址，而不是每个客户端各自起一份。共用时注意两点：一是知识库 ID 和权限要区分开，别让不该看的人搜到；二是并发上来后 RAGFlow 侧的检索压力会明显变化，具体扛多少要看你这套部署的实际情况，可以先用接口测速量个延迟基线。
