---
title: Connect your coding agent
description: Wire OMGDB into Claude Code, Cursor, or any MCP-capable client, choose the right capability scope, and give your agent a safe first tour of the store.
---

OMGDB is built to be driven by a coding agent. The bridge is the [MCP server](/docs/mcp/): `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:

```sh
# 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:

```json
{
  "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:

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

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

```sh
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):

```json
{
  "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:

```sh
omgdb mcp --scope read
```

```json
{"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](/docs/mcp/) 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).

| Scope | Tools | When |
| --- | --- | --- |
| `read` | `find`, `aggregate`, `describe`, `explain`, `diagnose`, `vsearch`, `context_pack` | Default choice. The agent can query, introspect, and search but is structurally unable to mutate. |
| `read-write` | All of the above plus `insert`, `plan_update`, `apply`, `rollback` | When you want the agent to change data through the reversible workflow. |
| `dangerous` | Reserved; currently permits the same tools as `read-write` | Not needed today — no destructive tool exists yet. |

**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](/docs/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:

```text
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:

```text
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](/docs/mcp/) — the full protocol reference: tools, schemas, scopes, error envelopes.
- [Agent mutations](/docs/agent-mutations/) — the plan → apply → rollback workflow in depth.
- [Errors & self-repair](/docs/errors/) — the error catalog the agent can repair from.
- [Introspection](/docs/introspection/) — `describe`, `dump`, `verify`, and schema inference.