MCP Server

ArcadeDB includes a built-in Model Context Protocol (MCP) server that allows AI assistants and LLM-based tools to interact with the database. The MCP server exposes database operations as tools that AI clients can discover and invoke using the standard MCP protocol.

The MCP server implements the MCP specification (version 2025-03-26) over HTTP using the JSON-RPC 2.0 protocol.

Endpoint

All MCP requests are sent as POST requests to a single endpoint:

POST /api/v1/mcp

Requests must include a valid Authorization header (Basic Auth or Bearer token) and a JSON-RPC 2.0 body.

Configuration

The MCP server is configured via the file config/mcp-config.json in the ArcadeDB server directory. You can also manage the configuration at runtime through the configuration endpoint.

Example mcp-config.json

{
  "enabled": true,
  "allowReads": true,
  "allowInsert": true,
  "allowUpdate": true,
  "allowDelete": false,
  "allowSchemaChange": false,
  "allowAdmin": false,
  "allowedUsers": ["root", "analyst"]
}

Property Default Description

Property	Default	Description
`enabled`	`false`	Enable or disable the MCP server. When disabled, all MCP requests return an error.
`allowReads`	`true`	Allow read-only queries (SELECT, MATCH, etc.).
`allowInsert`	`false`	Allow INSERT operations.
`allowUpdate`	`false`	Allow UPDATE operations.
`allowDelete`	`false`	Allow DELETE operations.
`allowSchemaChange`	`false`	Allow schema modifications (CREATE TYPE, CREATE PROPERTY, CREATE INDEX, etc.).
`allowAdmin`	`false`	Allow administrative operations.
`allowedUsers`	`["*"]`	List of usernames allowed to use the MCP server. Use `"*"` to allow all authenticated users.

enabled

false

Enable or disable the MCP server. When disabled, all MCP requests return an error.

allowReads

true

Allow read-only queries (SELECT, MATCH, etc.).

allowInsert

false

Allow INSERT operations.

allowUpdate

false

Allow UPDATE operations.

allowDelete

false

Allow DELETE operations.

allowSchemaChange

false

Allow schema modifications (CREATE TYPE, CREATE PROPERTY, CREATE INDEX, etc.).

allowAdmin

false

Allow administrative operations.

allowedUsers

["*"]

List of usernames allowed to use the MCP server. Use "*" to allow all authenticated users.

Configuration Endpoint

The MCP configuration can be managed at runtime via the /api/v1/mcp/config endpoint.

Get current configuration:

curl -u root:arcadedb-password \
  http://localhost:2480/api/v1/mcp/config

Update configuration (root user only):

curl -u root:arcadedb-password \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "allowReads": true, "allowInsert": true}' \
  http://localhost:2480/api/v1/mcp/config

MCP Protocol Methods

The MCP server supports the following JSON-RPC 2.0 methods:

Method Description

Method	Description
`initialize`	Handshake that returns the protocol version and server capabilities.
`notifications/initialized`	Client notification acknowledging initialization.
`tools/list`	Returns the list of available tools with their JSON schemas.
`tools/call`	Executes a specific tool by name with the provided arguments.
`ping`	Health check that returns a pong response.

initialize

Handshake that returns the protocol version and server capabilities.

notifications/initialized

Client notification acknowledging initialization.

tools/list

Returns the list of available tools with their JSON schemas.

tools/call

Executes a specific tool by name with the provided arguments.

ping

Health check that returns a pong response.

Example: Initialize

curl -u root:arcadedb-password \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","clientInfo":{"name":"my-client","version":"1.0"}}}' \
  http://localhost:2480/api/v1/mcp

Example: List available tools

curl -u root:arcadedb-password \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  http://localhost:2480/api/v1/mcp

Available Tools

The MCP server exposes five tools that AI clients can invoke.

`list_databases`

Lists all databases accessible to the authenticated user.

Parameters: None

Example:

curl -u root:arcadedb-password \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_databases","arguments":{}}}' \
  http://localhost:2480/api/v1/mcp

Response:

{
  "databases": ["mydb", "analytics"]
}

`get_schema`

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

Parameters:

Parameter Required Description

Parameter	Required	Description
`database`	Yes	The name of the database.

database

Yes

The name of the database.

Example:

curl -u root:arcadedb-password \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_schema","arguments":{"database":"mydb"}}}' \
  http://localhost:2480/api/v1/mcp

Response:

