prototype

typedb-mcp

A safety-focused Model Context Protocol server that exposes a TypeDB 3.11+ database to an LLM agent. Written in Rust, built on the official typedb-driver (gRPC) and the rmcp SDK.

Read the source on GitHub How to run it

what it is

typedb-mcp is an independent reimplementation, in Rust on gRPC, of the upstream typedb/typedb-mcp Python (HTTP) server. The transport URL and the broad shape of the tool surface match upstream's intent, but this is not a drop-in replacement.

Three differences are load-bearing:

start_session is the entry point, and every other tool requires a session_id argument. Sessions outlive the MCP transport session — a deliberate choice driven by LiteLLM-gateway interop.
The lifecycle is gated. Schema must be read before a transaction can be opened on a database. Only one transaction is open at a time. The response envelope is structured (session, next_moves, result or error).
The TypeDB endpoint is gRPC on port 1729, not the HTTP API on 8000 that the upstream Python server uses.

theory

Agent affordances are user affordances.

The design of this server rests on one observation: the things that make a tool easier for a human to use correctly are the same things that make it easier for an agent to use correctly. The two populations have different failure modes — humans get bored, agents hallucinate — but they fail for a shared underlying reason, which is that both have to resolve indirection to act, and both have a finite budget for doing so.

Compare two error messages.

Specified database does not exist.

versus

Specified database agnts does not exist. Available databases: agents, ost, scratch.

The first error tells the caller that something is wrong. To recover, the caller has to figure out which database was specified, list the databases that exist, compare, guess, and retry. Every one of those steps is a hop of indirection.

The second collapses all of those hops into the response itself. A human reading the first error is mildly inconvenienced. An agent reading the first error spends tokens on a multi-turn investigation that ends, often, in a fabricated database name. The direction of the cost is the same for both readers.

Build for the agent the way you would build for a careful but tired human, and both will do better work.

how to run it

Published to GitHub Container Registry as ghcr.io/tilmon-engineering/typedb-mcp.

docker run -p 8001:8001 \
  ghcr.io/tilmon-engineering/typedb-mcp:latest \
  --typedb-address host.docker.internal:1729 \
  --typedb-username admin \
  --typedb-password password

On Linux, add --add-host=host.docker.internal:host-gateway to reach a TypeDB running on the host. The address points at TypeDB's gRPC port, not the HTTP port.

Point your MCP client at http://<host>:8001/mcp. For Cursor:

{
  "mcpServers": {
    "typedb": { "url": "http://localhost:8001/mcp" }
  }
}

status

typedb-mcp is in active development. The source is the canonical place for issues, discussions, and changes — public feedback is preferred over private inbound.

github.com/tilmon-engineering/typedb-mcp

feedback

React to this prototype.

If you'd rather not open an issue — that it's interesting, that it misses, that you'd use it, that you wouldn't — drop a line. Goes straight to Sean.