ragflow 的 mcp 工具怎么接

你手上已经有一份 RAGFlow 知识库，也想让智能体在对话里直接查它，但卡在「MCP 工具怎么写、检索结果怎么塞回模型、调不通怎么查」这几步。这篇不重复讲协议和原理，只给一条可执行的接入路径：先确认 RAGFlow 侧的调用入口能用，再把它包成一个描述清楚的工具，最后补上超时、降级、日志和评测，让这条链路在真实流量下不飘。

你手上有一份 RAGFlow 知识库，也想让智能体在对话里直接查它，但真正动手时容易卡在三件事上：工具怎么描述模型才肯调、检索回来的长文怎么塞回上下文、调不通的时候从哪儿查起。这篇不讲协议原理，只给一条能落地的接入路径。

整体顺序是反着来的：先把 RAGFlow 侧的调用入口跑通，再把检索包成一个模型看得懂的工具，最后补超时、降级、日志和一组小评测。少任何一环，都会在真实流量下露馅。

先让 RAGFlow 那边能被稳定调用

别急着写工具层。先在 RAGFlow 界面里用你熟悉的几条问题跑一遍，确认召回的内容确实是你想要的那几段。检索质量本身就不行的库，包成工具只会把问题藏得更深。

1. 界面里先验收知识库拿几条业务上真实会问的问题去问，看命中的文档和片段对不对。命中率明显不对就先调切分和召回参数，别往下走。
2. 拿到三样东西知识库标识、调用凭证、请求地址。具体字段名和调用路径到 /stacks/agent-apis 对照当时的官方口径，不要凭记忆写，字段名差一个字母就是 401 或者空结果。
3. 用最小请求打通一次写一段十几行的脚本或者一条 curl，只要能把一条查询打过去、拿到返回就行。把返回的 JSON 原样存成一个文件，后面写字段映射全靠它。
4. 给返回结果瘦身检索原文通常带大量元数据、整段长文本、重复片段。工具返回给模型前先截断单条长度、去掉重复、限制总条数，否则一次调用就把上下文吃干净了。

把检索包成一个模型能看懂的工具

工具描述就是提示词。模型是靠描述判断「这轮要不要调、调哪个」的，写「查询知识库」等于没写。要写清它管哪类资料、什么情况下该用、参数是什么意思。

• 参数设计要窄：一个必填的查询语句，加可选的知识库标识或条数上限就够了，能省就省
• 返回里带上出处：文档名加片段编号，模型可以在回答里标来源，你事后也能核对
• 空结果要显式：检索没命中就返回「未命中相关资料」，不要给空字符串，否则模型容易顺着上下文编
• 工具描述里点明不适用场景：比如跨库汇总、实时数据查询这类它做不到的事，写清楚反而减少误调

超时、降级和日志这三件事必须提前埋

本地调通不代表线上能用。检索是外部依赖，慢和挂都是常态，所以这三件事要在写工具的时候就放进代码，而不是等出事故再补。

• 超时按两档设：单次检索给一个不算长的上限，整轮对话再给一个总预算，防止工具反复重试把会话拖死
• 降级路径先定一条：检索失败是回退到关键词搜索，还是让模型直答并声明未查到资料，二选一写死在代码里
• 日志至少四列：查询语句、命中条数、耗时、是否降级。有这四列，慢和错才分得开
• 给同轮工具调用设步数上限：同一个检索工具被反复调用，通常是描述含糊或者库没命中，要能中断

日志字段怎么设计、监控看哪些维度，可以参考 /tools/quality-monitor 里的监控思路，按你自己的链路裁剪，不用照搬。

排查顺序

# 出问题时按这个顺序看，别一上来就改工具描述
# 1. 用同样的查询直接打 RAGFlow 接口，看有没有返回
# 2. 有返回但模型没调工具 -> 看工具描述和参数名
# 3. 调了但答案没变好 -> 看返回给模型的内容是不是被截没了
# 4. 偶发失败 -> 看日志里的耗时列和降级列

上线前跑一遍小评测，别靠感觉

不需要一开始就搭复杂评测流水线。准备一组固定问题，覆盖三种情况：能命中的、只能部分命中的、完全查不到的。改一次工具描述就重跑一遍，对比两次结果。

该调有没有调

该查资料的问题模型有没有触发检索工具，没触发就是描述不够明确

调了有没有更好

跟不让它调工具时的回答比，事实性明显提升还是只是变长了

描述版本管理

把工具描述当提示词管理，改一版记一版，出问题能回退到上一个能用的版本

也要想清楚不适用的场景。如果知识库更新极频繁、或者用户的问题本身不需要查资料，硬套检索工具只会增加延迟和成本，这种情况让模型直答更合适；接口价格和调用成本的变化，可以去 /price-watch 看当时的数字再决定要不要压调用次数。

工具描述写不清，模型不是不调，而是乱调；日志不记全，你不是修不好，是不知道从哪修。