omnigraph/docs/releases/v0.8.0.md

Omnigraph v0.8.0

v0.8.0 has two headline changes:

1. Every served graph becomes an MCP (Model Context Protocol) server — an MCP-capable agent (Claude Code/Desktop, Cursor, the OpenAI Responses mcp tool, and others) can connect to a graph and operate it directly. The surface adds no new capability and no new business logic; every tool delegates to the same engine/handler path the REST routes use and is gated by the same Cedar policy. It is additive.
2. Graph commit lineage moves into __manifest (RFC-013 Phase 7), folded into the publish CAS, via a one-time on-disk migration (internal schema v3 → v4). This is the first internal-schema change since v0.4.0 and carries an upgrade-order requirement — read the upgrade notes before rolling it out.

MCP surface (POST /graphs/{id}/mcp)

An MCP-capable agent can connect to a graph and run reads and mutations, load data, manage branches, browse commits, read the schema, and invoke the graph's curated stored queries.

• One MCP endpoint per served graph, mounted automatically by the cluster server — no separate flag. It is a stateless Streamable-HTTP transport: a single application/json JSON-RPC response per call, no SSE, no session id.
• Built-in tools cover the operational surface: graph_query, graph_mutate, graph_load, graph_snapshot, schema_get, branch_list, branch_create / branch_delete / branch_merge, commit_list / commit_get, schema_apply (disabled with a 409 under cluster-backed serving — evolve via cluster apply and restart), and a graph_health liveness probe.
• Stored queries as tools. A graph's stored-query registry is projected as tools, in one of two modes chosen automatically from the exposed-query count: per_query (each exposed query is its own typed tool) below a threshold, or a stored_query_list + stored_query_run discovery/execute pair at or above it, so a client's tool count stays bounded.
• Resources. The graph schema (omnigraph://schema) and branch list (omnigraph://branches) are exposed as MCP resources.
• Structured output. Tool results carry structuredContent (the same typed result envelopes as the REST routes) plus a text mirror.

Authorization parity with REST

• Every tool and resource resolves the actor from the bearer token and passes the same Cedar gate as the equivalent REST route; the call-time gate is authoritative.
• tools/list is a relaxation of the per-call gate: a tool the actor could invoke on some branch is listed, so listing never hides a tool you can call, while an actor with no grant for an action still does not see its tools. Under the common "protect main, write feature branches" policy, graph_mutate is listed for an actor who can write unprotected branches.
• Stored queries sit behind the coarse invoke_query gate (a stored mutation is additionally change-gated); for a caller without invoke_query, a stored tool masks as an unknown tool so the catalog can't be probed. An expose: false query is unreachable on the MCP surface entirely (not listed, not runnable by name) while remaining HTTP/service callable.

Authoring stored queries as MCP tools

.gq gains the controls to shape how a stored query appears as an MCP tool, all carried in the query source:

• @instruction("…") reaches agents. The query's @instruction annotation is folded into the MCP tool description (after @description), so the how/when-to-use guidance shows up in tools/list — previously it surfaced only in the REST catalog.
• Per-parameter docs. A leading @description("…") on a parameter (@description("the user's slug") $slug: String) is surfaced into the parameter's JSON-Schema description in both the MCP tool input schema and the GET /queries catalog.
• @mcp(tool_name: "…", expose: <bool>). A dedicated MCP-presentation annotation: tool_name overrides the tool id (unique-checked at boot, can't shadow a built-in); expose: false hides the query from the agent tool surface (tools/list / stored_query_list / stored_query_run) while keeping it HTTP/service-callable by name. expose is presentation only — Cedar invoke_query remains the authority for who may call a query.

Transport hardening

• Fail-closed Host / Origin posture, derived from the bind address at startup. A loopback bind accepts the full loopback Host set (127.0.0.1, ::1, localhost) regardless of which IP stack it bound; a non-loopback bind rejects an unexpected browser Origin and restricts Host to the configured public hosts.
• The MCP-Protocol-Version header is validated on follow-up requests (an unsupported version is a 400); initialize negotiates the version in its body and is exempt by design.

Graph lineage now lives in __manifest (internal schema v4)

The graph commit DAG (commits, parents, merge parents, per-branch heads, and the authoring actor) is now stored in __manifest as graph_commit / graph_head rows, written in the same commit (CAS) as the table-version rows of a graph publish. Previously the lineage lived in a separate _graph_commits.lance dataset written after the manifest commit, leaving a narrow window where a crash could land a manifest version with no matching lineage row. Folding the lineage into the publish closes that gap by construction: a graph commit and its lineage now land atomically at one manifest version. The in-memory commit graph is a projection of those manifest rows; _graph_commits.lance is retained only as a carrier for Lance branch refs and no longer receives commit rows.

This bumps the __manifest internal schema stamp from v3 to v4.

Existing graphs migrate seamlessly on first write

A graph created by an earlier binary (internal schema v3) keeps its lineage in _graph_commits.lance with none in __manifest. On the first read-write open, Omnigraph backfills that lineage into __manifest (the migrate_v3_to_v4 internal-schema step) and bumps the stamp to v4. The migration:

• is per-branch — each branch backfills on its first write;
• is idempotent and crash-safe — the stamp bump is the last step, and the backfill is keyed on the commit id, so a crash mid-migration re-runs harmlessly on the next open;
• preserves all data — every commit, parent, merge parent, actor, and head is carried over; commit ids are stable, so existing references still resolve.

No data is lost and no operator action is required beyond upgrading the binary.

Before its first write migrates the graph, a read-only open of a v3 graph (e.g. omnigraph commit list, NDJSON export) still reads correct history via a transitional fallback that sources the commit DAG from _graph_commits.lance — read-only opens never write, so they never migrate, but they never show an empty history either.

Upgrade notes

• Breaking: internal schema v4 — upgrade writer (and reader) binaries first. Internal schema v4 is a hard version gate. Once a graph has been opened for write by a v0.8.0 binary, its __manifest is stamped v4, and an older binary will refuse to open it — read-write and read-only — with an upgrade omnigraph before opening this graph error rather than silently misreading the new lineage. This is the standard forward-version protection (same shape as the v1→v2 / v2→v3 steps), now enforced on the read-only path too. Upgrade every writer (and reader) binary that touches a graph to v0.8.0 before, or together with, the first write under the new version. A mixed fleet where an old binary still writes the same graph is unsupported, as with any internal-schema bump.
• GET /graphs/{id}/queries is now invoke_query-gated (was read). The stored-query catalog uses the same authority as invocation and the MCP tools/list surface, so discovery and invocation agree ("see the menu iff you can order from it"). A caller with only read (and no invoke_query) now gets 403 instead of a listing; in default-deny mode the endpoint returns 403 until an invoke_query rule is configured. This is the one observable REST behavior change in this release.
• The MCP endpoint is additive. Apart from the GET /queries gate change and the v4 on-disk migration above, the REST surface, CLI, and cluster config are unchanged.
• Pointing an agent at a graph: configure your MCP client with the URL https://<host>/graphs/<id>/mcp and the same bearer token you use for REST. See docs/user/operations/mcp.md for the connect recipe, the tool catalog, projection modes, and the Host/Origin and protocol-version contracts. Design and rationale: RFC-003.