Use Your Ragen AI Assistants from Any MCP-Compatible Client

The Ragen MCP Server lets any MCP-compatible client — Claude Desktop, Cursor, Hermes Agent, a custom agent, or any tool that speaks the Model Context Protocol — talk directly to your Ragen assistants. Instead of integrating the Chat REST API yourself, point your client at the MCP endpoint and start chatting with your knowledge base immediately. This is the reverse of MCP Connectors: here, an external client calls into Ragen rather than Ragen calling out to other services.

Connecting your client

Point your MCP client at the Streamable HTTP endpoint:

$RAGEN_MCP_URL/mcp

Authenticate using a Ragen API key — the same key you’d use for the REST API. Send it as a Bearer token on every connection:

Authorization: Bearer YOUR_API_KEY

A connection with no Authorization header, or one that isn’t Bearer-prefixed, is rejected with 401 before any tool call can proceed. Ragen validates the key on each tool call — a deactivated or malformed key fails exactly as it would on POST /v1/chat. Every tool call runs with the permissions of the person who created the key: the key’s scope picks the assistant or the knowledge base, and inside it retrieval applies that person’s document permissions, the same as in the web app. See Authentication.

Available tools

Omit assistant_id unless you have one. The API key carries a scope: a key created for one assistant answers for it without being told, and a key scoped to the whole knowledge base rejects a request naming any assistant with 403. ragen_list_assistants shows what the key you connected with can reach. See Authentication.

`ragen_chat`

Send a message to a Ragen assistant and receive its answer.

string

The ID of the assistant (project) to send the message to. Optional — the key decides by itself, and naming an assistant it is not scoped to is refused. Use ragen_list_assistants to see what this key can reach.

string

required

The message to send to the assistant.

string

Additional context to include alongside the message — for example, the content of the page the caller is currently viewing.

string

OpenAI-style reasoning effort level: "low", "medium", or "high". Only honoured by reasoning-capable models; ignored otherwise.

Success response:

{ "success": true, "text": "Based on your documentation, the return window is 30 days from the date of purchase." }

Error response:

{ "success": false, "status": 403, "error": "This API key is scoped to a different assistant than '11111111-1111-4111-8111-111111111111'" }

A 403 means the key and the request disagree about the assistant — either you named one the key is not scoped to, or you named one at all on a knowledge-base key. A 404 still means the assistant does not exist for this organization.

ragen_chat is always non-streaming. An MCP tool call returns a single result, so there is no mechanism to forward a partial answer token-by-token. If you need streaming responses, call the Chat API directly with stream: true.

`ragen_list_assistants`

List the assistants your API key can reach. A knowledge-base key sees every assistant its organisation owns; a key created for one assistant sees that one. Use this to find an assistant_id before calling ragen_chat — or, if exactly one comes back, to confirm you can omit it. This tool takes no parameters. Success response:

{
  "success": true,
  "assistants": [
    { "id": "11111111-1111-4111-8111-111111111111", "name": "Support Bot" },
    { "id": "22222222-2222-4222-8222-222222222222", "name": "Sales Bot" }
  ]
}

Error response:

{ "success": false, "status": 401, "error": "Unauthorized" }

Scoping is automatic: this calls the same GET /v1/assistants endpoint as the REST API, which returns what the key can reach — the organisation’s assistants for a knowledge-base key, the single bound one otherwise. The example above shows a knowledge-base key. There is no additional access configuration needed.

`ragen_search_knowledge_base`

Search the knowledge base and get back the most relevant document chunks, without generating an answer. Use it when your agent should reason over Ragen’s documents itself — or when you want to check what Ragen retrieves before blaming the answer. It is the MCP equivalent of POST /v1/search.

string

The assistant (project) whose knowledge base to search. Optional — the key decides by itself, and naming an assistant it is not scoped to is refused.

string

required

The search query.

integer

Maximum number of chunks to return, a whole number from 1 to 20. Defaults to the organisation’s configured retrieval count.

Success response:

{
  "success": true,
  "context": "**Refund Policy**\n\nCustomers may return items within 30 days of purchase...",
  "file_ids": ["file-abc123", "file-def456"]
}

context is the same block Ragen’s chat passes to the model; file_ids are the source files, which GET /v1/files/{id} resolves. Error response:

{ "success": false, "status": 403, "error": "This API key is scoped to a different assistant than '11111111-1111-4111-8111-111111111111'" }

Configuring Claude Desktop

