MCP Server

Entries under principalProfiles assign a tool profile to an individual authenticated principal. The effective profile is the intersection of the server-global profile and the principal entry: a tool is advertised and callable only when both profiles contain it. An entry can therefore only narrow the surface, and never grants a tool that the global profile hides. As with the global profile, an intersection never grants a permission: read, write, schema, administrative, database, user, and origin checks remain independent and mandatory.

A principal is keyed by its user name. An API token can be keyed either canonically as apitoken:<token-name> or by the bare token name, the same two spellings that allowedUsers accepts. When both spellings are present, the canonical apitoken: entry wins.

Profile names are case-insensitive on input and are serialized in lowercase. A tools/call for a tool excluded by the intersection is rejected with an error naming both profiles, so a client cannot bypass the filtered tools/list by invoking the tool directly. The initialize instructions follow the effective profile: they describe the rag surface when the intersection matches the rag profile, and otherwise describe the general or the restricted surface.

The runtime configuration endpoint merges principalProfiles by principal name. Set one principal to null to remove that entry, or set the top-level principalProfiles value to null to clear all per-principal profiles:

Lists all databases accessible to the authenticated user.

Parameters: None

Example:

Response:

Retrieves the full schema of a database, including all types (vertex, edge, document), their properties, and indexes.

Parameters:

Example:

Response:

Executes a read-only (idempotent) query against a database. The server performs semantic analysis to ensure the query does not modify data. If a write operation is detected, the request is rejected.

Parameters:

Example:

Response:

Executes a non-idempotent command (write operations, schema changes, administrative commands). The server checks the command against the MCP configuration permissions before execution.

Parameters:

Permission mapping:

The server analyzes the command semantics and checks against the MCP configuration:

Example:

Response:

Returns server metadata including version, available query languages, and accessible databases.

Parameters: None

Example:

Response:

Returns the first records in storage order from selected database types so an agent can inspect actual property-value shapes before constructing a query. This is not a random or representative sample.

Parameters:

Example:

Response:

availableTypes always reports the number of eligible vertex and document types in the database, even when types is supplied. When types is omitted, truncated indicates that more than 20 eligible types exist. The generated queries are checked as read-only, and serialized records do not include vertex edge collections.

Searches a dense LSM_VECTOR or sparse LSM_SPARSE_VECTOR index with a pre-computed query vector. ArcadeDB does not generate embeddings; the caller must supply the vector produced by its embedding model.

Parameters:

The optional filter is evaluated against each expanded neighbor row. Record properties are flattened into that row, and @rid, @type, record, plus distance for dense results or score for sparse results are also available.

Dense-vector example:

Response:

Dense results expose only distance, where lower is better. Sparse results expose only score, where higher is better. The response-level scoring value also records the active dense similarity function or sparse scoring modifier.

Without a filter, candidateLimit equals k. With a filter, ArcadeDB examines up to min(k * 8, 8000) vector candidates before applying the predicate. truncated is true when the returned result window is full (count equals k), so more matches may exist. When it is false, fewer than k matches survived the current candidate window. For a filtered search, that does not prove that no matching vectors exist beyond candidateLimit; increasing k also expands the candidate window until the 8,000-candidate ceiling is reached.

Searches a full-text index and returns the matching records ranked by relevance score. Requires read permission.

Address the index either by indexName, or by typeName with optional properties. When both forms are supplied, indexName wins.

Parameters:

Query syntax:

Example:

Response:

The similarity field reports whether scores are BM25 or legacy CLASSIC coordination counts. The limit is pushed down per bucket, so the search merges at most bucket count * limit entries rather than every match in the index. Because of that push-down, a record deleted concurrently between the index scan and the record read is skipped without being back-filled, so a search can legitimately return fewer than limit results.

Retrieves records by fusing up to three retrieval legs into a single ranked list: a vector search, an optional full-text search, and an optional graph expansion. Requires read permission. As with vector_search, ArcadeDB does not generate embeddings.

The graph expansion is seeded from the records the other legs found and walks outward from them, so a neighbor of a strong match can itself rank. Expanded records carry the number of hops from their seed and the path back to it.

Parameters:

Supplying only one of fulltextIndexName and fulltextQuery is rejected: half a leg is always a mistake, and ignoring it silently would return a plausible result set that quietly dropped what the caller asked for.

