MCP server

RosalindDB ships an MCP server, so an AI coding assistant can manage datasets and run vector search by making tool calls — no API client or glue code in between. It's a stdio server you point any MCP client at.

What it is

@rosalinddb/mcp is a small Model Context Protocol server. It speaks MCP over stdio and exposes eight tools that wrap RosalindDB's v1 REST API — dataset CRUD, vector ingestion, similarity search, and usage checks.

Once it's configured, your assistant can do the work for you: "create a dataset called products at 768 dimensions" or "search products for the ten nearest vectors where category is books" both become tool calls the agent makes directly.

It works with any MCP client — Claude Code, Claude Desktop, Cursor, and others.

Install

The server runs on demand via npx — nothing to install globally. Pick your MCP client for the exact setup:

Client

Add it from the command line — Claude Code writes the config for you:

claude mcp add rosalinddb \
  --env ROSALINDDB_API_URL=http://localhost:8080 \
  -- npx -y @rosalinddb/mcp

Or add it by hand to .mcp.json in your project root (the project-scoped, git-shareable config):

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

Then — run /mcp inside Claude Code to confirm the rosalinddb tools loaded. The eight RosalindDB tools become available to the assistant.

ROSALINDDB_API_URL is your API base URL — http://localhost:8080 against a local docker compose up stack, or the public URL of your self-hosted instance. No API key is needed in OSS-default mode (RB_REQUIRE_AUTH=false) — the snippet above is the whole config. If your backend has auth turned on, also set ROSALINDDB_API_KEY to an rb_live_… key created via POST /auth/keys.

Tools

The server exposes eight tools, each a thin wrapper over a v1 REST endpoint:

list_datasets — list every dataset in your tenant.
create_dataset — create a dataset with a fixed embedding dimension.
get_dataset — fetch one dataset's status and row count.
delete_dataset — soft-delete a dataset.
ingest_vectors — ingest a batch of vectors into a dataset.
query_vectors — top-K similarity search, with optional metadata filtering.
get_usage — current usage against your quotas.
list_api_keys — list your API keys (metadata only).

Bulk imports (NDJSON or Parquet, files over ~10 MiB) aren't in the MCP surface — they use the async REST import-job flow directly (POST /v1/datasets/{name}/imports → presigned upload → poll for completion), which doesn't fit cleanly into a single tool call. ingest_vectors stays the right tool for small interactive upserts.