Connect your coding agent

OMGDB is built to be driven by a coding agent. The bridge is the MCP server: omgdb mcp speaks newline-delimited JSON-RPC 2.0 over stdin/stdout and exposes the engine as scoped, agent-callable tools. This page is the wiring guide — the config blocks for the common clients, how to pick a capability scope, what the agent should read first, and the failures you are most likely to hit.

Before you wire anything

Two prerequisites, both one command:

# 1. Have the binary on PATH (see /docs/install/)
omgdb --help

# 2. Create the store — there is no create tool over MCP
omgdb create app.omgdb

The MCP tool set operates on existing stores. Creating a store, importing data in bulk, and repairing a corrupt log stay CLI-side on purpose.

Claude Code

Add a .mcp.json at your project root. The recommended starting point is read-only:

{
  "mcpServers": {
    "omgdb": {
      "command": "omgdb",
      "args": ["mcp", "--scope", "read"]
    }
  }
}

When you want the agent to write through the safe-mutation workflow, switch to the read-write variant:

{
  "mcpServers": {
    "omgdb": {
      "command": "omgdb",
      "args": ["mcp", "--scope", "read-write"]
    }
  }
}

Or register it from the terminal instead of editing the file:

claude mcp add omgdb -- omgdb mcp --scope read

Cursor

Same server, same shape — put it in .cursor/mcp.json in the project (or ~/.cursor/mcp.json globally):

{
  "mcpServers": {
    "omgdb": {
      "command": "omgdb",
      "args": ["mcp", "--scope", "read"]
    }
  }
}

Any stdio client

There is nothing client-specific in the server. Spawn the process and exchange one JSON-RPC object per line over stdin/stdout:

omgdb mcp --scope read

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"find","arguments":{"path":"app.omgdb","collection":"users","filter":{"age":{"$gte":21}}}}}

The server answers initialize with protocol version 2024-11-05, filters tools/list by the scope ceiling, and runs until stdin closes. It is stateless across calls: every tool takes a path argument and reopens the store for that call, so there is no session to manage. The full protocol contract — methods, error envelopes, safety annotations — is in the MCP server reference.

Choosing a scope

The server runs at a single capability ceiling, enforced both at discovery (tools/list hides tools above the ceiling) and again at execution (a guessed tool name is still refused).

Start at read. A read-only agent can already do the interesting work: explore the schema, debug queries, run semantic search, build context packs. Escalate to read-write when you trust the loop — and note that what read-write unlocks is not raw mutation but the safe-mutation cycle: plan_update dry-runs the change and returns a token plus a before/after sample, apply commits it as one transaction, and rollback restores the recorded before-state. Every applied change remains a cat-able audit file backed by the op-log. See agent mutations.

Note: Scopes gate capabilities, not filesystem paths. Every tool takes a store path, so a read-only server can still read any store the process can access. Run the server as a user whose filesystem permissions match what you intend to expose.

What the agent should read first

Point the agent at the store’s own self-description before it writes a single query:

1. describe — the MCP tool that returns a Markdown manual of the live database: every collection, its inferred per-field schema, its indexes, and its validation spec. The validation spec is the write contract; an agent that reads it first stops guessing field names and types.
2. omgdb inspect app.omgdb --json — the quick machine-readable catalog (collections and document counts). This one is CLI-only today, so the agent runs it in the terminal rather than over MCP.
3. explain and diagnose — before trusting a query, explain shows whether it will use an index or scan, and diagnose reports per-predicate match counts when a filter returns nothing. Both fail loudly with a did-you-mean hint if the collection name is a typo.

A practical convention: add a line to your project’s agent instructions (for example CLAUDE.md) saying “call describe on app.omgdb before querying it.”

Troubleshooting

path must be the store directory. Every tool’s path argument names the store directory — the one containing oplog.ndjson. Not the single-file .omgdb pack archive (run omgdb unpack first) and not the oplog.ndjson file itself. Prefer absolute paths: the server resolves relative paths against its own working directory, which is set by the MCP client and may not be your project root.

One process at a time. A store is protected by an exclusive advisory lock; a second process is refused cleanly with:

store at `app.omgdb` is locked by another process

The MCP server itself is stateless — it takes the lock per call and releases it — so when you see this, the usual culprit is another long-lived process holding the store open (a REPL, a stuck CLI command, a second MCP server on the same store). Close it and retry; the lock clears when the holder exits.

A write tool is refused. At --scope read, calls to insert, plan_update, apply, or rollback return a tool-level error rather than executing:

Error: tool `insert` requires `read-write` scope but this server runs with `read` scope

Update the config to read-write and restart the server process (most clients respawn it automatically on config change).

The store “does not exist.” Tool errors about a missing store or missing collections usually mean the path resolved somewhere unexpected (see the absolute-path advice above) or the store was never created — remember create is CLI-only.

Related

• MCP server — the full protocol reference: tools, schemas, scopes, error envelopes.
• Agent mutations — the plan → apply → rollback workflow in depth.
• Errors & self-repair — the error catalog the agent can repair from.
• Introspection — describe, dump, verify, and schema inference.