The expand object:

An unknown edge type is rejected, listing the available ones. Traversing a name that matches nothing would otherwise return an empty neighborhood without an error, silently degrading the search to plain two-way fusion. maxDepth above 3 is rejected rather than clamped, and the cap is enforced server-side regardless of the value sent. Graph expansion requires a vertex type; requesting it against a document type is rejected.

Fusion strategies:

RRF (Reciprocal Rank Fusion) is rank-only and ignores per-row scores. DBSF and LINEAR normalize per-source scores and therefore require a numeric score on every row of every source.

The graph expansion leg ranks by traversal order and carries no score, so DBSF and LINEAR cannot be combined with expand and that combination is rejected. Both remain available for vector plus full-text fusion.

Weights:

weights accepts vector, fulltext, and expand. The first two default to 1.0 and expand defaults to 0.5, because under RRF a rank-one expanded record would otherwise score exactly what the nearest neighbor scores, letting an arbitrary one-hop neighbor tie the best semantic match.

A weight naming a leg the request does not ask for is rejected, as is an unknown key, a negative value, and a non-numeric value. A weight of 0.0 is accepted: it keeps a leg’s records in the candidate set and in each result’s sources while contributing nothing to the ranking.

Example:

Response:

sources names the legs that contributed to each result, so a fused score can be interpreted rather than taken on faith: it distinguishes a top semantic match from a record that arrived two hops from something relevant. depth and path appear only on results the expansion leg contributed, and path starts at the seed and ends at the result itself.

fused reports whether fusion actually ran. Fusion requires at least two sources, so a request naming neither fulltextQuery nor expand cannot be fused: that response sets fused to false and its results carry the vector leg’s native distance or score instead of fusedScore. The full-text index name and similarity are reported under legs whenever that leg ran, including when it matched nothing.

The response carries several independent budgets. Top-level truncated means the result window filled (count equals k), so raising k may surface more. legs.expand.truncated means the traversal hit its fan-out cap, so the neighborhood was only partly explored; narrowing edgeTypes or maxDepth gives a more complete picture of the part that matters. legs.expand.seedsTruncated means the retrieval legs produced more candidate seeds than the traversal budget accepts, so expansion started from a subset.

For pure two-way fusion without graph expansion, vector.fuse remains available through the query tool.

Creates or updates a single vertex addressed by a match key, without duplicating it. Requires both insert and update permission, because a merge resolves to a create or an update depending on what already exists.

The vertex is matched, or created, by the matchKeys property/value pairs, and then any setProperties are written. Repeated calls with identical matchKeys resolve to the same vertex. Values are bound as parameters, so they are safe to pass verbatim; identifiers are quoted.

Parameters:

Example:

Creates or updates a single directed edge between two vertices, without duplicating it. Requires both insert and update permission.

Each endpoint is matched, or created, by its own match keys; then the edge of type relType between them is matched or created, and any relProperties are written. Repeated calls between the same resolved endpoints with the same relType resolve to the same edge.

Parameters:

Example:

The edge properties are written in a trailing assignment, so the edge is keyed by its endpoints and type alone and is never duplicated by a change to its properties.

Starts the query profiler, which records every query with its execution time and plan. Requires admin permission.

The profiler auto-stops after timeoutSeconds, so a session left running does not profile indefinitely. Use profiler_stop to end it early and collect the results, or profiler_status to check progress while it runs.

Parameters:

Example:

Response:

Only one profiling session runs at a time. Starting the profiler while it is already recording does not restart it, extend it, or raise an error: the call returns status: "already_recording" and leaves the session untouched, so an agent retrying a start cannot silently discard the data collected so far.

Stops the query profiler and returns the data captured during the session. Requires admin permission. Takes no parameters.

Results are aggregated per query and include execution counts, timing (minimum, maximum, average, and p99), and execution-plan step costs. They are also written to disk, so a session can be retrieved after the fact.

Example:

If the profiler was not recording, the call returns status: "not_recording" rather than an error, so stopping an already-stopped profiler is safe to retry.

Reports whether the profiler is recording and returns the current or most recent results. Requires admin permission. Takes no parameters.

Where profiler_stop ends the session, this reads it without disturbing it, so it is the safe call for an agent that wants to check progress mid-session. Alongside the captured queries and their timing statistics, the response carries server metric snapshots taken during the session.

