Connect

MCP Server

Give an AI assistant direct access to your RushDB data without writing integration code. The RushDB MCP server (@rushdb/mcp-server) runs in three ways:

Mode	Best for	Connects to	Setup
Hosted OAuth	ChatGPT, Claude.ai, web clients	RushDB Cloud	Add one URL and sign in
Local, Cloud API key	Claude Desktop, Cursor, VS Code	RushDB Cloud	Add an MCP config block
Local, self-hosted engine	Claude Desktop, Cursor, VS Code	Your own `rushdb` engine	Add an MCP config block

Reference: MCP Server Reference · All MCP Tools

Hosted OAuth: No Installation

Use this endpoint:

https://mcp.rushdb.com/mcp

ChatGPT

Open Settings → Connectors → Add connector.
Enter https://mcp.rushdb.com/mcp.
Sign in with your RushDB account.
Choose the project to expose.

Claude.ai

Open Settings → Integrations → Add integration.
Enter https://mcp.rushdb.com/mcp.
Authorize with your RushDB account.
Choose the project to expose.

caution

Always include /mcp. The root domain does not serve the MCP protocol.

Local MCP: RushDB Cloud API Key

Get an API key at app.rushdb.com, add the relevant configuration, then restart your client.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Cursor

Add .cursor/mcp.json in your project:

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

VS Code: Copilot Agent Mode

Add .vscode/mcp.json:

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

Self-Hosted Engine: Direct Mode

Direct mode connects a local stdio MCP client to a RushDB engine you run. It needs no RushDB Cloud account, API key, dashboard or OAuth. Start the engine with a token:

export RUSHDB_TOKEN="$(openssl rand -hex 32)"
rushdb up --data-dir ./rushdb-data

Then configure the MCP server with the same token:

{
  "mcpServers": {
    "rushdb": {
      "command": "npx",
      "args": ["-y", "@rushdb/mcp-server"],
      "env": {
        "RUSHDB_MODE": "direct",
        "RUSHDB_ENGINE_URL": "http://127.0.0.1:3000",
        "RUSHDB_ENGINE_TOKEN": "your-engine-token"
      }
    }
  }
}

Direct mode offers every tool whose work the engine does:

schema discovery;
record reads and writes, with ordering, projections and aggregations;
relationships, labels and properties;
bulk import and CSV export;
text indexes and keyword search;
external vector indexes, with vector and hybrid search by a queryVector you supply.

The RushDB Cloud tools are not listed, and are refused if called: smartSearch (natural-language search), the relationship-pattern tools, and anything that needs managed embeddings (a text query for vector search, managed indexes).

Direct mode runs over stdio only, on the same machine as the client: the MCP HTTP transport authenticates through RushDB Cloud's OAuth.

Verify the Connection

Ask your assistant:

Call getSchemaMarkdown and show me what labels exist in my RushDB project.

A new project or engine returns an empty schema. That still confirms the connection works.

Mandatory Workflow

RushDB MCP exposes a discovery-first workflow so agents query the schema that exists instead of guessing labels, fields, or operators:

Call getSchemaMarkdown at the start of a session. It returns labels, property names and types, value ranges, and relationships.
Classify the request as a listing, aggregation, traversal, keyword or semantic search, or mutation.
Call getSearchQuerySpec before building queries with dates, metrics, groupBy, relationship traversal, or vector search.
Use the discovered label and property names exactly as returned. Labels are case-sensitive.

Clients with MCP Prompts support can fetch rushdb.queryBuilder at session start. Other clients can call getQueryBuilderPrompt for the same instructions.

Local Configuration Reference

Variable	Mode	Required	Default	Description
`RUSHDB_API_KEY`	Cloud	yes	—	RushDB Cloud API key
`RUSHDB_API_URL`	Cloud	no	`https://api.rushdb.com/api/v1`	A RushDB Cloud API endpoint other than the default
`RUSHDB_MODE`	Direct	yes	—	Set to `direct`
`RUSHDB_ENGINE_URL`	Direct	yes	—	The engine's base URL, e.g. `http://127.0.0.1:3000`
`RUSHDB_ENGINE_TOKEN`	Direct	yes	—	The engine token
`RUSHDB_ENGINE_SCOPE`	Direct	no	—	The tenant, on an engine started with `--multitenant`

Security

Treat RUSHDB_API_KEY and RUSHDB_ENGINE_TOKEN like passwords. Inject them through your MCP client or an OS keychain, and do not commit them to version control.

Essential Tools

Need	Start with
Discover a schema	`getSchemaMarkdown`, `getSchema`
Build a precise query	`getSearchQuerySpec`, `findRecords`
Read or write records	`getRecord`, `createRecord`, `updateRecord`, `setRecord`
Connect records	`findRelationships`, `attachRelation`, `detachRelation`
Work in batches	`bulkCreateRecords`, `bulkDeleteRecords`, `exportRecords`
Keyword search	`createTextIndex`, `listTextIndexes`, `textSearch`
Vector and hybrid search	`findEmbeddingIndexes`, `createEmbeddingIndex`, `vectorSearch`
Natural-language search [Cloud]	`smartSearch`
Review inferred graph structure [Cloud]	`listRelationshipPatterns`, `analyzeRelationshipPatterns`, `approveRelationshipPattern`

Each MCP tool publishes its input schema to the connected client. See All MCP Tools for the complete catalog.

Troubleshooting

Symptom	Check
Hosted connector cannot discover actions	Confirm the URL is `https://mcp.rushdb.com/mcp`, including `/mcp`, then remove and recreate the connector.
Local MCP reports a missing API key	Set `RUSHDB_API_KEY` in the MCP client's `env` block and restart the client.
Direct mode cannot reach the engine	Check `RUSHDB_ENGINE_URL` with `curl $RUSHDB_ENGINE_URL/health`, and that the token matches the engine's.
A tool is missing in direct mode	It needs RushDB Cloud; see the tool catalog.
A query uses the wrong label or property	Call `getSchemaMarkdown` again and use the case-sensitive names it returns.
A structured query fails validation	Call `getSearchQuerySpec` and rebuild the query from the documented operators.

Make the Agent More Effective

Install RushDB Agent Skills after the MCP connection. Skills teach the agent discovery-first querying, graph modeling, faceted search, and persistent memory patterns.

Hosted OAuth: No Installation​

ChatGPT​

Claude.ai​

Local MCP: RushDB Cloud API Key​

Claude Desktop​

Cursor​

VS Code: Copilot Agent Mode​

Self-Hosted Engine: Direct Mode​

Verify the Connection​

Mandatory Workflow​

Local Configuration Reference​

Essential Tools​

Troubleshooting​

Make the Agent More Effective​

Next Steps​