{
  "database": "mydb",
  "types": [
    {
      "name": "Person",
      "category": "vertex",
      "parentTypes": ["V"],
      "properties": [
        {
          "name": "name",
          "type": "STRING",
          "mandatory": true,
          "readonly": false,
          "notNull": true
        }
      ],
      "indexes": [
        {
          "name": "Person[name]",
          "type": "LSM_TREE",
          "properties": ["name"],
          "unique": true
        }
      ]
    }
  ]
}

`query`

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:

Parameter Required Description

Parameter	Required	Description
`database`	Yes	The name of the database.
`language`	Yes	Query language: `sql`, `cypher`, `gremlin`, `graphql`, `mongo`.
`query`	Yes	The query string to execute.
`limit`	No	Maximum number of records to return (default: 1000).

database

Yes

The name of the database.

language

Yes

Query language: sql, cypher, gremlin, graphql, mongo.

query

Yes

The query string to execute.

limit

Maximum number of records to return (default: 1000).

Example:

curl -u root:arcadedb-password \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"query","arguments":{"database":"mydb","language":"sql","query":"SELECT FROM Person LIMIT 10"}}}' \
  http://localhost:2480/api/v1/mcp

Response:

{
  "records": [
    {"@rid": "#1:0", "@type": "Person", "name": "Alice"},
    {"@rid": "#1:1", "@type": "Person", "name": "Bob"}
  ],
  "count": 2
}

`execute_command`

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

Parameters:

Parameter Required Description

Parameter	Required	Description
`database`	Yes	The name of the database.
`language`	Yes	Command language: `sql`, `sqlscript`, `cypher`, `gremlin`, `graphql`, `mongo`.
`command`	Yes	The command string to execute.
`limit`	No	Maximum number of records to return (default: 1000).

database

Yes

The name of the database.

language

Yes

Command language: sql, sqlscript, cypher, gremlin, graphql, mongo.

command

Yes

The command string to execute.

limit

Maximum number of records to return (default: 1000).

Permission mapping:

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

Operation Type Required Permission

Operation Type	Required Permission
INSERT	`allowInsert`
UPDATE	`allowUpdate`
DELETE	`allowDelete`
CREATE TYPE, CREATE PROPERTY, CREATE INDEX, etc.	`allowSchemaChange`
Administrative operations	`allowAdmin`
SELECT, MATCH	`allowReads`

INSERT

allowInsert

UPDATE

allowUpdate

DELETE

allowDelete

CREATE TYPE, CREATE PROPERTY, CREATE INDEX, etc.

allowSchemaChange

Administrative operations

allowAdmin

SELECT, MATCH

allowReads

Example:

curl -u root:arcadedb-password \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"execute_command","arguments":{"database":"mydb","language":"sql","command":"INSERT INTO Person SET name = '\''Charlie'\''"}}}' \
  http://localhost:2480/api/v1/mcp

Response:

{
  "records": [
    {"@rid": "#1:2", "@type": "Person", "name": "Charlie"}
  ],
  "count": 1
}

`server_status`

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

Parameters: None

Example:

curl -u root:arcadedb-password \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"server_status","arguments":{}}}' \
  http://localhost:2480/api/v1/mcp

Response:

{
  "version": "26.5.1",
  "serverName": "ArcadeDB_0",
  "languages": ["sql", "sqlscript", "cypher", "gremlin", "graphql", "mongo"],
  "databases": ["mydb", "analytics"],
  "ha": {
    "clusterName": "arcadedb",
    "leader": "server1",
    "replicas": ["server2", "server3"]
  }
}

The ha field is only included when High Availability is enabled and the user has admin permissions.

Security

The MCP server enforces multiple layers of security:

Authentication — All requests require valid ArcadeDB credentials (Basic Auth or Bearer token).
User authorization — Users can only access databases they are authorized for in the ArcadeDB security configuration.
MCP permissions — The MCP configuration controls which operations are allowed (reads, inserts, updates, deletes, schema changes, admin).
User allow-list — The allowedUsers setting restricts which users can access the MCP server.
Semantic analysis — Queries and commands are analyzed to detect their operation type and enforce the appropriate permission.

Using with AI Clients

The ArcadeDB MCP server is compatible with any MCP-compliant client. To connect an AI assistant to ArcadeDB, configure the client with the MCP endpoint URL and authentication credentials.

Example configuration for an MCP client:

{
  "mcpServers": {
    "arcadedb": {
      "url": "http://localhost:2480/api/v1/mcp",
      "headers": {
        "Authorization": "Basic cm9vdDphcmNhZGVkYi1wYXNzd29yZA=="
      }
    }
  }
}

Once connected, the AI client will automatically discover the available tools via tools/list and can use them to explore databases, query data, and execute commands within the configured permissions.