RAGFlow MCP 客户端示例 (RAGFlow MCP client examples)

Python 和 curl MCP 客户端代码示例。

MCP Python 客户端示例

我们在此处提供了一个用于测试的 原型 (Prototype) MCP 客户端示例。

重要

如果您的 MCP 服务端正在托管（host）模式下运行，在异步连接到该服务时，请在客户端的 headers 中包含您获取到的 API 密钥：

async with sse_client("http://localhost:9382/sse", headers={"api_key": "YOUR_KEY_HERE"}) as streams:
    # 您的其他代码...

或者，为符合 OAuth 2.1 Section 5 规范，您也可以改用以下代码来连接到您的 MCP 服务端：

async with sse_client("http://localhost:9382/sse", headers={"Authorization": "YOUR_KEY_HERE"}) as streams:
    # 您的其他代码...

使用 curl 与 RAGFlow MCP 服务端进行交互

通过 HTTP 请求与 MCP 服务端进行交互时，请遵循以下初始化顺序：

客户端发送 initialize 请求，包含协议版本和功能（Capabilities）声明。
服务端回复 initialize 响应，包含支持的协议和功能（Capabilities）。
客户端通过 initialized 通知确认就绪。
此时，客户端与服务端之间的连接即告建立，可以进行后续操作（例如列出工具）。

提示

有关此初始化流程的更多信息，请参见此处。

在接下来的章节中，我们将引导您完成一个完整的工具调用（Tool Calling）过程。

1. 获取会话 ID (Session ID)

与 MCP 服务端的每个 curl 请求都必须包含一个会话 ID：

$ curl -N -H "api_key: YOUR_API_KEY" http://127.0.0.1:9382/sse

提示

有关获取 API 密钥的信息，请参阅此处。

传输

传输通道将以流式传输工具执行结果、服务器响应以及心跳检测（Keep-alive pings）等消息。

服务端返回会话 ID：

event: endpoint
data: /messages/?session_id=5c6600ef61b845a788ddf30dceb25c54

2. 发送 `Initialize` 请求

客户端发送 initialize 请求，包含协议版本和功能信息：

session_id="5c6600ef61b845a788ddf30dceb25c54" && \

curl -X POST "http://127.0.0.1:9382/messages/?session_id=$session_id" \
  -H "api_key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "1.0",
      "capabilities": {},
      "clientInfo": {
        "name": "ragflow-mcp-client",
        "version": "0.1"
      }
    }
  }' && \

传输

服务端回复 initialize 响应，包含支持的协议和功能信息：

event: message
data: {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-03-26","capabilities":{"experimental":{"headers":{"host":"127.0.0.1:9382","user-agent":"curl/8.7.1","accept":"*/*","api_key":"ragflow-xxxxxxxxxxxx","accept-encoding":"gzip"}},"tools":{"listChanged":false}},"serverInfo":{"name":"docker-ragflow-cpu-1","version":"1.9.4"}}}

3. 确认就绪

客户端通过 initialized 通知确认就绪：

curl -X POST "http://127.0.0.1:9382/messages/?session_id=$session_id" \
  -H "api_key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "notifications/initialized",
    "params": {}
  }' && \

此时客户端与服务端之间的连接已建立，可以进行后续操作（例如列出工具）。

4. 列出工具 (Tool listing)

curl -X POST "http://127.0.0.1:9382/messages/?session_id=$session_id" \
  -H "api_key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/list",
    "params": {}
  }' && \

传输

event: message
data: {"jsonrpc":"2.0","id":3,"result":{"tools":[{"name":"ragflow_retrieval","description":"Retrieve relevant chunks from the RAGFlow retrieve interface based on the question, using the specified dataset_ids and optionally document_ids. Below is the list of all available datasets, including their descriptions and IDs. If you're unsure which datasets are relevant to the question, simply pass all dataset IDs to the function.","inputSchema":{"type":"object","properties":{"dataset_ids":{"type":"array","items":{"type":"string"}},"document_ids":{"type":"array","items":{"type":"string"}},"question":{"type":"string"}},"required":["dataset_ids","question"]}}]}}

5. 工具调用 (Tool calling)

curl -X POST "http://127.0.0.1:9382/messages/?session_id=$session_id" \
  -H "api_key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "ragflow_retrieval",
      "arguments": {
        "question": "How to install neovim?",
        "dataset_ids": ["DATASET_ID_HERE"],
        "document_ids": []
      }
    }
  }'

传输

event: message
data: {"jsonrpc":"2.0","id":4,"result":{...}}

完整的 curl 示例

session_id="YOUR_SESSION_ID" && \

# 步骤 1：初始化请求
curl -X POST "http://127.0.0.1:9382/messages/?session_id=$session_id" \
  -H "api_key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "1.0",
      "capabilities": {},
      "clientInfo": {
        "name": "ragflow-mcp-client",
        "version": "0.1"
      }
    }
  }' && \

sleep 2 && \

# 步骤 2：就绪通知
curl -X POST "http://127.0.0.1:9382/messages/?session_id=$session_id" \
  -H "api_key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "notifications/initialized",
    "params": {}
  }' && \

sleep 2 && \

# 步骤 3：列出工具
curl -X POST "http://127.0.0.1:9382/messages/?session_id=$session_id" \
  -H "api_key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/list",
    "params": {}
  }' && \

sleep 2 && \

# 步骤 4：工具调用
curl -X POST "http://127.0.0.1:9382/messages/?session_id=$session_id" \
  -H "api_key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "ragflow_retrieval",
      "arguments": {
        "question": "How to install neovim?",
        "dataset_ids": ["DATASET_ID_HERE"],
        "document_ids": []
      }
    }
  }'