ArangoDB MCP Server: making database tools usable by an assistant
Origin
I wanted an AI assistant to inspect ArangoDB and work with its data without asking me to copy query results into a conversation. The first version exposed basic database operations. As the toolset grew, the harder work became making requests, responses, and side effects precise enough for the client to handle.
Overview
ArangoDB stores both documents and relationships between them. This open-source server exposes those operations through the Model Context Protocol, or MCP. A compatible assistant can discover collections, validate and run queries, follow graph relationships, and work with documents.
I built the TypeScript server, tool definitions, input validation, database handlers, and export controls. The assistant interprets the user's request and chooses a tool. The server checks the arguments, performs a defined operation, and returns the result in a declared format.
The project is a local development integration. Its authority comes from the configured database credentials, so describing an operation accurately matters as much as making it callable.
Constraints
An assistant needs to know what it can do, what it received, and whether anything changed.
MCP messages share a standard-input and standard-output connection. Ordinary application logging on the protocol output can make the client unable to read an otherwise valid response. Startup and failure behavior therefore belong to the integration contract.
Implementation
The commit history follows a change from exposing operations to defining their behavior under invalid input, large results, and partial failure.
An early fix removed connection and startup logging that interfered with the MCP conversation. Standard output carries protocol messages. Startup failures can be reported through standard error without mixing diagnostics into a successful tool response.
I also changed initialization so the server awaits the database connection before starting the MCP transport. Tool definitions, runtime schemas, and database handlers live in separate modules. That keeps a protocol change from being mixed into every query implementation.
Features
Inspect and query from a conversation
List collections, inspect sample documents and indexes, validate a query, and request bounded results. Both JSON text and structured data are available to the client.
Work with documents and relationships
Read individual documents, make explicit mutations, traverse a graph, or find a shortest path. Dedicated tools describe the required inputs and return shape.
Run beside the developer's tools
The arango-server process connects to compatible desktop and editor clients over standard input and output. Database credentials come from the environment, and exports stay under the configured output root.
Results
The server grew into a broader database toolset with explicit validation and failure behavior.
- Runtime schemas replaced unchecked argument casts, and successful responses include structured content with declared output schemas.
- Query results carry limits and partial-result information. Parsing and execution-plan inspection are available as separate operations.
- Exports use constrained destinations and exclusive file creation. Mixed collection outcomes are reported as partial failure.
- The integration script exercises the MCP connection against ArangoDB, including graph, search, mutation, and rejection cases.
What mattered
The important boundary is what the server can actually guarantee. It can validate an argument, limit a response, and report an operation's outcome. Whether the query answers the user's question, and whether a proposed write should happen, still requires judgment outside those checks.