Connecting and working with the MCP application server

[Hekas1]

Dear community members, please help me figure out how to connect and work with the tool server to RagFlow
I have a running tool server that has an API key, but when I connect it to the RagFlow interface, I constantly get an error:

hint : 102
Test MCP error: Connection failed (possibly due to auth error). Please check authentication settings first

I also launched the tool server that comes with RagFlow, it starts when it starts, is it possible to connect it to the interface in RagFlow

I would be grateful for any help.

[dosubot[bot]]

The "hint : 102 Test MCP error: Connection failed (possibly due to auth error)" almost always means there's an authentication problem—usually the API key is missing, incorrect, or not being sent in the right way, or the endpoint is not pointing to an active/compatible MCP server.

Here's a checklist to help you connect your tool (MCP) server to RagFlow:

1. Make sure your MCP server is running with the correct parameters. For the bundled server, the typical command is:

   uv run mcp/server/server.py --host=127.0.0.1 --port=9382 --base-url=http://127.0.0.1:9380 --mode=self-host --api-key=ragflow-xxxxx
   

   The API key must start with ragflow- and match exactly what you enter in the RagFlow UI. If you use Docker, check that the --mcp-host-api-key is set and not wrapped in quotes, and that ENABLE_MCP_SERVER is enabled in your environment or docker-compose file [docs].

2. In the RagFlow interface, go to Profile Settings → MCP Servers. When adding a new MCP server, enter:

   • Name (any label)
   • URL (e.g., http://127.0.0.1:9382)
   • Server type (sse or streamable-http, matching your server's transport)
   • Authorization token (the same API key you used to launch the MCP server) [UI code]

3. Use the "Test" button in the dialog. If the test fails with the same error, double-check:

   • The API key matches exactly (no extra spaces, no quotes)
   • The URL points to the correct host and port, and the MCP server is running
   • The server type matches the transport enabled on your MCP server (sse or streamable-http)
   • The MCP server is in the correct mode (self-host if using a single API key, host for multi-tenant)

4. The bundled MCP server can be used—just make sure it's started with the correct parameters as above. By default, it listens on localhost:9382 and expects the RagFlow backend at http://127.0.0.1:9380 [docs].

If you still get the error, check the MCP server logs for authentication or connection errors—they often provide more detail about what's wrong with the request or key.

Let me know if you need help with a specific configuration or error message!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[Hekas1]

Sorry, but it not work

[dosubot[bot]]

The most common cause of this error is a mismatch between the MCP server's mode, transport type, and the settings you choose in the RagFlow UI. If your MCP server is running in host mode, you must disable the streamable-HTTP transport using the --no-transport-streamable-http-enabled flag, because streamable-HTTP is not supported in host mode yet. If you're using self-host mode, make sure the API key you launch the MCP server with matches exactly what you enter in the RagFlow UI, and that the transport type (SSE or streamable-http) matches on both sides see docs and recent changes.

Can you share the exact command you use to start your MCP server, the API key you enter in the RagFlow UI, and which server type (SSE or streamable-http) you select? Also, check the MCP server's startup logs—they should show which transports are enabled and the mode. This info will help pinpoint the issue.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[ZhenhangTung]

@Hekas1 Could you share screenshots? Are you using Agent's MCP tools?

[Hekas1]

I have rusted the omcp tools server with the OpenAI compatibility standard
The tools work, I can use them
I also have an MCP server running together with the RagFlow server.
However, I cannot connect the tools in the RagFlow interface. I get the error:

Test MCP error: Connection failed (possibly due to auth error). Please check authentication settings first

[ZhenhangTung]

@yongtenglei pls take a look.

[yongtenglei]

Hi, @Hekas1

Check your URL?

A classic URL for SSE is something like http://localhost:9382/sse and http://localhost:9382/mcp/ for Streamable-HTTP.