Ragty MCP Server

Ragty exposes read-only knowledge retrieval through the Model Context Protocol (MCP). AI clients can discover the caller's datasets and search authorized document chunks without integrating with Ragty's administration API.

Endpoint and Transport

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

The endpoint uses Streamable HTTP with stateless server sessions and JSON responses. Configure clients with the canonical trailing slash. A request to /mcp is redirected with HTTP 307 to /mcp/; /ragty/mcp is not a backend route unless an external reverse proxy explicitly maps that prefix.

Authentication

Tool discovery and execution, including tools/list, require a Bearer credential:

Credential	Format	Use
User JWT	Standard JWT	Interactive user identity in the active tenant
Personal API key	`ragty-...`	Long-lived machine credential created in Settings → API Keys

Invalid, expired, or missing credentials fail closed. Tool descriptions are advisory; authorization is recalculated when a tool is called.

Tool Discovery and Dataset Context

Ragty keeps each tool's name and input schema stable, but extends the existing tool descriptions for the authenticated caller:

list_datasets includes bounded names of currently accessible datasets.
search_datasets includes bounded names and short descriptions for semantic tool selection by clients or LLMs.
Caller-controlled dataset metadata is normalized, size-limited, and marked as untrusted data. It must never be treated as instructions.
At most 12 datasets are embedded in descriptions. If more are available, the description tells the client to call list_datasets for the complete catalog.
With no accessible datasets, discovery succeeds with an explicit no-access message.
If contextual metadata cannot be loaded after authentication, Ragty returns the original static descriptions. Tool execution still applies live RBAC.

The snapshot is generated on each explicit tools/list request. Clients may cache discovery results, so descriptions must never be used as proof of access.

Available Tools

`list_datasets`

Returns datasets accessible to the current user and tenant. Call it when the user asks which knowledge bases are available or before a dataset-scoped search.

Parameters: none

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

`search_datasets`

Runs hybrid retrieval across authorized datasets. It searches document chunks, not whole documents.

Parameter	Type	Required	Description
`query`	string	Yes	Non-empty query, maximum 2,000 characters
`dataset_ids`	string[]	No	Up to 50 dataset IDs from `list_datasets`; omitted means all accessible datasets
`top_k`	integer	No	Result limit, `1`-`100`; default `20`
`rerank`	boolean	No	Apply the configured reranker; default `false`

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

If reranking is unavailable or rejects the request, Ragty degrades to the fused hybrid-search results. Dataset IDs are authorization-filtered again at call time.

Client Configuration

Codex

Add this to ~/.codex/config.toml:

[mcp_servers.m8ty_rag]
enabled = true
url = "http://localhost:8000/mcp/"

[mcp_servers.m8ty_rag.http_headers]
Authorization = "Bearer ragty-YOUR_API_KEY"

Claude Desktop

Add a Streamable HTTP server to the Claude Desktop configuration:

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

VS Code

Add to .vscode/mcp.json:

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

Obtain an API Key

Open the frontend at http://localhost:8080.
Navigate to Settings → API Keys.
Create a personal or dataset-scoped key.
Copy the ragty-... token immediately; it is displayed only once.

Do not place API keys in source control or shared client configuration files.

23 August 2026