Ragen MCP Server: Connect Claude Desktop and AI Agents

The Ragen MCP Server exposes your Ragen assistants as Model Context Protocol tools, so any MCP-compatible client — Claude Desktop, Cursor, or a custom agent — can query your knowledge base directly without calling the REST API yourself. You send a natural-language message, the server forwards it to the right assistant, runs retrieval and generation server-side, and returns a grounded answer.

Connecting

Point your MCP client at the Streamable HTTP endpoint:

$RAGEN_MCP_URL/mcp

Authenticate using the same API key you use for the REST API — send it as a Bearer token on every connection:

Authorization: Bearer YOUR_API_KEY

To check a connection one layer at a time, and to see what each error means, see Testing the connection. The server also has a stdio mode, for a client that starts it as a local process. There the key comes from the RAGEN_API_KEY environment variable instead of a header. See Running the server locally over stdio.

Over HTTP, a connection with no Authorization header, or one that isn’t Bearer-prefixed, is rejected with a 401 before any tool call is possible. The API key is validated on each tool invocation — a deactivated or malformed key fails the same way it would calling the REST API directly.

Available Tools

The Ragen MCP Server exposes three tools. Each call runs with the permissions of the person who created the API key — see Authentication.

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 an assistant

Send a message to a Ragen assistant and receive a grounded answer drawn from its knowledge base. This is the MCP equivalent of POST /v1/chat.Parameters

string

The ID of the Ragen 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. Must be at least one character.

string

Optional additional context to include alongside the message — for example, the content of the page the user is currently viewing. Helps the assistant give more relevant answers.

string

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

ResponseOn success:

{
  "success": true,
  "text": "Based on your documentation, the refund policy allows returns within 30 days..."
}

On failure:

{
  "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 — you named an assistant the key is not scoped to, or named one at all on a knowledge-base key. A 404 is the other case, an assistant that does not exist for this organization:

{
  "success": false,
  "status": 404,
  "error": "Assistant not found"
}

ragen_chat is always non-streaming. MCP tool calls return a single result, not a Server-Sent Events stream. If you need token-by-token streaming, call the Chat API directly with stream: true.

ragen_list_assistants — List available assistants

List the assistants your API key can reach. A knowledge-base key sees every assistant its organization owns; a key created for one assistant sees that one. Use this to discover assistant IDs before calling ragen_chat — or, if exactly one comes back, to confirm you can omit the parameter.ParametersThis tool takes no parameters.ResponseOn success:

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

On failure:

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

Scoping is automatic and follows the key: the organization’s assistants for a knowledge-base key, the single bound one for an assistant-scoped key. There is no separate access configuration required.

ragen_search_knowledge_base — Retrieve document chunks without an answer

Search the knowledge base and return the most relevant document chunks, with no model call. This is the MCP equivalent of POST /v1/search: use it when your agent should reason over the documents itself.Parameters

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. Must be at least one character.

integer

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

ResponseOn success:

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

On error:

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

Configuring Claude Desktop

To add Ragen to Claude Desktop, open your claude_desktop_config.json file and add a ragen entry under mcpServers:

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/mcp with your actual $RAGEN_MCP_URL/mcp value. To run the server on your own machine instead, without mcp-remote, start it over stdio. See Running the server locally over stdio.

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.

On macOS, the claude_desktop_config.json file lives at ~/Library/Application Support/Claude/claude_desktop_config.json. Restart Claude Desktop after saving changes for them to take effect.

Step-by-Step Usage Example

Once your MCP client is connected, follow these steps to query your knowledge base:

List your assistants

Call ragen_list_assistants with no parameters to see which assistants are available to your API key.

// Tool: ragen_list_assistants
// Parameters: (none)

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

Pick an assistant ID

Identify the id of the assistant whose knowledge base you want to query. In the example above, you’d use "11111111-1111-4111-8111-111111111111" to reach the Support Bot.

Ask your question with ragen_chat

Call ragen_chat with your chosen assistant_id and the question you want answered.

// Tool: ragen_chat
{
  "assistant_id": "11111111-1111-4111-8111-111111111111",
  "message": "What is the return policy for digital products?"
}

// Response:
{
  "success": true,
  "text": "Digital products are non-refundable once downloaded, unless the product is defective..."
}

Current Scope

Today the Ragen MCP Server exposes three tools: ragen_chat, ragen_list_assistants and ragen_search_knowledge_base. File upload and full thread history via MCP are on the roadmap — they follow the same pattern and will be added as additional tools in a future release.

Chat API Quickstart

Use the TypeScript SDK or REST API directly for streaming and advanced control.

TypeScript SDK Reference

Full method reference for @webamigos/ragen-sdk-ts, including file upload and error handling.

Getting Started

Endpoints

SDKs & Tools

Ragen MCP Server: Connect Claude Desktop and AI Agents

Connecting

Available Tools

Configuring Claude Desktop

Step-by-Step Usage Example

Current Scope

Chat API Quickstart

TypeScript SDK Reference

​Connecting

​Available Tools

​Configuring Claude Desktop

​Step-by-Step Usage Example

​Current Scope

Chat API Quickstart

TypeScript SDK Reference

Connecting

Available Tools

Configuring Claude Desktop

Step-by-Step Usage Example

Current Scope