你已经把 RAGFlow 跑起来了，也想让 Agent 通过 MCP 去调它的检索能力，结果卡在「服务能起、工具列表也出来了，但一调就超时或者返回空」这种地方。这篇不重复协议概念，只给落地顺序：先确认走哪种通道、再把工具暴露成什么粒度、然后按超时并发降级日志评测这几项逐个补上，最后用一条最小链路验证通。
你已经把 RAGFlow 跑起来了，也想让 Agent 通过 MCP 去调它的检索能力，结果卡在「服务能起、工具列表也出来了，但一调就超时或者返回空」这种地方。这篇不重复协议概念，只给落地顺序：先确认走哪种通道、再把工具暴露成什么粒度、然后按超时并发降级日志评测这几项逐个补上，最后用一条最小链路验证通。
整个过程可以理解成给 RAGFlow 装一个「对外接口层」：MCP 负责把能力描述给客户端，真正干活的还是 RAGFlow 的检索。接口层写得糙，模型调起来就是各种莫名其妙的失败，所以下面每一节都给你判断标准和可执行动作，而不是只讲原理。
先定通道：RAGFlow 是被谁调、从哪一侧发起
开工前最容易踩的坑是把方向搞反。先问自己一句话：这次是别人来调 RAGFlow 的检索，还是 RAGFlow 去调别人的工具？两个方向对应完全不同的配置，选错后面全白做，改到一半才发现要返工。
| 拓扑 | 谁做 server | 适用情况 |
|---|---|---|
| RAGFlow 被 Agent 调 | 把 RAGFlow 的知识库能力包成 MCP server | 想让任意客户端复用同一个知识库 |
| RAGFlow 去调外部工具 | RAGFlow 做 MCP client | 让知识库流程里串上外部动作 |
| 两种都要 | 各自独立配置，别混在一个进程里 | 有双向需求的复杂场景 |
通道选本地 stdio 还是远程 HTTP，取决于部署位置：同机同容器用 stdio 省事，跨机器或容器隔离就必须走可寻址的传输，别硬塞。动手前把「谁发起连接、连到哪个地址端口、用什么凭证」这三件事写在一张纸上，再改配置，能省掉大量来回试。
工具怎么暴露：别把整个知识库塞成一个函数
工具拆分的原则是「按动作拆，不要按数据拆」。检索、列数据集、取文档片段这类各占一个工具，比一个叫「问知识库」的万能函数好调试，也好单独控权限。一个函数什么都干，出错时你根本不知道是检索挂了还是参数理解错了。
- 入参只用可枚举的字段：数据集标识、查询串、返回条数上限，别让模型自由发挥造字段
- 返回结构固定成几条片段加来源标识，别把整篇原文直接回灌给模型，上下文会被冲垮
- 给每个工具写一句人能读懂的描述，模型选错工具八成是描述太含糊，不是模型不行
- 工具数量少、只有单一检索动作时，别拆太细，拆多了反而增加选错概率
描述写得好不好，可以用一个笨办法验证：把工具列表给一个不了解项目的人看，问他每个工具该在什么情况下用。他答不上来，模型大概率也答不上来。
超时与并发：把「卡住」变成「快速失败」
很多人直接沿用模型调用的默认超时，结果 RAGFlow 冷启动或者首次加载索引时就被判超时。正确做法是先量出延迟基线，再定阈值。可以到 /tools/speed-test 量你自己的延迟基线，用真实数字定阈值，而不是拍脑袋。
- 量基线用固定几个问题各跑几遍，记录冷启动和热路径的耗时，到 /tools/speed-test 对照你机器上的实际数字
- 设短超时检索调用单独设一个比模型调用更短的超时，让卡住的请求尽快暴露
- 限并发限制同一时刻在跑的检索请求数，超过就排队或直接拒绝，避免把 RAGFlow 打满导致正常问答一起挂
- 分两条分支「检索超时」可以重试一次，「检索无结果」重试没意义，应该让模型直接说没查到
把超时和并发当成两件事分别调，不要一个参数解决所有问题。并发限制太松会拖垮服务，太紧又会让正常请求排队到超时，这个平衡点只能靠你自己的基线数据来找。
日志与评测：出问题时你能复现哪一步
没有日志的接入等于闭着眼睛开车。每次工具调用至少落四个字段：调用时间、工具名、入参摘要、耗时与返回条数。没有这几个字段，排错只能靠猜，改了半天也不知道是不是真的修好了。
| 失败类型 | 典型表现 | 先查什么 |
|---|---|---|
| 连不上 | 连接被拒、握手失败 | 地址端口、server 是否在跑 |
| 鉴权失败 | 401 类似的拒绝 | 凭证、token 是否过期 |
| 超时 | 卡住很久后报错 | 延迟基线、并发限制 |
| 返回空 | 接口成功但没片段 | 查询串、数据集标识、索引状态 |
| 格式不符 | 模型说参数不对 | 工具入参 schema 和描述 |
再准备一小批固定问题当回归用例，改完检索参数或换嵌入模型后跑一遍，对比命中片段是否变化。别靠感觉说「好像变好了」，有对照表才说得清。失败分层归类之后再去找对应文章，比一上来就改代码有效率。
降级顺序：接不上时不至于整条链路停摆
降级要分两层，按顺序退。第一层是减少返回条数或缩小召回范围，先保证有结果返回；第二层才是跳过检索直接让模型裸答，并在输出里明确标注「未使用知识库」。降级开关做成配置项而不是写死在代码里，方便临时切换验证。
- 第一层：缩范围、减条数，先让链路有返回
- 第二层：跳过检索裸答，输出里必须标注未用知识库
- 开关配置化：别写死，方便临时切回和验证对比
- 该报错就别降级：内部资料、合规、对外承诺场景宁可直接报错
最小链路验证：一次跑通再往上加
所有配置做完后，别急着上复杂 Agent，先用一条最小链路验证：单个客户端、单个检索工具、一句固定查询，看能不能拿到带来源标识的片段。这一步过了，再加工具、加并发、加降级逻辑。
# 伪代码示意，具体字段名以你的实现为准；启动 server 后先用客户端列出工具，再调用一次检索工具，检查返回条数与来源字段# list_tools -> call search -> assert len(snippets) > 0验证通过之后，把排查顺序记下来：连不上、鉴权、超时、返回空、格式不符，一层层往下查。这套顺序在后续换模型、换部署环境时同样适用。想对比不同中转方案在你这套链路里的实际表现，可以到 /sites 和 /rankings 看当时的数字，再到 /price-watch 核对价格波动。
下一步先量你自己的延迟基线，再回来定超时和并发；基线数字到 /tools/speed-test 核对，方案对比到 /sites 和 /rankings 看当时的记录。→常见问题
RAGFlow 的 MCP 服务起了，但客户端里看不到工具，先查哪里？
按连接层往前查：先确认进程真的在监听、客户端填的地址和端口对得上，再看启动日志里工具注册有没有报错。多数情况是启动阶段某个依赖没就绪导致工具列表为空，而不是协议本身的问题。把日志级别调高跑一次，比反复改配置快。
检索结果能返回，但模型老是忽略它自己编，是接入的问题吗？
通常不是传输层的问题，而是返回内容的组织方式。检查两点：返回片段是否带了可辨识的来源标识，以及工具描述是否说清了它返回的是什么。如果模型看不到明确来源，它就会倾向用自己的记忆。可以先在工具层把来源和片段绑死再回给模型。
本地开发和线上部署，MCP 配置要注意什么不一样的地方？
主要差在寻址和凭证两件事。本地通常走标准输入输出、不涉及网络暴露；线上要考虑端口、网络可达性、鉴权，以及进程重启后连接怎么恢复。建议把地址、超时、并发上限都抽成环境变量，两边用同一套代码只换配置，避免上线才发现调不通。
