MCP Server

What @rushdb/mcp-server does

@rushdb/mcp-server gives MCP clients access to RushDB's graph database through agent-callable tools. Agents can inspect labels, properties, types, value distributions, ranges, indexes, and relationships before constructing queries. They can then read, create, update, replace, or delete records; attach or remove relationships; import records in bulk; and export query results as CSV.

The server also supports several search approaches. Exact record queries can use filtering, ordering, projections, grouping, and aggregations. Text indexes provide BM25 keyword search, while embedding indexes support vector similarity search after exact filtering. Hybrid searches can combine vector similarity with text. RushDB Cloud adds natural-language search and relationship-pattern analysis tools.

How it works

A client can start the package with npx @rushdb/mcp-server and communicate over stdio. In RushDB Cloud mode, the process uses an API key and connects to the Cloud API. The hosted MCP endpoint, https://mcp.rushdb.com/mcp, provides an OAuth-based connection for supported web clients, so those clients do not need a local installation or API key configuration.

For a self-hosted setup, direct mode points the server at a running RushDB engine and authenticates with an engine token. This mode uses the engine protocol directly and does not depend on the Cloud dashboard, Cloud API key, or OAuth. The server exposes a query-builder prompt through MCP Prompts; clients without prompt support can call getQueryBuilderPrompt instead. Agents are intended to discover the schema before writing searches, and schema tools include compact Markdown and structured JSON formats for that purpose.

Setup and configuration

Install or launch the package through an MCP client's server configuration:

{
  "mcpServers": {
    "rushdb": {
      "command": "npx",
      "args": ["@rushdb/mcp-server"],
      "env": {
        "RUSHDB_API_KEY": "your-api-key-here"
      }
    }
  }
}

RUSHDB_API_KEY authenticates against RushDB Cloud. RUSHDB_API_URL can override the default Cloud API URL, which is https://api.rushdb.com/api/v1.

Direct mode uses RUSHDB_MODE=direct, RUSHDB_ENGINE_URL, and RUSHDB_ENGINE_TOKEN. The engine must be running separately, for example with a local data directory and matching token. Direct mode is intended for local stdio clients; the MCP HTTP transport is tied to the Cloud OAuth flow and is unavailable in this mode.

Tools and capabilities

• Discover schemas, labels, properties, property values, joins, and query syntax.
• Find records by query, ID, uniqueness, projections, ordering, grouping, or aggregations.
• Create, upsert, update, replace, bulk-delete, and delete records.
• Create, inspect, and remove relationships between existing records.
• Export matching records as CSV.
• Create and manage BM25 text indexes and embedding indexes.
• Run keyword, vector, and hybrid searches, including searches using supplied vectors.
• Use RushDB Cloud natural-language search and relationship-pattern analysis.

Write operations accept an optional transaction ID.

Limitations and notes

Several capabilities depend on the deployment mode. RushDB Cloud-only tools include natural-language smartSearch, inferred relationship-pattern tools, and managed embedding functionality. Direct mode provides engine-backed schema, record, relationship, bulk, export, text-index, and externally supplied vector capabilities, but Cloud-only tools are not listed and are rejected if called. Cloud-managed embedding searches that require a text query are also unavailable in direct mode.

The package has separate compatibility lines for RushDB 3.x and the legacy 2.x release, so clients using the older database generation should select the matching package line. Destructive operations are available through MCP, including property deletion, record deletion, bulk deletion, relationship removal, and index deletion.