@rosalinddb/mcp

Model Context Protocol server for RosalindDB.

A Model Context Protocol (MCP) server for RosalindDB — a cost-optimized, object-storage-first vector search database.

This server lets MCP-capable AI clients (Claude Desktop, Cursor, Claude Code, and others) operate a RosalindDB instance directly: create datasets, ingest vectors, run similarity queries, and check usage — without hand-writing REST calls. It is a thin wrapper over RosalindDB's v1 REST API: it authenticates with an rb_live_ API key when the backend has auth enabled, otherwise it runs unauthenticated against an OSS-default backend. It contains no business logic of its own.

The RosalindDB engine lives at rosalinddb/rosalinddb. Self-host it via docker compose and point this MCP at it.

Tools

For very large embedding dumps (over the 10 MiB ingest_vectors cap), use RosalindDB's async import-job flow directly via the REST API.

Related MCP server: MCP-Smallest.ai

Recall tier (read-your-writes)

RosalindDB can run an optional recall tier — a hot pgvector instance the server enables with RB_RECALL + RB_RECALL_DSN. It's transparent to this MCP (nothing to configure client-side), but it changes the behavior an agent sees:

• ingest_vectors is read-your-writes. With recall on, an upsert is synchronous (no job_id in the result) and the vector is immediately returned by the next query_vectors. With recall off, ingest is eventually consistent (returns a job_id) — poll get_dataset until status is indexed.

• delete_vector is read-your-deletes. With recall on, a delete is a synchronous tombstone ({ synchronous: true }) and the vector is gone from queries at once; with recall off it queues a rebuild ({ async: true, job_id }).

• query_vectors reports the serving tier in mode: recall (the recall tier), hot/cold (the consolidated object-storage tier — hot = shard already cached in memory, cold = first fetch), or ephemeral (no shard yet, computed on demand). Recall and consolidated results are unioned, with recall authoritative for anything written since the last consolidation.

This makes RosalindDB usable as agent working memory: store a fact and recall it on the very next turn. See the engine's recall / consolidate docs.

Auth modes

The RosalindDB backend ships in two modes; the MCP server supports both:

• OSS default (RB_REQUIRE_AUTH=false): no auth, no API key needed. This is what docker compose up gives you out of the box. Set ROSALINDDB_API_URL to your stack and leave ROSALINDDB_API_KEY unset. The list_api_keys, get_usage, and signup endpoints are disabled in this mode; calls to them surface a clear auth_disabled hint.

• Multi-tenant self-host (RB_REQUIRE_AUTH=true): set ROSALINDDB_API_KEY=rb_live_.... Create a key with POST /auth/keys (or use POST /auth/signup for the first user on a fresh stack).

Configuration

The server reads two environment variables:

When set, the key is sent as Authorization: Bearer rb_live_... on every request. A key that doesn't start with rb_live_ triggers a startup warning but is not rejected (in case you front the backend with a custom auth proxy).

Wiring it into an MCP client

Add this to your MCP client config (for Claude Desktop, claude_desktop_config.json):

{
  "mcpServers": {
    "rosalinddb": {
      "command": "npx",
      "args": ["-y", "@rosalinddb/mcp"],
      "env": {
        "ROSALINDDB_API_URL": "http://localhost:8080"
      }
    }
  }
}

npx -y @rosalinddb/mcp downloads and runs the server on demand — no global install needed. The server speaks the stdio transport, the standard for a locally-launched MCP server.

Pointing at a non-local instance? Set ROSALINDDB_API_URL to its base URL. If auth is on, also set ROSALINDDB_API_KEY=rb_live_.... The backend lives at rosalinddb/rosalinddb.

Local development

npm install        # install dependencies
npm run build      # compile TypeScript to dist/
npm test           # run the vitest unit + in-process MCP suite
npm run smoke      # build, then drive a real tools/list over stdio

To run the server directly from a local checkout:

{
  "mcpServers": {
    "rosalinddb": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/index.js"],
      "env": {
        "ROSALINDDB_API_URL": "http://localhost:8080"
      }
    }
  }
}

Live smoke test

With a running RosalindDB stack and a real key, tests/live-smoke.mjs exercises create → ingest → usage → query → delete end to end:

npm run build
ROSALINDDB_API_KEY=rb_live_... node tests/live-smoke.mjs

It is skipped automatically when no key is set.

Error handling

RosalindDB API errors are mapped to clear, actionable MCP tool errors — never a raw stack trace. A 404 surfaces as "dataset does not exist — list datasets or create it first"; a 429 quota error explains the limit and how to recover; a 404 auth_disabled (calling list_api_keys against an OSS-default backend) explains that the auth endpoints are gated behind RB_REQUIRE_AUTH=true; and a 503 recall_write_failed / recall_delete_failed / recall_unavailable explains that the read-your-writes tier is momentarily down and the call should be retried.

License

Apache 2.0. See LICENSE.

Security

To report a vulnerability, see SECURITY.md.