RushDB MCP Server
OfficialServer Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| RUSHDB_API_KEY | Yes | Required for local (API key) mode. Get your API key at https://app.rushdb.com | |
| RUSHDB_API_URL | No | Optional API base URL. Override for self-hosted or staging environments. | https://api.rushdb.com/api/v1 |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
You are a data assistant for RushDB (property-centric graph database, LMPG model). Translate natural-language requests into MCP tool calls. Return concise, factual answers. Never guess labels, field names, or field values — always discover them first.
LIMITS • limit max = 1000. Cap at 1000 if the user requests more. • NEVER include limit with select (sum/avg/min/max/count/collect/timeBucket) — it restricts the record scan and produces wrong results. • "How many X?" → read total directly from the findRecords response ({ data:[...], total:N }). Do NOT use a $count select for simple counts. • For self-group and dimensional groupBy: omit limit (unless asking for "top N"). • labels contains root records only. Put related labels inside where traversal blocks, not beside the root in labels. • groupBy never accepts alias-only values such as "$record" or "$related"; use "$record.name" / "$related.status" or a select key. • Default to $contains on the label's display property resolved from schema discovery (often name or title — never assume one exists) for any user-typed named reference, on root and related labels alike; use exact equality only for IDs or explicit exact-match requests, and confirm canonical values via discovery rather than guessing. • Related-count rankings keep the requested parent/entity as root: most/more/highest → order count desc; least/less/fewer/fewest/lowest → order count asc.
TOOL MAP (exact names — never invent alternatives)
getSchemaMarkdown → STEP 0: call once at session start. Returns all labels, properties (with recordsCount), and relationships.
getSearchQuerySpec → call before any findRecords with dates, aggregation, groupBy, relationships, or vectors. Returns the full operator + syntax reference.
getSchema → same as getSchemaMarkdown but structured JSON; use only when you need property id values for propertyValues.
findLabels → list labels after applying optional record-scoped filters. Skip if getSchemaMarkdown already ran this session.
findProperties → discover field names, types, and recordsCount after applying optional record-scoped filters. Call before any filtered query if fields are unknown.
searchValues → find where a user-typed value is stored (label, property, exact spelling, count) across every property; use before filtering on a name/code/phrase; match:"similar" for near spellings.
getSchemaSummary → every label's properties with distinct counts, ranges, and the values of small fields in one read; shows how values are coded ("+" for positive).
resolveNames → the real label/property behind a name not in the schema ("patients" → Patient). Use instead of guessing.
getJoinCandidates → how labels reference each other (property names + exact value containment, with evidence) when relationships are missing.
findRecords → primary read/query/list/search tool; execute SearchQuery (the only place select + groupBy are valid for metrics). Response: { data:[...], total:N }.
findRelationships → inspect relationships; where filters relationship type/properties, source/target filter endpoint records. No select/groupBy.
exportRecords → export matching records to CSV only when the user explicitly asks for export/download/CSV. Do not use it for normal read/list/search; use findRecords.
bulkDeleteRecords → destructive batch delete (accepts same where/labels as findRecords); confirm first, preview with findRecords.
propertyValues → enumerate distinct values for a propertyId (id comes from findProperties or getSchema JSON).
getRecord / getRecordsByIds / findOneRecord / findUniqRecord — single-record lookups.
createRecord / updateRecord / setRecord / deleteRecord / deleteRecordById — single-record mutations.
bulkCreateRecords — batch insert.
attachRelation / updateRelation / detachRelation — relationship mutations (updateRelation changes properties on existing relationships: set / unset; types: { name: 'datetime' } stores an ISO string as a datetime).
listRelationshipPatterns / analyzeRelationshipPatterns — inspect or generate schema-derived relationship suggestions.
approveRelationshipPattern / ignoreRelationshipPattern / deleteRelationshipPattern — manage suggestions; confirm deletion, especially when deleteExisting is true.
findPropertyById / deleteProperty — property management.
helpAddToClient — setup instructions for adding this server to an MCP client.
getQueryBuilderPrompt — returns this system prompt (fallback for clients without Prompts API).
MANDATORY WORKFLOW
STEP 0 — SCHEMA (always first) Call getSchemaMarkdown before any other tool on the very first tool call of the conversation. Do not call findLabels, findRecords, or findProperties first. It returns: all label names (case-sensitive), all field names + types, value ranges, and the full relationship map — in one call. Use its output directly. Do not re-call findLabels/findProperties for labels already in the schema.
STEP 1 — INTENT (classify before acting) • METRICS/ANALYTICS (count/total/sum/avg/breakdown/per X/top N by metric/distribution/grouped) → plan findRecords WITH select + groupBy. NEVER fetch raw records to count or sum them manually. • LISTING → findRecords with where + limit + orderBy. • SINGLE RECORD → getRecord (by ID) / findOneRecord (first match) / findUniqRecord (exactly one). • RELATIONSHIPS → findRelationships to inspect or traverse connections. • MUTATION → confirm and preview before any destructive operation.
STEP 2 — QUERY SPEC (when building a non-trivial query) Before calling findRecords with dates, aggregation, groupBy, relationship traversal, or vector search: call getSearchQuerySpec. It returns the complete operator reference, all WHERE syntax rules, select/groupBy modes, late-ordering rules, the validation checklist, and annotated examples. Do not guess syntax — the spec is the source of truth.
STEP 3 — BUILD Use only label and field names from discovery. Labels are case-sensitive. For "top N records by scalar field on the same label", use orderBy + limit, not select. For "which parent has most/more/least/less/fewer/fewest related children", root the parent label, traverse child in where with $alias, count the child alias, group by the parent's display property from the schema, and order desc for most/more or asc for least/less/fewer. Do not let a related/filter label become root for related-count rankings when a valid parent→related traversal path exists. Exception — condition verbs ("won", "wrote", "approved", …): a traversal satisfies the verb only if the relationship type expresses it. When the condition exists only as a scalar reference property on the related label (author_id / winner_* / approvedBy style — discover with findProperties), root on the label that OWNS that property and groupBy it instead; where cannot correlate two records (no $record./$alias. values, no $ref — $ref is select-only). Keep ambiguous named-reference filters loose with $contains on the display property discovery shows for that label. Resource-local where rule: - findRecords.where filters Records. - findRelationships.where filters relationship edges; use source/target for endpoint Records. - findLabels.where and findProperties.where filter Records before returning labels/properties. The traversal key in where IS a label copied exactly as spelled in the schema (labels are case-sensitive and may be any case — never change a label's case). Alias is $alias only. Use $relation on a related-label block to constrain edge type/direction (for example: POST: { $relation: { type: 'AUTHORED', direction: 'in' } }). Copy type verbatim from a schema Relationships row or omit it (untyped traversal is valid) — never write RUSHDB__RELATION__DEFAULT unless a schema row shows that exact type. For multihop over one pattern (hierarchies, "within N degrees") add hops inside $relation (for example: EMPLOYEE: { $relation: { type: 'REPORTS_TO', direction: 'out', hops: { max: 4 } } }). For rings/loops/circular flows use the record-level $cycle operator whose value is the traversal spec itself, hops mandatory with min 2+ (for example: where: { $cycle: { type: 'TRANSFERRED_TO', direction: 'out', hops: { min: 2, max: 6 } } }). Never wrap $cycle in a named block and never nest $relation inside it. Operators $label / $direction / $as / $of / $through / $hops do not exist — never use them; multihop depth is always $relation.hops.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {} |
| prompts | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| getSchemaMarkdownA | STEP 0 — call this ONCE at the start of every conversation before constructing any query. Returns the complete graph schema as compact Markdown: all labels with record counts, all properties per label with their type and value ranges (min/max for numbers/datetimes, sample values for strings/booleans; array properties render as type[]), and all cross-label relationships with direction and edge property summaries. The Properties table includes a "Semantic Search" column: properties with an embedding index show |
| getSchemaA | Returns the same graph schema as getSchemaMarkdown but as structured JSON. Each item has: label (string), count (number), properties (array with id, name, type, optional isArray, recordsCount (number of records that carry this property), min/max for numbers/datetimes, values[] for strings/booleans, and an optional vectorIndexes array), and relationships (array with label, type, direction: in|out, count, and optional edge properties). vectorIndexes is non-empty when one or more embedding indexes exist for that property; each entry has: id, sourceType (managed|external), similarityFunction (cosine|euclidean), dimensions (number), status (pending|indexing|ready|error), modelKey. A non-empty vectorIndexes means the property is queryable with aiSemanticSearch. Use this when you need property |
| findLabelsA | List or filter available record types (labels) and their counts. IMPORTANT: getSchemaMarkdown already returns ALL label names in STEP 0 — do NOT call findLabels as a substitute for it. Only call findLabels when you need label counts after applying record-scoped predicates, or getSchemaMarkdown was not called yet. Call with no arguments to list all labels. |
| createRecordA | Create a new record. Use the exact label casing returned by findLabels. Set mergeStrategy + mergeBy in options to enable upsert semantics (merge existing vs. replace). |
| updateRecordA | Partially update a record — only fields present in data are changed; all other existing fields are preserved. Use setRecord instead if you want to replace all fields. Requires recordId: retrieve it first with findRecords or getRecord if not already known. |
| deleteRecordA | Delete a single record by ID. Irreversible. Always confirm with the user before calling. Use findRecords to preview the record first. |
| findRecordsA | Primary read/query/list/search tool for records. Use findRecords to find records, search records, list records, retrieve matching records, filter records, or answer questions from data. Use this instead of exportRecords unless the user explicitly asks for CSV/export/download. Search records with a structured SearchQuery. BEFORE building any query with dates, metrics, groupBy, relationship traversal, or vector search — call getSearchQuerySpec to load the complete syntax reference. INTENT: metrics/analytics request (count/total/sum/avg/breakdown/top N by metric) → MUST include select + groupBy. NEVER fetch raw records to count/sum manually. RESPONSE: { data:[...records], total:N } — for simple "how many" read total directly; no count select needed. HARD RULES: (1) NEVER set limit when select is present — restricts the record scan and produces mathematically wrong results. Omit limit for all metrics queries. (2) labels contains root records only; put related labels inside where traversal blocks with $alias when referenced. (3) groupBy never accepts alias-only values like "$record"; use "$record.name" or a select key. (4) Ambiguous/incomplete named references should use $contains on a display property confirmed via schema discovery, not exact equality. (5) Related-count rankings keep the requested parent/entity as root; count the related alias and order desc for most/more or asc for least/less/fewer. |
| getRecordA | Fetch a single record by its ID. Use when you already have the ID from a previous findRecords or findOneRecord call. |
| getRecordsByIdsA | Fetch multiple records by their IDs in one call. Use after collecting IDs from a findRecords query. |
| attachRelationA | Create a directed or bidirectional relationship between records. sourceId and targetId/targetIds must already exist — use findRecords to resolve records by name/attribute first. |
| updateRelationA | Change the properties of existing relationships of one type between a record and target records: |
| detachRelationA | Remove the relationships between a record and target records. Without relationType it removes relationships of every type; with direction "bidirectional" it removes them both ways. Not available inside a transaction. Use findRelationships to inspect existing relationships and confirm the correct type/direction before detaching. |
| findRelationshipsA | Discover and traverse relationships between records. Use this tool in two scenarios: (1) Multi-hop path discovery — fetch a sample record ID, then call findRelationships with source.where or target.where containing that ID to reveal adjacent labels; repeat to trace the full path before building a nested findRecords where clause. (2) Edge filtering — where applies to relationship type/properties; use source/target for endpoint record predicates. Does NOT support select or groupBy — use findRecords for metrics/analytics across related labels. |
| listRelationshipPatternsA | List inferred relationship patterns for the current project. Returns suggestions and their lifecycle status, current schema relationship summaries, and the latest analysis status. Use this before approving, ignoring, or deleting a relationship pattern. |
| analyzeRelationshipPatternsA | Queue schema analysis to generate relationship pattern suggestions for the current project. This may invoke the configured LLM. Poll listRelationshipPatterns to inspect completion status and suggestions. |
| approveRelationshipPatternA | Approve and apply a suggested relationship pattern. Call listRelationshipPatterns first so the user can review the inferred source, target, direction, type, mode, and confidence. |
| ignoreRelationshipPatternA | Ignore a suggested relationship pattern without applying it. Call listRelationshipPatterns first so the user can review the inferred pattern. |
| deleteRelationshipPatternA | Delete a saved relationship pattern. Irreversible. Confirm with the user before calling. When deleteExisting is true, relationships previously materialized by this pattern are also removed. |
| bulkCreateRecordsA | Insert multiple records of the same label in one call. Set mergeStrategy ("append" to keep existing unspecified fields, "rewrite" to replace) and mergeBy (fields to match on) in options to enable upsert semantics. Use the exact label casing returned by findLabels. |
| bulkDeleteRecordsA | Delete all records matching a query. IRREVERSIBLE and potentially high-impact. REQUIRED: always call findRecords with the same labels+where first to show the user a preview, then ask for explicit confirmation before calling this tool. |
| exportRecordsA | Export matching records as a CSV file only when the user explicitly asks to export/download CSV. For normal reading, answering, listing, searching, or inspecting records, use findRecords instead. Accepts the same labels/where/orderBy filters as findRecords. Call findProperties first to know available field names if constructing a where filter. |
| helpAddToClientA | Help the user add the RushDB MCP server to their MCP client |
| getQueryBuilderPromptA | Return the RushDB system prompt. Use this if your MCP client does not support the Prompts API. |
| getSearchQuerySpecA | Returns the complete RushDB SearchQuery specification as a focused reference document. Covers: all WHERE operators (string/number/boolean/datetime component objects/vector/$exists/$type), relationship traversal syntax ($alias/$relation with variable-length hops/$cycle ring detection/$id), logical grouping ($and/$or/$not/$nor/$xor), all select functions ($sum/$avg/$min/$max/$count/$collect/$timeBucket), both groupBy modes (dimensional + self-group), late-ordering rules, root-label vs related-label traversal rules, COLLECT nesting, limit rules by query mode, multi-hop path discovery, enum normalization, validation checklist, and annotated query examples. CALL THIS before building any findRecords query that involves dates, metrics, groupBy, relationship traversal, or vector search. Do not guess operator syntax — use this spec as the source of truth. |
| setRecordA | Replace ALL fields of a record with the provided data object — any existing fields not in data are deleted. Use updateRecord instead for partial/merge updates that preserve unspecified fields. |
| findOneRecordA | Return the first record matching the query — useful for entity resolution probes. Call with where: { : { $contains: "..." } } and a small limit to resolve a named entity to its ID before using it in a relationship filter. Prefer this over findRecords when you need exactly one representative match rather than a full list. |
| findUniqRecordA | Return the single record that uniquely matches the query — throws if zero or more than one record matches. Use for unique-key lookups (email, code, slug) where exactly one result is expected. Use findOneRecord instead when you only want the first match and duplicates are acceptable. |
| deleteRecordByIdA | Delete a single record by ID. Irreversible. Always confirm with the user before calling. Use getRecord to preview the record if needed. |
| propertyValuesA | Get statistics or distinct values for a specific property, identified by the |
| searchValuesA | Find where a value from the question is stored: searches the exact value dictionaries of every property at once and returns { matches: [{ label, property, value, count }], total }. Use it before filtering on a name, code, or phrase the user typed, instead of guessing the field or spelling. match: contains (default), prefix, exact, or similar (near spellings, for typos and punctuation: "spiderman" finds "Spider-Man"). No match means no stored value contains the text: check the spelling, try a shorter word, or read a field's values with propertyValues. |
| getSchemaSummaryA | Every label with its properties in one live read (never cached): per property its type, record count, exact distinct count, min/max for numbers and dates, and the full value list when it holds few (fewValues, default 10); per label its relationships. Use it to learn how values are coded (e.g. KCT holds "-" and "+") without one call per field. |
| resolveNamesA | Find the real label or property behind a name you are unsure of (case, separators and plural endings ignored, then ranked by spelling): "patients" → Patient, "patients.birthdate" → Patient.Birthday. Call it instead of guessing when a label or field name is not in the schema. Returns [{ label, property?, score }]. |
| getJoinCandidatesA | Which properties reference records of another label (or the same one), found from property names and exact value containment, with evidence (matched values and records, coverage). RushDB Cloud only. Use it to learn how labels connect when the data has no relationships yet, e.g. before joining in a query. Returns [{ source, target, reasons, relationshipType, confidence, evidence, rationale }]. |
| findPropertiesA | Discover the field names, types, and IDs available on a record label. Always call this before using field names in any query — never guess or invent field names. Filter by label using labels: ["LABEL_NAME"]. |
| findPropertyByIdA | Fetch the metadata (name, type, label, recordsCount) of a single property by its ID. Use when you already have a propertyId and need to re-confirm its type or cardinality before calling propertyValues. |
| deletePropertyA | Permanently delete a property and all its values from every record that has it. Irreversible. Confirm with the user before calling. |
| findEmbeddingIndexesA | List all embedding index policies configured for the current project. Each index entry contains: id, label, propertyName, modelKey, dimensions, enabled, status (pending|indexing|ready|error), createdAt, updatedAt. Call this before creating a new index to check if one already exists for the same label+propertyName. |
| createEmbeddingIndexA | Create a new embedding index policy for a string property. For managed indexes (default), RushDB asynchronously embeds every existing value and keeps new values embedded on write. For external indexes (sourceType: "external"), the client supplies vectors via upsertEmbeddingVectors. Once the index status becomes "ready" (check with getEmbeddingIndexStats), use vectorSearch to query. |
| upsertEmbeddingVectorsA | Write pre-computed embedding vectors to an external vector index for a set of records. Only valid for indexes with sourceType "external". Each vector must contain exactly as many dimensions as the index was created with. After upserting, call getEmbeddingIndexStats to check if all records are indexed (status becomes "ready"). |
| deleteEmbeddingIndexA | Delete an embedding index policy by its ID and strip all stored embedding vectors for that index. Irreversible. Confirm with the user before calling. Use findEmbeddingIndexes to get the indexId. |
| getEmbeddingIndexStatsA | Return indexing statistics for an embedding index: totalRecords and indexedRecords. Use this to monitor backfill progress after creating an index — when indexedRecords === totalRecords the index is fully ready. |
| vectorSearchA | Perform direct vector similarity search over records whose |
| listTextIndexesA | List the project's keyword (BM25) text indexes: name, label, property ("*" = every string of the record), consistency and status. |
| createTextIndexA | Declare a keyword (BM25) text index over one property of a label, or every string of it (property "*"). It is built online; once its status is "ready" (listTextIndexes), search it with textSearch or as the |
| deleteTextIndexA | Drop a text index by name. Irreversible. Confirm with the user before calling. |
| textSearchA | Keyword (BM25) search over a text index: records matching |
| semanticSearchA | Deprecated alias for vectorSearch. Performs direct vector similarity search over records whose |
| smartSearchA | Convert a natural-language question into one read-only SQL statement over the project schema, run it, and return the results plus the statement, a short title for it and any warnings. Rows that select a record come back as records; aggregates such as counts and totals come back as plain rows. Use this for user-facing questions such as "Who are piloting Falcon?" or "How many orders per city?". For direct vector similarity over an embedding index, use vectorSearch instead. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| rushdb.queryBuilder | RushDB Query Builder system prompt: guides the model to discover labels/properties first and construct validated SearchQuery objects before calling find-related tools. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 48 tools
Many tools overlap heavily: six-plus schema-discovery tools (getSchemaMarkdown, getSchema, getSchemaSummary, findLabels, findProperties, findPropertyById), duplicate deletes (deleteRecord vs deleteRecordById), near-duplicate reads (findRecords/getRecord/getRecordsByIds/findOneRecord/findUniqRecord), overwrite vs partial semantics (setRecord vs updateRecord), and an explicitly deprecated alias (semanticSearch for vectorSearch). The descriptions do try to disambiguate, but an agent must read paragraphs of guidance each time to pick correctly, and redundancy remains.
All names use camelCase and nearly all follow a verb_noun pattern (createRecord, findRelationships, deleteEmbeddingIndex, bulkCreateRecords). A handful (propertyValues, searchValues, resolveNames, smartSearch, helpAddToClient) are noun-first rather than verb-first, which is a minor deviation but still readable and predictable.
48 tools is well past the point where a set stays legible; the schema-discovery and search areas alone account for nearly twenty overlapping entries. Consolidating getSchemaMarkdown/getSchema/getSchemaSummary, deleteRecord/deleteRecordById, and semanticSearch into vectorSearch would cut the surface substantially without losing capability.
Record CRUD, bulk operations, relationship attach/detach/update, schema introspection, pattern inference, embedding and text index lifecycle, vector/keyword/NL search, and CSV export are all present, which is strong coverage for a graph database service. The main gaps are around transactions (tools note they are unavailable inside one) and lack of explicit transaction/session management tools.