MCP Server (RAG)

The RAG server exposes an MCP (Model Context Protocol) endpoint for AI agents to search knowledge bases programmatically.

Endpoint

POST /mcp/
Content-Type: application/json
Authorization: Bearer <token>

Supports both Accept: application/json and Accept: text/event-stream. Stateless — no session management required.

Authentication

Two token types are accepted via Authorization: Bearer:

Token Type	Format	Description
JWT	Standard JWT	User session token (from login)
Personal API Key	`ragty-...`	Long-lived API key (Settings → API Keys)

The server distinguishes them by prefix — tokens starting with ragty- go through the API key resolution path, others are decoded as JWT.

Available Tools

list_datasets

Returns all datasets accessible to the authenticated user/tenant. Call this first to discover available knowledge bases and get dataset IDs for scoped search.

Parameters: None

Response:

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Company Policies",
    "description": "HR and compliance documents",
    "document_count": 42
  }
]

search_datasets

Searches document chunks using hybrid retrieval (dense embeddings + sparse BM25). Returns ranked text chunks with metadata — not whole documents.

Parameters:

Name	Type	Required	Description
`query`	string	Yes	The search query text
`dataset_ids`	string[]	No	Dataset IDs (NOT document IDs) from `list_datasets`. Restricts search scope. Omit to search all accessible datasets.
`top_k`	integer	No	Max results to return (default: 20, max: 100)
`rerank`	boolean	No	Apply cross-encoder reranking for better relevance (default: false, slower)

Response:

[
  {
    "score": 0.87,
    "content": "The vacation policy allows up to 25 days...",
    "document_id": "doc-uuid",
    "page_num": 3,
    "layout_type": "text"
  }
]

Client Configuration

Codex / Generic MCP Client

Create or edit ~/.codex/config.json:

{
  "mcpServers": {
    "m8ty-rag": {
      "type": "http",
      "url": "http://localhost:8000/mcp/",
      "headers": {
        "Authorization": "Bearer ragty-YOUR_API_KEY"
      }
    }
  }
}

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "m8ty-rag": {
      "type": "streamableHttp",
      "url": "http://localhost:8000/mcp/",
      "headers": {
        "Authorization": "Bearer ragty-YOUR_API_KEY"
      }
    }
  }
}

VS Code (Copilot MCP)

Add to .vscode/mcp.json:

{
  "servers": {
    "m8ty-rag": {
      "type": "http",
      "url": "http://localhost:8000/mcp/",
      "headers": {
        "Authorization": "Bearer ragty-YOUR_API_KEY"
      }
    }
  }
}

Obtaining an API Key

Log in to the frontend at http://localhost:3000
Navigate to Settings → API Keys
Click Create Key → choose "Personal" or "Dataset-scoped"
Copy the ragty-... token (shown once only)

Or via CLI:

# Login
TOKEN=$(curl -s -X POST http://localhost:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"pass"}' | jq -r .access_token)

# Create key
curl -s -X POST http://localhost:8000/keys \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"scope_type":"personal","name":"My Agent"}' | jq .token

12 June 2026