Datalevin MCP Server

dtlv mcp runs a Datalevin MCP server over stdio.

The MCP server is a local process adapter over Datalevin APIs:

• local MCP clients talk to dtlv mcp over stdio
• the MCP server opens local Datalevin databases directly
• the MCP server can also open remote dtlv://... targets behind the same local stdio process

The intended integration target is generic:

• any MCP-compliant client that can launch a local stdio server
• custom AI-powered applications that want a stable Datalevin tool surface

It is not designed around any specific branded host or coding-agent workflow.

Starting the Server

Read-only mode is the default:

dtlv mcp

Enable write tools explicitly when needed:

dtlv --allow-writes mcp

Session Lifecycle

The server follows MCP 2025-06-18 session sequencing:

• the first request in a session must be initialize
• initialize must include protocolVersion, capabilities, and clientInfo
• request methods such as initialize, ping, tools/list, and tools/call must include a JSON-RPC request id
• normal requests such as tools/list and tools/call are only accepted after the client sends notifications/initialized
• JSON-RPC batch requests are rejected

Tool Result Shape

tools/call replies follow the normal MCP JSON-RPC envelope and return both a machine-readable payload and a text payload:

{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"database\":\"database-...\",\"result\":[[\":name\",\"Alice\"]]}"
      }
    ],
    "structuredContent": {
      "database": "database-...",
      "result": [[":name", "Alice"]]
    }
  }
}

Use structuredContent as the authoritative payload. content[0].text is a compact text rendering for MCP clients that expect a text block.

When a tool fails, MCP returns result.isError = true and the structuredContent value contains the machine-readable error payload.

Large Responses

The MCP server applies its own response shaping on top of Datalevin's JSON API limits.

Current defaults:

• max result items: 200
• max serialized response bytes: 524288

The byte limit is enforced against the full MCP JSON-RPC reply, not just structuredContent.

When a result is truncated, structuredContent includes:

{
  "meta": {
    "truncated": true,
    "truncations": [
      {
        "kind": "items",
        "path": "result",
        "limit": 200,
        "returned": 200,
        "original": 684
      }
    ]
  }
}

Truncation Records

meta.truncations is an array. Each element describes one truncation step.

Item truncation:

{
  "kind": "items",
  "path": "result",
  "limit": 200,
  "returned": 200,
  "original": 684
}

• kind = "items" means the top-level result collection was shortened
• path = "result" identifies the truncated field
• limit is the applied MCP item cap
• returned is the number of items still present
• original is the original top-level item count before truncation

Byte truncation with preview:

{
  "kind": "bytes",
  "path": "result",
  "limit": 524288,
  "mode": "preview"
}

Byte truncation with omission:

{
  "kind": "bytes",
  "path": "result",
  "limit": 524288,
  "mode": "omitted"
}

• kind = "bytes" means the serialized response would have exceeded the MCP byte budget
• mode = "preview" means structuredContent.result still contains a shortened preview
• mode = "omitted" means structuredContent.result was set to null because even the preview form would still be too large

When truncation happens, content[0].text is no longer a full duplicate of the structured payload. It becomes a small summary instead:

Result truncated.

When an untruncated structuredContent payload is still too large to duplicate in content[0].text, the text block becomes See structuredContent. instead. This avoids paying the full payload cost twice.

Pagination Guidance

For naturally paged tools, pass explicit limits instead of relying on MCP truncation:

• datalevin_datoms
• datalevin_kv_range
• datalevin_search_datoms

For Datalog queries, include query-level limiting when possible. MCP still enforces its own caps even if the query itself does not.

Remote Access

The MCP server itself remains a local stdio process. Remote Datalevin access uses Datalevin's existing client/server support behind that process.

Examples:

• local Datalog DB: {"dir":"/data/app-db"}
• remote Datalog DB: {"uri":"dtlv://user:pass@dbhost/app-db"}
• local KV store: {"dir":"/data/app-kv"}
• remote KV store: {"uri":"dtlv://user:pass@dbhost/app-kv"}

Current Notes

• write tools are disabled unless --allow-writes is passed at startup
• MCP ids such as database, kv, searchIndex, and vectorIndex are session-scoped
• the MCP transport is stdio only in v1