There are two ways to connect, depending on where the MCP server runs:

Your Ragen instance already runs the MCP server. Connect to its /mcp endpoint through mcp-remote, below.
It does not, or you would rather run it on your own machine. Claude Desktop can start the server itself over stdio. See Running the server locally over stdio.

Connecting to a deployed server

Add a ragen entry to your Claude Desktop configuration file:

claude_desktop_config.json

{
  "mcpServers": {
    "ragen": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://your-ragen-instance.example.com/mcp",
        "--header",
        "Authorization:${RAGEN_AUTH}"
      ],
      "env": {
        "RAGEN_AUTH": "Bearer YOUR_API_KEY"
      }
    }
  }
}

claude_desktop_config.json launches local processes over stdio; it has no field for a remote URL or request headers. mcp-remote is the bridge: Claude Desktop starts it as a process, and it forwards every call to your Ragen MCP endpoint over Streamable HTTP with the Authorization header attached. Replace https://your-ragen-instance.example.com with your RAGEN_MCP_URL value and YOUR_API_KEY with a valid Ragen API key.

The header goes through an environment variable, written as Authorization:${RAGEN_AUTH} with no space after the colon: some clients split arguments on spaces, and Bearer YOUR_API_KEY inside args would arrive as two arguments.

After saving the config, restart Claude Desktop. You should see ragen_chat, ragen_list_assistants and ragen_search_knowledge_base in Claude’s tool list. Call ragen_list_assistants first to confirm the connection is working and to retrieve your assistant IDs.

Running the server locally over stdio

Claude Desktop can start the MCP server as a local process and talk to it over stdin and stdout, with no mcp-remote in between. The server still calls your Ragen API for every tool, so the API has to be reachable from your machine.

claude_desktop_config.json

