你在 RAGFlow 里把知识库调通了，现在想让 Agent 通过 MCP 直接调用它，结果卡在「服务起没起」「Agent 连不上」「一调就超时」这些地方。这篇不重复 RAG 和 MCP 的概念，只讲落地环节：怎么确认服务真的对外可用、超时和并发怎么给、检索失败怎么降级、日志和评测怎么留痕，让你一步步把链路跑顺。
你在 RAGFlow 里把知识库调通了，问答也测过没问题，现在想让 Agent 通过 MCP 直接调用它，结果卡在几个很具体的地方：服务到底起没起、Agent 连不上、一调就超时、检索不到东西时整条链路跟着卡死。这篇不重复 RAG 和 MCP 是什么，只讲落地环节怎么做。
下面按「先确认能用、再调参数、再考虑挂掉怎么办、最后留痕复盘」的顺序走。每一步都给出可执行动作和判断标准，你照着排查基本能把链路跑顺。涉及具体耗时、并发上限这类数字，以你环境实测为准，站内也有对应页面可以对照。
先确认三件事：服务真的起来了、能被谁访问、工具暴露了什么
很多人一上来就改 Agent 的配置，其实问题多半在前一层。RAGFlow 侧先回到它自己的问答或检索入口，确认这个知识库单跑能答出来；如果它在自己页面里都答不准，接进 MCP 只会把问题放大。这一步不做，后面所有排查都是白费。
| 检查项 | 怎么验证 | 不通过的典型表现 |
|---|---|---|
| RAGFlow 知识库 | 在站内问答或检索入口用同一句话提问 | 答非所问或返回空，说明解析/索引没完成 |
| MCP 服务进程 | 看进程是否存活、有无报错退出 | Agent 报连接被拒绝或超时 |
| 传输与地址 | 确认本地进程还是网络端口，地址端口对得上 | 配置写的是本机地址，Agent 跑在另一台机器上 |
| 工具清单 | 手工调一次，拿到真实响应 | Agent 说工具不存在或参数校验失败 |
| 返回结构 | 记下返回的字段名和层级 | 代码里按错字段名取值，拿到 undefined |
传输方式先定死：本地同机跑就用进程方式，跨机器或容器就老老实实走网络端口，别混着配。地址和端口这两个值两端必须逐字一致，端口被防火墙挡了是查不出报错的，只能从 Agent 那侧看到连接失败。
- 先用最简单的一句话手工调一次检索工具，拿到一份真实响应样本再往下走
- 把这份样本原样存下来，后面写代码、写日志字段都照它来
- 确认工具参数里哪些必填、哪些有默认值，必填项缺了会直接报错
- 返回结构先看最外层是数组还是对象，取值路径别猜，照样本抄
超时和并发按最慢的一环给，不要照抄默认值
超时最常见的错法是只覆盖了检索这一段，模型生成那一段没算进去，结果 Agent 等不到结果就判失败。正确做法是先把耗时拆开量：检索多久、模型生成多久，超时值要大于两者之和，再留一点余量给网络往返。站内有测速页可以帮你把这两段分开看，到 /tools/speed-test 核对当时的数字。
并发要往下游看。Agent 一次可能并发发出多个检索请求，RAGFlow 侧承受的是你的并发数乘上每次检索的切片量，不是简单的请求数。超了下游要么排队要么直接报错，表现出来就是「单问没事、连着问就挂」。
- 量基线把检索耗时和生成耗时分开测，各测若干次取一个稳定区间，别用最好的一次当基准
- 定超时超时设为两段耗时之和再加余量；只覆盖检索会误判，只覆盖生成会漏掉检索卡住的情况
- 压并发逐步提高并发直到出现排队或报错，把配置停在这个点往下留一档
- 分开排查单请求不通先查网络和地址；单请求通、多请求挂查并发和限流；都通但偶尔慢查是否单个大文档拖慢了整批检索
检索失败不能把 Agent 一起拖死
检索工具挂了或者超时，如果直接抛异常给 Agent，模型很容易陷入反复重试，把时间和额度都烧在这里。更稳的做法是给工具设一个「返回上限」：超时后返回空结果加一句简短说明，让模型改成先向用户确认或换关键词，而不是自己无限重试。
| 失败类型 | 能不能重试 | 建议处理 |
|---|---|---|
| 网络抖动、网关超时 | 可以 | 退避后重试有限次数，仍失败则降级返回 |
| 参数错误、参数缺失 | 不可以 | 直接返回错误说明，重试没有意义 |
| 鉴权失败、权限不足 | 不可以 | 返回明确原因，交给配置侧修 |
| 检索命中为空 | 看情况 | 换关键词或让模型先问用户，别原地重试 |
| 下游限流 | 可以 | 等待后重试，同时下调并发 |
另外给 Agent 设步数上限：连续几次检索无结果就停下来，把结果如实告诉用户。这条对成本和安全都重要，尤其是检索工具在循环里被反复调用的时候。
日志与评测：让「这次为什么没答对」能复盘
链路跑通之后，真正难的是「昨天还能答、今天不行了」这种问题。日志不记全，就只能靠猜。每次检索调用至少要把下面这些字段落下来，而且字段名后面别随便改，不然评测脚本对不上。
- 请求时间，用来和其他环节的时间线对齐
- 查询语句原始文本，别记录模型改写过后的版本
- 命中切片数，为 0 通常说明检索这步就没成功
- 检索耗时与模型耗时分开记，一眼看出卡在哪段
- 是否走了降级返回，以及降级原因
- 工具调用是否重试过、重试了几次
再准备一组固定的评测用例，刻意覆盖三类：答案确实在库里、库里根本没有、问题本身太模糊。每次改完配置就跑同一批问题对比，看的是「有没有变差」，不是单次分数好看。这类对照数据站内有页面会追踪当时的口径，到 /rankings 核对当时的数字，别拿旧结果和新配置混着比。
上线前值得做一次对照：同一批问题，一次直接问模型、一次走 MCP 检索，把两类答案摆在一起看。如果走检索反而更容易出错，说明检索这一跳没带来价值，先从知识库质量和检索参数上找原因，而不是怀疑 MCP 本身。
检索不是加一跳就更聪明，能答对才算数——上线前用同一批问题把「有检索」和「没检索」摆在一起比一次。下一步把你手里的模型和检索耗时拿去站内价格与测速页面核对一遍，再决定超时和并发怎么配，别照抄默认值。→
常见问题
服务起来了，但 Agent 一直说连不上，先查哪？
按顺序排：先确认 MCP 进程是否还在、有没有启动报错；再看传输方式和地址端口是否和 Agent 配置里写的一致；最后确认两边的网络是否互通，本地进程方式重点看命令路径和权限，网络方式重点看防火墙和监听地址是不是只绑了本机。
一次检索要等好几秒，是 RAGFlow 慢还是 MCP 慢？
拆开量就行。在 MCP 工具里单独打一次日志，把请求发出到 RAGFlow 返回的时间记下来，再对比 MCP 自身处理耗时，差值基本能定位瓶颈在哪一段。检索本身慢通常是切片粒度或召回条数的问题，不是 MCP 层的问题。
Agent 调用检索工具时参数老报错，怎么快速定位？
先拿工具描述里的参数结构和模型实际传的参数对比，常见就三种：类型不符、多包了一层对象、必填字段缺失。把工具描述改得更死板一些，字段名和类型写清楚，再让模型重跑一次看是否复现。
