MCP Server

Expose a bigRAG instance over the Model Context Protocol so Claude Desktop, Cursor, and other MCP clients can retrieve from your collections natively.

bigRAG ships an MCP server in two shapes:

Remote HTTP — mounted on the bigRAG API at /mcp, for streamable-http clients that can send an Authorization: Bearer ... header. No local install.
Local stdio — the bigrag-mcp CLI, for Claude Desktop's config.json and older Cursor setups.

Both derive scope (all-collections vs pinned to one collection) from the API key. Local stdio adjusts its registered toolset at startup; remote HTTP always advertises the full tool list and enforces scope at call time.

Admin UI Setup

The admin UI's MCP page (/mcp) is the canonical way to set one up.

Mint a fresh bigRAG API key dedicated to that MCP (not shared with /api-keys), scoped to collection:read, document:read, and query:read.

Copy the full API key — it is shown exactly once. Paste it directly into your MCP client's bearer header or Claude Desktop config.

The MCP is persisted as a first-class server-side resource (title, server name, collection scope, key prefix) that you can later rotate or delete.

You do not pick from existing keys on /api-keys — MCP credentials live in their own namespace. If a key leaks or is lost, click Rotate key on the MCP's detail dialog. The previous key stops working immediately on the next request.

Scoping to a Single Collection

When creating the MCP in the admin UI, set Collection scope to pin it to one collection. The bigRAG API blocks cross-collection endpoints for scoped MCPs with a 403.

MCP scope	Local stdio tools	Remote HTTP tools
All collections	8 tools including `list_collections` and `multi_collection_query`	8 tools
Pinned to `X`	6 tools, all with `collection` pre-bound to `X`; `list_collections` and `multi_collection_query` are hidden	8 tools advertised; cross-collection calls return 403

There is no separate BIGRAG_COLLECTION env var — the key itself carries its scope. To change scope, delete the MCP and create a new one (or rotate after editing via the REST API).

Remote HTTP

No local install. The endpoint is stable:

https://bigrag.example.com/mcp

Every request must send the MCP key in an HTTP authorization header:

Authorization: Bearer bigrag_sk_...

Under the hood the endpoint is a FastMCP server with stateless_http=True and json_response=True; every request carries the bearer key and is dispatched through the bigRAG REST API, so auth and scope rules apply uniformly.

If your client only supports URL-only remote servers, use the local stdio bridge below until OAuth support is available.

Local stdio (Claude Desktop, older Cursor)

Install the CLI:

uv tool install bigrag
# or: pip install bigrag

Run directly:

BIGRAG_URL=https://bigrag.example.com \
BIGRAG_API_KEY=bigrag_sk_... \
bigrag-mcp

Flags

Flag	Default	Notes
`--base-url`	`http://localhost:4000`	also read from `BIGRAG_URL`
`--api-key`	(none)	also read from `BIGRAG_API_KEY`
`--transport`	`stdio`	alt: `streamable-http`
`--port`	`6101`	for streamable-http only

For streamable-http, --port sets the FastMCP bind port. The stdio transport ignores it.

Scope is discovered on startup via GET /v1/auth/whoami. If the key is pinned to a collection, the CLI registers the scoped toolset automatically.

Claude Desktop Config

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "bigrag": {
      "command": "bigrag-mcp",
      "env": {
        "BIGRAG_URL": "https://bigrag.example.com",
        "BIGRAG_API_KEY": "bigrag_sk_..."
      }
    }
  }
}

Restart Claude Desktop. The server appears under the tools icon with the tools registered for that key's scope.

Tools

All tools are thin wrappers around /v1/* endpoints. They honor the same auth and scopes as any other API client.

The query and multi_collection_query tools accept skip_cache when an MCP client needs a live retrieval instead of Redis query-cache reuse.

Full-workspace key

Tool	Calls	Purpose
`list_collections`	`GET /v1/collections`	Discover what's available.
`get_collection`	`GET /v1/collections/{name}`	Embedding / chunking config.
`get_collection_stats`	`GET /v1/collections/{name}/stats`	Document/chunk/token counts.
`query`	`POST /v1/collections/{name}/query`	Main tool — top-k chunks for a question.
`multi_collection_query`	`POST /v1/query`	Search several collections in parallel.
`list_documents`	`GET /v1/collections/{name}/documents`	Paginate documents.
`get_document`	`GET /v1/collections/{name}/documents/{id}`	Metadata for one document.
`get_document_chunks`	`GET /v1/collections/{name}/documents/{id}/chunks`	All chunks of a document.

Collection-pinned key

Local stdio registers six tools minus list_collections and multi_collection_query, with the collection / name argument removed because it is pre-bound from the key's scope. Remote HTTP advertises the same eight tool names as a full-workspace key, but scoped-key calls that would cross collection boundaries fail with 403.

Example Interaction

Once configured:

User: What does our runbook say about Postgres failover?

Model: (invokes query with collection: runbooks, query: "Postgres failover procedure", top_k: 5)

(receives top-5 chunks; synthesises an answer citing document_ids)

Limitations

Ingestion (upload and webhooks) is intentionally not exposed — MCP tools target retrieval workflows. Use the HTTP API, a language SDK, or the admin UI for writes.
Operator status polling endpoints are not wrapped — MCP tools are request/response retrieval helpers.
OAuth 2.0 flows are not implemented. Remote HTTP clients must send Authorization: Bearer ...; URL query-token authentication is not accepted on /mcp.

On this page