ArcadeDB for AI Agents: MCP Server and Agent Memory

Why put the agent next to the graph

An agent that only has a vector store can find passages that look like the question. It cannot tell that a fact was superseded, that two names are one person, or which project a preference belongs to. Those are relationships, and they are what a graph stores. ArcadeDB keeps the graph, the documents, the vectors and the full-text index in one engine, so one MCP connection gives an agent all of them, against one consistent copy of the data.

That combination is the core of GraphRAG: retrieve by similarity, then follow edges to the context similarity alone would miss. If you are building the graph itself from documents, the knowledge graphs page covers modelling and extraction. This page is the practical part: how to switch the MCP server on, what it exposes, and how to wire it into your client.

Enable the MCP server

The MCP server is the mcp module of the ArcadeDB repository. The standard distribution and the Docker image include it and register it automatically, so there is no plugin to add. It is disabled by default. Once enabled, it answers JSON-RPC 2.0 over HTTP at POST /api/v1/mcp (MCP specification 2025-03-26) and authenticates every request with your ArcadeDB credentials, Basic auth or a Bearer API token.

docker run --rm -p 2480:2480 \
  -e JAVA_OPTS="-Darcadedb.server.rootPassword=playwithdata" \
  arcadedata/arcadedb:26.10.1

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

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

You can do the same from Studio: open the Server panel, then the MCP tab, where you can enable the server, choose an API token, set permissions and copy a ready-made client configuration. For a file-based setup, edit config/mcp-config.json in the server directory.

Permissions

Each operation type has its own flag. The server decides which flag applies by parsing the statement, not by matching keywords, so a cleverly worded query cannot slip a write past a read-only setting.

For a retrieval agent, the rag profile hides everything except schema, query, search and the two upsert tools. Profiles only filter the tool list; the permission flags still apply on top.

What the agent can call

As of ArcadeDB 26.10.1 the server registers the tools below. Call tools/list for the authoritative list and input schemas of the version you run.

Resources. Each database publishes its schema as arcadedb://{database}/schema, so a client that reads resources gets the schema at session start without spending a tool call.

Prompts. Two guided templates: graphrag_query answers a question with the retrieval tools and cites the @rid of every record it used, and build_knowledge_graph extracts entities and relationships from text and writes them with the upsert tools. A prompt is only offered when the caller's profile and permissions allow every tool it names.

Connect your client

Every client needs the endpoint URL and an Authorization header. Use a Bearer API token created in Studio (Security panel, Add API Token), or Basic auth, which is Basic followed by the base64 of user:password. The examples use Basic auth for root:playwithdata; replace it with your own value, and prefer a token scoped to the databases the agent needs.

Claude Desktop

Claude Desktop launches local servers as processes, so it reaches the HTTP endpoint through the mcp-remote bridge (needs Node.js for npx). Add this to claude_desktop_config.json:

{
  "mcpServers": {
    "arcadedb": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:2480/api/v1/mcp",
        "--header",
        "Authorization: Basic cm9vdDpwbGF5d2l0aGRhdGE="
      ]
    }
  }
}

Claude Code

Claude Code speaks Streamable HTTP directly. Add the server from the command line:

claude mcp add --transport http arcadedb http://localhost:2480/api/v1/mcp \
  --header "Authorization: Basic cm9vdDpwbGF5d2l0aGRhdGE="

or commit it to a project's .mcp.json:

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

Cursor

Put a remote server entry in .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

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

Stdio, for clients that start their own server

If you run ArcadeDB from the distribution rather than Docker, bin/mcp-stdio.sh starts a server and speaks MCP over standard input and output. It always authenticates as root, so the root password is required, and it ignores the enabled flag while every other setting in mcp-config.json still applies.

{
  "mcpServers": {
    "arcadedb": {
      "command": "/opt/arcadedb/bin/mcp-stdio.sh",
      "env": {
        "ARCADEDB_SETTINGS": "-Darcadedb.server.rootPassword=playwithdata"
      }
    }
  }
}

