MCP Server

OMGDB ships a minimal Model Context Protocol server that exposes the engine directly to coding agents. Started with omgdb mcp, it speaks newline-delimited JSON-RPC 2.0 over stdin/stdout and advertises the database as 48 agent-callable tools built on the engine’s own JSON codec.

The defining feature is its capability-scope model. The server runs at a single ceiling — read or read-write — and a tool is only callable if its required scope is within that ceiling. Enforcement happens in two layers: tools above the ceiling are never advertised in tools/list, and every tools/call re-checks the ceiling before executing. An untrusted agent can be handed a read-only database it is structurally unable to mutate.

For wiring the server into specific agent hosts, see the agent setup guides.

Running the server

omgdb mcp

This starts a stdio server at the default read-write scope. It reads JSON-RPC requests one per line from stdin and writes one response per line to stdout, flushing after each, until stdin closes. Blank lines, lines that do not parse as a JSON object, and objects without a string method are silently ignored.

To restrict the server to the read tools:

omgdb mcp --scope read

Stateless by design: the server holds no session. Every tool takes a path argument naming the on-disk store, and everything that looks like session state — read cursors, planned-change tokens — is persisted as sidecar files inside the store itself. Cursors and plan tokens survive a server restart.

Capability scopes

Scopes are ordered (read < read-write < dangerous); a tool is allowed if and only if its required scope is at or below the server’s ceiling.

Two-layer enforcement

1. Discovery. tools/list filters the catalog to tools within the server scope. A read server returns 23 tools, a read-write server 47, a dangerous server all 48. A read-only agent never even sees the mutating tools — and no agent sees drop_collection unless the server was deliberately started with the dangerous ceiling.

2. Execution. tools/call re-checks the ceiling before doing any work. A disallowed call returns a tool result with isError: true:

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

So hiding a tool from tools/list is not the only line of defense — an agent that guesses a tool name it was never shown is still refused.

Unknown tool names

Tool existence is checked before the scope check. A typo’d or invented tool name always gets Error: unknown tool `finds` — never a message suggesting the server needs more scope. A misspelling cannot be mistaken for a permissions problem, and cannot be used to fish for scope escalation.

Tools

All 48 tools take a path string naming the store; documents, filters, pipelines, and update specs are JSON values. In the tables below, a trailing ? marks a parameter as optional — everything else is listed in the tool’s inputSchema.required, exactly matching what dispatch enforces at call time.

Read tools (23) — scope read

Write tools (24) — scope read-write

Dangerous tools (1) — scope dangerous

Argument requiredness

Requiredness is declared per tool and matches execution exactly:

• find and cursor_open treat a missing filter as {} (match all) — it is optional in their schemas.
• explain, suggest_indexes, diagnose, and plan_update require filter: an introspection or mutation plan against an implicit match-all is too easy to trigger by accident, so a missing filter is a missing argument `filter` error. Pass {} explicitly to mean “all documents”.
• explain and diagnose additionally refuse a collection that does not exist, with a did-you-mean hint — a typo never yields confidently wrong planner advice.

Safety annotations

Every tool carries an annotations object so an MCP host can reason about tool safety, and the annotations reflect what each tool actually does:

JSON-RPC methods

Error handling

Protocol-level problems are JSON-RPC errors:

Tool-level failures — an unknown tool name, a refused-by-scope call, a missing argument, or an engine error — are not JSON-RPC errors. They return a normal result envelope whose content is a text block and whose isError is true, so an agent can read the message and repair the call.

A complete session, copy-paste

Create a store, then drive the server over stdin — three requests, one per line:

omgdb create app.omgdb
omgdb insert app.omgdb users '{"name":"ana","age":30}'

printf '%s\n' \
  '{"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}}}}}' \
| omgdb mcp

The initialize response identifies the server:

{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"omgdb","version":"..."}}}

tools/list returns 47 tools at the default scope (23 with --scope read, all 48 with --scope dangerous), each with an inputSchema and annotations. The find entry looks like:

{
  "name": "find",
  "description": "Find documents matching a MongoDB-style filter",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": {"type": "string"},
      "collection": {"type": "string"},
      "filter": {"type": "object"},
      "sort": {"type": "object"},
      "skip": {"type": "integer"},
      "limit": {"type": "integer"},
      "afterId": {},
      "afterSortKey": {"type": "object"},
      "project": {"type": "object"}
    },
    "required": ["path", "collection"]
  },
  "annotations": {
    "readOnlyHint": true,
    "idempotentHint": true,
    "destructiveHint": false,
    "requiredScope": "read"
  }
}

And the find call returns the matching document as NDJSON inside a text block.

If the server had been started with --scope read, a call to a write tool such as insert would come back as a result flagged as an error, not an insert:

{"jsonrpc":"2.0","id":4,"result":{"content":[{"type":"text","text":"Error: tool `insert` requires `read-write` scope but this server runs with `read` scope"}],"isError":true}}

Related

• Agent setup guides — wiring the server into specific agent hosts.
• Agent mutations — the plan_update / apply / rollback workflow surfaced by the write tools.
• CLI reference — the full omgdb command surface, including the equivalent direct commands.