mirror of
https://github.com/infiniflow/ragflow.git
synced 2026-11-11 13:51:01 +08:00
docs: update MCP documents (#19730)
Adds an overview of RAGFlow MCP features. Adds guides for using RAGFlow as an MCP server and connecting external MCP servers. Improves navigation between related MCP documents.
This commit is contained in:
YanZhang authored and 
GitHub committed
1 parent
0b7dd3720a
commit
b2c2afa5e1
6 files changed
+387
-3
No files matched your search
@@ -0,0 +1,159 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
title: Connect an External MCP Server to RAGFlow
|
||||
sidebar_label: Connect an External MCP Server to RAGFlow
|
||||
slug: /connect_external_mcp_server
|
||||
sidebar_custom_props:
|
||||
categoryIcon: LucideBookOpen
|
||||
---
|
||||
|
||||
# Connect an External MCP Server to RAGFlow
|
||||
|
||||
Connect an external MCP server to RAGFlow to make its tools available to RAGFlow Agents.
|
||||
|
||||
RAGFlow supports MCP servers using **Streamable HTTP** or **SSE**. After an MCP server is added successfully, RAGFlow discovers the tools exposed by the server and makes them available for Agent workflows.
|
||||
|
||||
## Prepare the MCP server
|
||||
|
||||
Before adding an MCP server to RAGFlow, make sure that the server is running and identify the transport it provides.
|
||||
|
||||
RAGFlow supports the following MCP server types:
|
||||
|
||||
* **Streamable HTTP**, for example:
|
||||
|
||||
```text
|
||||
https://example.com/mcp
|
||||
```
|
||||
|
||||
* **SSE**, for example:
|
||||
|
||||
```text
|
||||
https://example.com/sse
|
||||
```
|
||||
|
||||
Streamable HTTP is recommended when supported by the MCP server. SSE is retained for compatibility with MCP servers that use the older transport.
|
||||
|
||||
RAGFlow does not directly connect to MCP servers that use `stdio`. To use a `stdio`-based MCP server, expose it through a gateway or another service that provides an SSE or Streamable HTTP endpoint.
|
||||
|
||||
## Add an MCP server to RAGFlow
|
||||
|
||||
1. Log in to RAGFlow.
|
||||
2. Click your profile picture in the upper-right corner and open **User settings**.
|
||||
3. Open **MCP**.
|
||||
4. Click **Add MCP**.
|
||||
5. Configure the MCP server.
|
||||
|
||||
| Field | Description | Example |
|
||||
| ----------- | -------------------------------------------------------- | --------------------------- |
|
||||
| Name | A custom name used to identify the MCP server in RAGFlow | `Local file tools` |
|
||||
| URL | The complete MCP endpoint | `https://example.com/mcp` |
|
||||
| Server type | The transport provided by the MCP server | `streamable-http` |
|
||||
| Description | Optional description of the MCP server | `Read and manage files` |
|
||||
| Headers | HTTP headers required by the MCP server | `Authorization: Bearer xxx` |
|
||||
| Variables | Variables required by the MCP server configuration | Depends on the MCP server |
|
||||
|
||||
The **Server type** must match the transport exposed by the MCP server:
|
||||
|
||||
```text
|
||||
streamable-http
|
||||
```
|
||||
|
||||
or:
|
||||
|
||||
```text
|
||||
sse
|
||||
```
|
||||
|
||||
If the MCP server does not require authentication, leave **Headers** empty.
|
||||
|
||||
Make sure that the path in **URL** matches the endpoint actually exposed by the MCP server. For example, a Streamable HTTP server commonly uses `/mcp`, while an SSE server commonly uses `/sse`.
|
||||
|
||||
## MCP server URL access restrictions
|
||||
|
||||
RAGFlow validates MCP server URLs before establishing a connection to protect the RAGFlow backend against server-side request forgery (SSRF) and internal network probing.
|
||||
|
||||
### Supported URL schemes
|
||||
|
||||
MCP server URLs must use one of the following schemes:
|
||||
|
||||
```text
|
||||
http://
|
||||
https://
|
||||
```
|
||||
|
||||
The URL must contain a valid hostname or IP address.
|
||||
|
||||
Other URL schemes, including `stdio://`, are not supported for MCP server connections.
|
||||
|
||||
### Public address validation
|
||||
|
||||
By default, RAGFlow allows an MCP server URL only when **all IP addresses resolved from its hostname are publicly routable addresses**.
|
||||
|
||||
With the default configuration:
|
||||
|
||||
```text
|
||||
ALLOW_ANY_HOST=0
|
||||
```
|
||||
|
||||
RAGFlow rejects URLs that resolve to loopback, private, link-local, reserved, or other non-public addresses.
|
||||
|
||||
Examples of addresses that are rejected by default include:
|
||||
|
||||
```text
|
||||
127.0.0.1
|
||||
::1
|
||||
10.x.x.x
|
||||
172.16.x.x - 172.31.x.x
|
||||
192.168.x.x
|
||||
```
|
||||
|
||||
This also affects hostnames. Even if the URL uses a public domain name, RAGFlow rejects the connection if that domain resolves to a non-public IP address in the environment where the RAGFlow backend is running.
|
||||
|
||||
For example:
|
||||
|
||||
```text
|
||||
https://mcp.example.com/mcp
|
||||
```
|
||||
|
||||
can still be rejected if `mcp.example.com` resolves to a private, loopback, or synthetic address.
|
||||
|
||||
### Fake-IP DNS results
|
||||
|
||||
Proxy applications such as Mihomo or Clash may use Fake-IP mode and return synthetic addresses for public domains.
|
||||
|
||||
For example, a public domain may resolve to an address in a range such as:
|
||||
|
||||
```text
|
||||
fdfe:dcba:9876::/48
|
||||
```
|
||||
|
||||
RAGFlow identifies such addresses as non-public and may display an error similar to:
|
||||
|
||||
```text
|
||||
URL resolves to a non-public address (...), which is not allowed.
|
||||
```
|
||||
|
||||
If you see this error, check DNS resolution from the environment where the RAGFlow backend is running.
|
||||
|
||||
The error does not necessarily indicate that the MCP server URL, transport type, or authentication configuration is incorrect.
|
||||
|
||||
## Connect to a local or private MCP server
|
||||
|
||||
For trusted local development or testing environments, you can allow RAGFlow to connect to MCP servers running on localhost, a private network, or a Docker network.
|
||||
|
||||
In `docker/.env`, set:
|
||||
|
||||
```text
|
||||
ALLOW_ANY_HOST=1
|
||||
```
|
||||
|
||||
Then fully restart the RAGFlow backend services so that the new environment setting takes effect.
|
||||
|
||||
For example:
|
||||
|
||||
```bash
|
||||
docker compose down
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
When `ALLOW_ANY_HOST=1`, RAGFlow skips the public-address validation described above.
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
sidebar_position: 11
|
||||
title: Launch RAGFlow MCP Server
|
||||
sidebar_label: Launch RAGFlow MCP Server
|
||||
slug: /launch_mcp_server
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
sidebar_position: 13
|
||||
title: RAGFlow MCP Client Examples
|
||||
sidebar_label: RAGFlow MCP Client Examples
|
||||
slug: /mcp_client
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
sidebar_position: 12
|
||||
title: RAGFlow MCP Tools
|
||||
sidebar_label: RAGFlow MCP Tools
|
||||
slug: /mcp_tools
|
||||
|
||||
@@ -0,0 +1,76 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
title: MCP Overview
|
||||
sidebar_label: Overview
|
||||
slug: /mcp_overview
|
||||
sidebar_custom_props:
|
||||
categoryIcon: LucideBookOpen
|
||||
---
|
||||
|
||||
# MCP Overview
|
||||
|
||||
## What is MCP?
|
||||
|
||||
Model Context Protocol (MCP) is an open protocol for connecting AI applications with external tools, data sources, and services.
|
||||
|
||||
Through MCP, an MCP client can discover and invoke tools provided by an MCP server. RAGFlow can either act as an MCP server to expose its capabilities to external clients or connect to external MCP servers to extend the tools available to RAGFlow Agents.
|
||||
|
||||
## MCP usage scenarios in RAGFlow
|
||||
|
||||
RAGFlow currently supports the following two MCP usage scenarios.
|
||||
|
||||
### Use RAGFlow as an MCP server
|
||||
|
||||
RAGFlow can act as an MCP server and expose capabilities such as knowledge base retrieval to external MCP clients.
|
||||
|
||||
The RAGFlow MCP server runs as a standalone component alongside a properly functioning RAGFlow server.
|
||||
|
||||
The MCP server supports two launch modes:
|
||||
|
||||
* **Self-host mode**: Provide a RAGFlow API key when starting the MCP server. The MCP server uses this API key to access RAGFlow resources available to the corresponding user.
|
||||
* **Host mode**: The MCP server is not bound to a fixed user. Each MCP client provides its own authentication information in requests and can access only the RAGFlow resources available to that user.
|
||||
|
||||
The RAGFlow MCP server supports the following transports:
|
||||
|
||||
* **Streamable HTTP**: Communicates through the `/mcp` endpoint.
|
||||
* **SSE**: Communicates through the `/sse` and `/messages/` endpoints and is retained for compatibility with legacy MCP clients.
|
||||
|
||||
A typical request flow is:
|
||||
|
||||
```text
|
||||
External MCP Client
|
||||
↓
|
||||
RAGFlow MCP Server
|
||||
↓
|
||||
RAGFlow Server
|
||||
↓
|
||||
RAGFlow capabilities
|
||||
```
|
||||
|
||||
For information about starting and configuring the RAGFlow MCP server, see **Launch RAGFlow MCP Server**.
|
||||
|
||||
For details about the MCP tools exposed by RAGFlow and their parameters, see **RAGFlow MCP Tools**.
|
||||
|
||||
For examples of calling the RAGFlow MCP server with Python or curl, see **RAGFlow MCP Client Examples**.
|
||||
|
||||
### Connect an external MCP server to RAGFlow
|
||||
|
||||
RAGFlow can also connect to third-party or self-hosted MCP servers and discover the MCP tools they provide.
|
||||
|
||||
Once configured, these tools can be used by RAGFlow Agents, allowing agents to interact with external systems and services.
|
||||
|
||||
A typical request flow is:
|
||||
|
||||
```text
|
||||
External MCP Server
|
||||
↓
|
||||
RAGFlow
|
||||
↓
|
||||
Agent
|
||||
```
|
||||
|
||||
For information about configuring, testing, and using external MCP servers, see **Connect an External MCP Server to RAGFlow**.
|
||||
|
||||
## Choose the right MCP scenario
|
||||
|
||||
Choose an MCP usage scenario based on what y
|
||||
@@ -0,0 +1,149 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
title: Use RAGFlow as an MCP Server
|
||||
sidebar_label: Use RAGFlow as an MCP Server
|
||||
slug: /use_ragflow_as_mcp_server
|
||||
sidebar_custom_props:
|
||||
categoryIcon: LucideBookOpen
|
||||
---
|
||||
|
||||
# Use RAGFlow as an MCP Server
|
||||
|
||||
RAGFlow can act as an MCP server and expose its capabilities to external MCP clients.
|
||||
|
||||
The Python-based RAGFlow MCP server runs as a standalone component alongside RAGFlow. It communicates with the RAGFlow server through the RAGFlow API and exposes RAGFlow capabilities through the Model Context Protocol (MCP).
|
||||
|
||||
To start and configure the server, see [Launch RAGFlow MCP Server](./launch_mcp_server.md).
|
||||
|
||||
For details about the MCP tools exposed by RAGFlow, see [RAGFlow MCP Tools](./mcp_tools.md).
|
||||
|
||||
For examples of calling the RAGFlow MCP server from an MCP client, see [RAGFlow MCP Client Examples](./mcp_client_example.md).
|
||||
|
||||
## How it works
|
||||
|
||||
The Python MCP server runs independently from the RAGFlow server.
|
||||
|
||||
A typical request flow is:
|
||||
|
||||
```text
|
||||
External MCP Client
|
||||
↓
|
||||
RAGFlow MCP Server
|
||||
↓
|
||||
RAGFlow API
|
||||
↓
|
||||
RAGFlow capabilities
|
||||
```
|
||||
|
||||
The MCP server receives requests from external MCP clients and forwards the corresponding operations to RAGFlow through its API.
|
||||
|
||||
By default, the MCP server listens on port `9382`.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before starting the RAGFlow MCP server, ensure that:
|
||||
|
||||
* RAGFlow is deployed and running normally.
|
||||
* The RAGFlow API is accessible from the MCP server.
|
||||
* A valid RAGFlow user has been created.
|
||||
* A RAGFlow API key is available if you use Self-host mode.
|
||||
* The MCP client can access the MCP server.
|
||||
* The required Python dependencies are installed if you start the MCP server from source.
|
||||
|
||||
## Launch modes
|
||||
|
||||
The RAGFlow MCP server supports two launch modes:
|
||||
|
||||
* **Self-host mode**
|
||||
* **Host mode**
|
||||
|
||||
The main difference is how RAGFlow user authentication is handled.
|
||||
|
||||
### Self-host mode
|
||||
|
||||
In Self-host mode, the RAGFlow API key is specified when the MCP server starts.
|
||||
|
||||
The MCP server uses this API key for requests sent to RAGFlow. All MCP clients connected to this server therefore access RAGFlow using the same RAGFlow user identity.
|
||||
|
||||
The request flow is:
|
||||
|
||||
```text
|
||||
External MCP Client
|
||||
↓
|
||||
RAGFlow MCP Server
|
||||
↓
|
||||
Configured RAGFlow API Key
|
||||
↓
|
||||
RAGFlow Server
|
||||
```
|
||||
|
||||
Self-host mode is suitable when the MCP server is dedicated to a specific RAGFlow user or trusted environment.
|
||||
|
||||
### Host mode
|
||||
|
||||
In Host mode, the MCP server is not bound to a fixed RAGFlow user when it starts.
|
||||
|
||||
Instead, each MCP client provides its own authentication information. RAGFlow determines the user and resource permissions based on the credentials provided by that client.
|
||||
|
||||
The request flow is:
|
||||
|
||||
```text
|
||||
External MCP Client
|
||||
↓
|
||||
Client authentication
|
||||
↓
|
||||
RAGFlow MCP Server
|
||||
↓
|
||||
RAGFlow Server
|
||||
```
|
||||
|
||||
Host mode is more suitable when a shared MCP server needs to serve multiple RAGFlow users.
|
||||
|
||||
## Transport protocols
|
||||
|
||||
The Python MCP server supports the following transports:
|
||||
|
||||
* **Streamable HTTP**
|
||||
* **SSE**
|
||||
|
||||
### Streamable HTTP
|
||||
|
||||
Streamable HTTP uses the following endpoint:
|
||||
|
||||
```text
|
||||
/mcp
|
||||
```
|
||||
|
||||
For example:
|
||||
|
||||
```text
|
||||
http://127.0.0.1:9382/mcp
|
||||
```
|
||||
|
||||
Streamable HTTP should be preferred for MCP clients that support it.
|
||||
|
||||
### SSE
|
||||
|
||||
The MCP server also supports the legacy SSE transport.
|
||||
|
||||
The SSE endpoint is:
|
||||
|
||||
```text
|
||||
/sse
|
||||
```
|
||||
|
||||
Messages are sent through:
|
||||
|
||||
```text
|
||||
/messages/
|
||||
```
|
||||
|
||||
For example:
|
||||
|
||||
```text
|
||||
http://127.0.0.1:9382/sse
|
||||
```
|
||||
|
||||
SSE is retained for compatibility with MCP clients that still use the legacy MCP transport.
|
||||
|
||||
> When using Host mode, check the transport requirements of
|
||||
Reference in new issue
Block a user