{
  "mcpServers": {
    "ragen": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "TARGET_ENV=local",
        "-e", "RAGEN_MCP_TRANSPORT=stdio",
        "-e", "RAGEN_API_URL",
        "-e", "RAGEN_API_KEY",
        "ghcr.io/webamigos/ragen-mcp:latest"
      ],
      "env": {
        "RAGEN_API_URL": "https://your-ragen-api.example.com",
        "RAGEN_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

RAGEN_API_URL is the address of the Ragen API (the api service), not of the MCP server, and it is resolved from inside the container. If the API runs on the same machine, localhost points at the container itself. On Docker Desktop, use http://host.docker.internal:3001 instead. RAGEN_API_KEY is the key on its own, without Bearer. Over stdio there is no request to carry an Authorization header, so the server reads the key from its environment instead.

Without RAGEN_API_KEY the server still starts and lists its tools, and every tool call returns an error naming the variable to set. That error is the first thing to check if the tools appear but never answer.

Stdio needs Ragen 2.37.0 or later. Pin the image to a version you have checked (ghcr.io/webamigos/ragen-mcp:2.37.0) if you would rather not follow latest.

Configuring Cursor

In Cursor’s MCP settings, add a new server entry with:

Transport: Streamable HTTP
URL: $RAGEN_MCP_URL/mcp
Authorization header: Bearer YOUR_API_KEY

.cursor/mcp.json

{
  "mcpServers": {
    "ragen": {
      "url": "https://your-ragen-instance.example.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Configuring Hermes Agent

Hermes Agent is a personal agent that runs on your own machine or server. Connected to Ragen, it answers from your company knowledge base within the permissions of the person whose key it uses, while Hermes itself handles tasks, memory and messaging channels. Tested with Hermes Agent 0.16.0. Add a ragen entry under mcp_servers in the Hermes config.yaml (~/.hermes/config.yaml, or a profile’s own file under ~/.hermes/profiles/<name>/):

config.yaml

mcp_servers:
  ragen:
    url: "https://your-ragen-instance.example.com/mcp"
    headers:
      Authorization: "Bearer ${RAGEN_API_KEY}"
    timeout: 120

Hermes resolves ${RAGEN_API_KEY} from its environment when it connects, so the key never has to be written into the file. Set it without echoing it, then check the connection:

hermes mcp test ragen

A working connection reports Tools discovered: 3 and lists ragen_chat, ragen_list_assistants and ragen_search_knowledge_base. Hermes exposes them to the model as mcp_ragen_ragen_chat and so on, and marks every result as untrusted tool output.

Create the key as the person who will use the agent. A key carries the permissions of the person who created it, so a key created by an organization owner gives the agent the owner’s view of every document. With a plain member’s key, a document the member cannot open in the web app is not returned to the agent either, through ragen_search_knowledge_base or ragen_chat.

If the agent should only answer from the knowledge base, give it a dedicated profile and switch off the toolsets it does not need, such as the terminal and file access:

hermes profile create ragen --no-skills
hermes -p ragen tools disable terminal file code_execution browser computer_use

Hermes and Ragen can share one model server. Point both at the same Ollama or vLLM endpoint (Open models). Hermes needs a model with a context window of at least 64,000 tokens.

Custom agents

For custom agents or any MCP-compatible SDK, use Streamable HTTP transport and supply the Authorization: Bearer header on connection. All standard MCP tool-call patterns apply — discover tools with the standard tools/list method and invoke them with tools/call.

ragen_chat

Send a question to a specific assistant and receive a complete answer in one call.

ragen_list_assistants

Discover the assistants your API key can reach.

ragen_search_knowledge_base

Retrieve the most relevant document chunks, with no answer generated.

Testing the connection

Before you configure a client, you can check each layer from a terminal with the MCP Inspector CLI. Run the commands in order. Each one depends on everything the one before it proved, so the first failure tells you which layer is broken.

Set the key without echoing it

Read the key into a variable instead of typing it on the command line, where it would land in your shell history and on screen:

read -s RAGEN_API_KEY && export RAGEN_API_KEY

Paste the key and press Enter. Nothing is shown. Set RAGEN_MCP_URL to your server’s address the same way, or with a plain export, since it is not a secret.

Check one layer at a time

The MCP server: list its tools

npx -y @modelcontextprotocol/inspector --cli "$RAGEN_MCP_URL/mcp" --transport http --header "Authorization: Bearer $RAGEN_API_KEY" --method tools/list

You should see ragen_chat, ragen_list_assistants and ragen_search_knowledge_base. This step does not check the key: the MCP server only checks that the header is shaped like Bearer <key>. A pass proves the server is reachable, nothing more.

The key and the Ragen API: list assistants

npx -y @modelcontextprotocol/inspector --cli "$RAGEN_MCP_URL/mcp" --transport http --header "Authorization: Bearer $RAGEN_API_KEY" --method tools/call --tool-name ragen_list_assistants

"success": true with a list of assistants means the key is valid. It also means the Ragen API, and the token vault it checks keys against, both work.

Retrieval: search the knowledge base

npx -y @modelcontextprotocol/inspector --cli "$RAGEN_MCP_URL/mcp" --transport http --header "Authorization: Bearer $RAGEN_API_KEY" --method tools/call --tool-name ragen_search_knowledge_base --tool-arg "query=refund policy"

"success": true means the vector store answers. An empty file_ids list is still a pass: retrieval works, and this query found nothing.

A model answer: chat

npx -y @modelcontextprotocol/inspector --cli "$RAGEN_MCP_URL/mcp" --transport http --header "Authorization: Bearer $RAGEN_API_KEY" --method tools/call --tool-name ragen_chat --tool-arg "message=What is this knowledge base about?"

This spends model tokens, so run it last.

Reading the result

What you see	What it means
`401` before any tool runs	The `Authorization` header is missing, or it is not `Bearer <key>`
`404` when connecting	Nothing answers MCP at this URL. It should end in `/mcp`
Tools are listed, then `"status": 401, "error": "Invalid API key"`	The key is wrong or deactivated. On a self-hosted instance, the API may also be unable to reach its token vault
`"status": 403`	The key’s scope does not cover the request. A key created for one assistant only answers for that assistant
`"status": 0, "error": "fetch failed"`	The MCP server cannot reach the Ragen API
`"status": 500` from search or chat	The Ragen API failed behind the MCP server. See When tools are listed but calls fail

When you are done testing, deactivate a key you created only for the test in Organization → API keys.

Self-hosting the MCP server

If you run Ragen yourself, the MCP server is a separate service — a thin one. It owns no data: every tool call forwards an API key to the Ragen API, which does the authentication, the retrieval and the rate limiting. That is why it configures in three variables, plus two for stdio and two optional ones for OpenTelemetry. Use the published image, ghcr.io/webamigos/ragen-mcp, or build it from the repository’s apps/mcp/Dockerfile, whose build context is the repository root, and run node dist/index.js. By default it listens for Streamable HTTP on /mcp; with RAGEN_MCP_TRANSPORT=stdio it serves one client over stdin and stdout instead.

Environment variables

Variable	Required	Default	What it does
`TARGET_ENV`	yes	—	`local`, `staging` or `production`. Deployed instances must set it; see the warning below.
`RAGEN_API_URL`	yes when deployed	`http://localhost:3001`	Where the Ragen API answers. On a platform with private networking, use the internal address.
`RAGEN_MCP_PORT`	no	`3300`	The port the server listens on. Prefer this over `PORT`.
`PORT`	no	`3300`	Also honoured, for single-container hosts that inject it. `RAGEN_MCP_PORT` wins when both are set — three services in the Ragen repository read a bare `PORT`, and a checkout’s root `.env.local` is shared by all of them, so one value moves all three.
`RAGEN_MCP_TRANSPORT`	no	`http`	`http` serves Streamable HTTP on `/mcp`. `stdio` serves one client over stdin and stdout, for a client that starts the server as a local process. Logs then go to stderr.
`RAGEN_API_KEY`	over stdio	—	The API key used for every tool call over stdio, written without `Bearer`. Ignored over HTTP, where each caller sends its own.
`OTEL_EXPORTER_OTLP_ENDPOINT`	no	—	Enables tracing. Without it, telemetry is a no-op.
`OTEL_SERVICE_NAME`	no	—	The service name in traces.

There is nothing else — no database, no Redis, no API key of its own over HTTP. There, a key belongs to whoever is calling, arrives per request, and is never stored. Over stdio the server serves one client, so that client’s key comes from RAGEN_API_KEY.

TARGET_ENV is what makes RAGEN_API_URL required. A deployment that leaves it unset would read as local, accept the localhost fallback, boot cleanly, and then fail every tool call with a connection error. Recent versions refuse to start instead — if yours boots without it, set it anyway and check RAGEN_API_URL really points at your API.

When tools are listed but calls fail

The MCP server’s health check (/health) and its tool list do not depend on the Ragen API, so both pass while every tool call fails. The calls depend on variables of the api service, not of the MCP server:

Symptom	Where to look
`"status": 0`, `fetch failed`	`RAGEN_API_URL` on the MCP server: the API’s address as seen from the MCP server’s container
`401 Invalid API key` for a key you just created	`RAGEN_TOKEN_VAULT_URL` (and its secret) on the `api` service: the API checks every key against the token vault
`500` from `ragen_search_knowledge_base` or `ragen_chat`	The `api` service’s logs. An unset or unreachable `QDRANT_URL` is the usual cause, then the model provider’s credentials

If you have a checkout of the Ragen repository, its smoke test runs all of the steps above against a URL and prints a hint naming the service and variable for the first one that fails:

npm run smoke --workspace=@ragenai/mcp -- "$RAGEN_MCP_URL/mcp"

It reads the key from RAGEN_API_KEY and exits with 1 when a step fails, so it can also run after a deployment.

Get Started

Core Concepts

Configuration

Integrations

Security

Resources

Use Your Ragen AI Assistants from Any MCP-Compatible Client

Connecting your client

Available tools

`ragen_chat`

`ragen_list_assistants`

`ragen_search_knowledge_base`

Configuring Claude Desktop

Connecting to a deployed server

Running the server locally over stdio

Configuring Cursor

Configuring Hermes Agent

Custom agents

ragen_chat

ragen_list_assistants

ragen_search_knowledge_base

Testing the connection

Set the key without echoing it

Check one layer at a time

Reading the result

Self-hosting the MCP server

Environment variables

When tools are listed but calls fail

​Connecting your client

​Available tools

​ragen_chat

​ragen_list_assistants

​ragen_search_knowledge_base

​Configuring Claude Desktop

​Connecting to a deployed server

​Running the server locally over stdio

​Configuring Cursor

​Configuring Hermes Agent

​Custom agents

ragen_chat

ragen_list_assistants

ragen_search_knowledge_base

​Testing the connection

​Set the key without echoing it

​Check one layer at a time

​Reading the result

​Self-hosting the MCP server

​Environment variables

​When tools are listed but calls fail

Connecting your client

Available tools

`ragen_chat`

`ragen_list_assistants`

`ragen_search_knowledge_base`

Configuring Claude Desktop

Connecting to a deployed server

Running the server locally over stdio

Configuring Cursor

Configuring Hermes Agent

Custom agents

Testing the connection

Set the key without echoing it

Check one layer at a time

Reading the result

Self-hosting the MCP server

Environment variables

When tools are listed but calls fail