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

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 two tools today.

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

required

The ID of the Ragen assistant (project) to send the message to. Use ragen_list_assistants to discover available IDs.

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": 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 all assistants available to your API key’s organization. Use this to discover assistant IDs before calling ragen_chat.ParametersThis tool takes no parameters.ResponseOn success:

{
  "success": true,
  "assistants": [
    { "id": "asst-abc123", "name": "Support Bot" },
    { "id": "asst-def456", "name": "Sales Bot" }
  ]
}

On failure:

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

Scoping is automatic: results are limited to assistants owned by the API key’s organization. There is no separate access configuration required.

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 supports Streamable HTTP MCP servers via a proxy command; use npx with the @modelcontextprotocol/server-fetch helper (or any HTTP-to-stdio bridge you prefer):

claude_desktop_config.json

{
  "mcpServers": {
    "ragen": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-fetch",
        "https://your-ragen-instance.example.com/mcp"
      ],
      "env": {
        "AUTHORIZATION": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Replace https://your-ragen-instance.example.com/mcp with your actual $RAGEN_MCP_URL/mcp value.

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": "asst-abc123", "name": "Support Bot" },
    { "id": "asst-def456", "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 "asst-abc123" 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": "asst-abc123",
  "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 two tools: ragen_chat and ragen_list_assistants. 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