Prefer to run Google's MCP server in front of several databases? ArcadeDB is also a source in MCP Toolbox for Databases.

GraphRAG in one command

The graph-rag demo in the arcadedb-usecases repository builds a small GraphRAG dataset (text chunks with embeddings, the people, concepts and organizations they mention, and the edges between them) and runs five retrieval patterns: hybrid vector plus graph, multi-hop entity bridging, latest chunk per document, composite scoring, and an agentic multi-step flow. You need Docker, curl and jq.

git clone https://github.com/ArcadeData/arcadedb-usecases.git && cd arcadedb-usecases/graph-rag && docker compose up -d && ./setup.sh && ./queries/queries.sh

Then ask Claude about it

The demo's root password is arcadedb. Enable MCP on it and register it with Claude Code:

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

claude mcp add --transport http arcadedb-graphrag http://localhost:2480/api/v1/mcp \
  --header "Authorization: Basic cm9vdDphcmNhZGVkYg=="

Now ask something like "In the GraphRAG database, which documents are connected to Vector Search through shared entities?". The agent reads the schema, writes the Cypher traversal and cites the records. Because the sample vectors are only 4-dimensional, the agent will lean on query rather than vector_search here; with your own data and a real embedding model, all the retrieval tools apply.

Agent memory

Agents need two kinds of durable memory: episodic (what happened, turn by turn) and semantic (facts learned about people, projects and systems, which change over time). Both are naturally a graph: episodes mention entities, facts are about entities, and a newer fact supersedes an older one instead of overwriting it.

Through MCP, an agent can write that memory itself. upsert_entity matches a vertex by key properties and updates it or creates it; upsert_relationship does the same for an edge between two matched vertices. Repeating the same extraction resolves to the same records instead of piling up duplicates. Two things make it reliable:

• Create a UNIQUE index on the match-key properties. Without it each match is a type scan, and two concurrent upserts can still create the same vertex twice.
• Enable both allowInsert and allowUpdate, ideally only for the memory database, using the per-database overrides.

{"name": "upsert_relationship", "arguments": {
  "database": "memory",
  "fromType": "Person",  "fromMatchKeys": {"email": "[email protected]"},
  "toType": "Project",   "toMatchKeys": {"code": "ANALYTICAL-ENGINE"},
  "relType": "WORKS_ON", "relProperties": {"since": 1843}
}}

The build_knowledge_graph prompt packages this workflow: it reads the existing schema, picks stable match keys, and calls the upsert tools once per entity and relationship.

Memory frameworks that already use ArcadeDB

For a single-process agent, the same graph and vector memory can also run in-process with the embedded Python package, with no server at all.

Vector + graph hybrid search

hybrid_search runs up to three retrieval legs and fuses them into one ranked list:

• Vector: nearest neighbours on an LSM_VECTOR (dense) or LSM_SPARSE_VECTOR index. Required.
• Full-text: a BM25 query on a full-text index. Optional.
• Graph expansion: walks 1 to 3 hops from the records the other legs found, over the edge types you choose, so a neighbour of a strong match can rank too. Optional.

Fusion defaults to Reciprocal Rank Fusion (RRF); DBSF and LINEAR are available for vector plus full-text. Each result lists the legs that produced it in sources, and expanded results carry their depth and path back to the seed, so the agent can explain why a record is there. ArcadeDB does not compute embeddings: the caller passes queryVector from its own model, with the index's dimensions.

{"name": "hybrid_search", "arguments": {
  "database": "research",
  "vectorIndexName": "Paper[embedding]",
  "queryVector": [0.12, -0.08, 0.31],
  "fulltextIndexName": "Paper[abstract]",
  "fulltextQuery": "graph retrieval",
  "expand": {"edgeTypes": ["CITES"], "direction": "out", "maxDepth": 2},
  "fusionStrategy": "RRF",
  "k": 10
}}

The same building blocks are available in SQL for application code, through the vector functions and graph traversal described in the vector search docs.