Example:

Returns the server-level configuration settings with their current values, defaults, and descriptions. Takes no parameters.

Only settings whose scope is the server are returned; database-scoped settings are excluded.

Example:

Response:

overridden is true when the setting has been given an explicit value rather than inheriting its default.

Updates a server configuration setting at runtime. Requires admin permission.

Changes take effect immediately. Whether they survive a restart depends on the individual setting, so treat this as a runtime adjustment rather than a way to persist configuration. Call get_server_settings first to see the available keys and their current values.

Parameters:

An unknown key is rejected by name rather than silently accepted, so a typo cannot masquerade as a successful update.

Example:

Response:

The response reports the replaced value so a change can be reverted without a separate read.

A prompt is a script that names tools by name, so it is offered only when the caller can actually run it. Each prompt is listed, and rendered, only when both conditions hold:

Neither prompt is therefore available under the admin profile, which contains none of the retrieval or upsert tools. Under rag and all, graphrag_query is available whenever reads are permitted, and build_knowledge_graph additionally requires the two write permissions, which are false by default.

These checks are evaluated against the server-global permission flags, because no database is resolved while a prompt is rendered. Per-database overrides still apply to every tool call the model subsequently makes.

Like resources/list, prompts/list is a discovery call most clients issue unprompted at session start, so a caller entitled to no prompts receives an empty prompts array rather than an error. Availability is then re-checked by prompts/get, for the same reason tools/call re-checks the profile after tools/list has already filtered: an unavailable prompt is refused with error -32600 even when it is requested by name. An unknown prompt name, or a missing argument, returns -32602.

Example: list prompts

Response:

Example: render a prompt

Response:

Each argument is substituted inside a delimiter block that marks it as data rather than procedure. Because the value is substituted verbatim, a value that itself carries the closing tag would end that block early and have the remaining text read as instructions. The server therefore suffixes both delimiters with an unpredictable token whenever the value contains such a tag, which moves the boundary instead of altering the value. An ordinary argument carries no such tag and renders against the constant delimiters shown above.

The HTTP endpoint follows the Streamable HTTP transport rules of MCP 2025-03-26.

HTTP methods. JSON-RPC is carried over POST only. The server does not offer a Server-Sent Events stream, so any other method (including GET) is answered with 405 Method Not Allowed and an Allow: POST header.

Requests and notifications. A request must carry an id that is a string or an integer; null, fractional and structured ids are rejected with JSON-RPC error -32600. A notification is a message with a method and no id: the server never answers one, and a POST that carried only notifications returns 202 Accepted with an empty body.

Batches. A top-level JSON array is accepted on both the HTTP and the stdio transport. Every element is dispatched independently and only the elements that are requests contribute a response, so a batch of notifications alone yields 202 Accepted with no body and a mixed batch yields an array holding just the request responses.

Origin validation. To mitigate DNS rebinding, a request carrying an Origin header is accepted only when the origin is a loopback address, matches the host the request was addressed to, or is listed in allowedOrigins. Anything else is rejected with 403. A request with no Origin is accepted, because non-browser MCP clients do not send one and the header is attached by the browser precisely in the case the check is meant to catch. Setting allowedOrigins to ["*"] accepts any origin and disables this protection: use it only when the endpoint is fronted by a proxy that performs its own origin control.

Clients that launch their MCP servers as a child process, rather than connecting to one over the network, speak JSON-RPC 2.0 over standard input and output with one message per line. The distribution ships that transport as bin/mcp-stdio.sh, which starts an ArcadeDB server and serves MCP on its stdin and stdout.

The root password is mandatory: the process authenticates as root and exits with an error if arcadedb.server.rootPassword is unset. Because the client owns stdout, the server redirects its own logging to stderr so that log lines cannot corrupt the JSON-RPC stream.

Stdio mode enables the MCP server for the lifetime of the process regardless of the enabled flag, since the client started it precisely to speak MCP. Everything else in config/mcp-config.json still applies unchanged: permissions, tool profile, per-database overrides, and the allowedUsers list, which must admit root. Origin validation does not apply, because there is no HTTP request to carry an Origin header.

A line holding a top-level JSON array is dispatched as a batch, exactly as over HTTP. A message that produces no response, such as a notification or a batch of them, is answered with no output line at all.