feat(mcp): in-server MCP surface (omnigraph-mcp crate) + authoring controls (RFC-003)

[ragnorc]

Summary

Ships the in-server MCP (Model Context Protocol) surface for Omnigraph (RFC-003): a per-graph endpoint POST /graphs/{id}/mcp that lets an MCP agent (Claude Code/Desktop, Cursor, the OpenAI Responses mcp tool) drive a graph directly over stateless Streamable HTTP — reusing the same engine/handler paths and Cedar gates as the REST routes. Lands under v0.8.0.

This branch began as a docs-only RFC blueprint; it now carries the full implementation, the .gq authoring controls, the correct-by-design review fixes, and a merge with main.

What's in it

omnigraph-mcp crate — owns the rmcp Streamable-HTTP transport, the McpBackend trait seam, and a fail-closed McpHostPolicy derived from the bound socket (from_bind after TcpListener::bind). Dependency direction is server → mcp (the trait inverts it, so the crate names no omnigraph type). Crate-level transport conformance lives in omnigraph-mcp/tests/standalone.rs.

Server backend (OmnigraphMcpBackend) — projects 13 built-in tools (query / mutate / load / snapshot / schema / branch / commit / health), the schema + branches as resources, and the stored-query registry as tools (per_query below 24 exposed queries; a stored_query_list + stored_query_run meta pair above). Structured output (structuredContent) on every result. Every tool delegates to the existing run_query / run_mutate / run_ingest / authorize paths — no new business logic.

.gq authoring controls (source-carried, content-addressed; zero cluster plumbing):

• @mcp(expose: <bool>, tool_name: "<name>") — MCP presentation: visibility on the agent surface + the tool id.
• per-parameter @description("…") → the tool input-schema property description.
• @instruction folded into the tool description so an agent reads it in tools/list.

Authorization — tools/list is a faithful relaxation of the per-call gate via permits_on_any_branch / authorize_any_branch (a tool callable on some branch is never hidden; the per-call gate stays authoritative). The list gate is derived from each tool's call shape: fixed-branchless reads (schema_get / branch_list / commit_get) and the resources share one read(None) gate; branch-arg tools relax. expose is presentation, not authorization — Cedar invoke_query (+ the inner read / change) governs who may call.

Correct-by-design review fixes (this branch)

• Tool-name contract at load — from_specs validates every published tool name ([A-Za-z0-9_-], ≤64) and reserves the full surface-generated set (built-ins plus the stored_query_list / stored_query_run meta pair), so a malformed or reserved name fails boot loudly instead of producing a client-rejected catalog or a silent threshold-crossing shadow.
• Stored-query catalog gate unified — GET /queries is now invoke_query-gated (was read), matching the MCP surface and the endpoint's purpose ("see the menu iff you can order from it"). The one observable REST behavior change — documented in the v0.8.0 release note.
• Host allow-list covers the full loopback set (127.0.0.1 / ::1 / localhost) so an IPv6-loopback Host isn't rejected; the MCP-Protocol-Version header is validated on non-initialize requests (documented + tested).

Docs & skill

User: new docs/user/operations/mcp.md (client guide) + server.md / index.md; .gq annotations in queries/index.md; v0.8.0 release notes. Dev: RFC-003 aligned + testing.md. Skill: a dedicated skills/omnigraph/references/mcp.md plus SKILL.md / server-policy / stored-queries updates. openapi.json regenerated.

Merge with main

Merged origin/main (14 commits). One conflict — compiler/parser.rs (main's NanoError → CompilerError rename vs this branch's @mcp / param-description parser additions), resolved by keeping the new parsing with the renamed error type. The CLI queries list change (#280, surfacing @description / @instruction) auto-merged cleanly alongside this branch's mcp_expose / tool_name columns.

Full workspace gate green; cargo tree -p omnigraph-server -e normal | grep rmcp shows rmcp only under omnigraph-mcp.

---

Note

High Risk
Large new agent-facing HTTP surface with auth, policy list/call semantics, and write/load tools reusing production paths; misconfiguration of Origin policy or list/call drift would affect security and operability.

Overview
Introduces omnigraph-mcp (stateless Streamable-HTTP via rmcp, McpBackend trait, fail-closed Host/Origin policy from the bound socket) and merges POST /graphs/{id}/mcp into each graph’s Axum group so bearer auth and GraphHandle reach the backend before rmcp runs.

The server OmnigraphMcpBackend projects 13 built-in tools, schema/branches resources, and stored queries (per-query tools below 24 exposed, stored_query_list / stored_query_run above), delegating to existing run_query, run_mutate, and run_ingest paths. tools/list uses permits_on_any_branch / authorize_any_branch so branch-scoped tools aren’t hidden when the actor can call them on some branch; call_tool stays authoritative, with stored-query denials masked as unknown tools.

Query surface: @mcp(expose, tool_name) and param @description in .gq; registry expose/tool_name fields removed. param_json_schema in omnigraph-api-types feeds MCP/OpenAPI and is locked to the coercer by schema_equivalence tests. GET /queries is gated on invoke_query (aligned with MCP catalog discovery).

^{Reviewed by Cursor Bugbot for commit fbf455a. Bugbot is set up for automated code reviews on this repo. Configure here.}

Greptile Summary

This PR ships the in-server MCP surface for Omnigraph (omnigraph-mcp crate + OmnigraphMcpBackend): a per-graph POST /graphs/{id}/mcp endpoint using stateless Streamable HTTP that projects 13 built-in tools, schema/branches resources, and the stored-query registry as MCP tools — all delegating to existing Cedar-gated engine paths with no new business logic.

• omnigraph-mcp crate owns the rmcp dependency behind a McpBackend trait seam; the McpHostPolicy constructor is fail-closed (non-loopback bind defaults to DenyBrowsers, not open).
• .gq authoring controls (@mcp(expose, tool_name), per-param @description, @instruction) are carried in source; the registry validates tool-name format and reserves the full built-in + meta-pair namespace at boot.
• GET /queries is re-gated from read to invoke_query (the one documented REST behavior change in v0.8.0), aligning catalog discovery with invocation semantics.

Confidence Score: 3/5

The Cedar gate wiring is correct and the fail-closed Origin/Host policy is sound, but two defects need attention before the MCP surface is production-ready: the stored-query JSON schema misstates params as optional even when non-nullable params exist, and the GET /queries auth gate change will silently break existing callers whose token grants only read.

Two independent correctness issues were found: (1) stored_query_input_schema omits the top-level params from required even when the query has non-nullable parameters, so agents make schema-valid calls that the engine rejects — the schema contract is wrong. (2) The re-gating of GET /queries from read to invoke_query is a documented behavior change, but the TypeScript SDK in omnigraph-ts still documents the endpoint as read-gated; SDK callers holding only a read grant will receive unexpected 403s on upgrade.

crates/omnigraph-server/src/mcp.rs (stored_query_input_schema, lines 552–579) and crates/omnigraph-server/src/handlers.rs (server_list_queries auth gate change) need the most attention; the linked TypeScript SDK (omnigraph-ts/packages/sdk/src/resources/queries.ts) also needs a documentation update for the invoke_query requirement.

Important Files Changed

Filename	Overview
crates/omnigraph-server/src/mcp.rs	New 1180-line MCP backend: 13 built-in tools, stored-query projection (per-query/meta modes), Cedar-gated list and call paths. Contains a schema accuracy bug — params is never added to the top-level required array in stored_query_input_schema even when the query has non-nullable params, causing agents to make schema-valid calls that fail at runtime.
crates/omnigraph-server/src/handlers.rs	Adds authorize_any_branch + invoke_query_request helpers; re-gates GET /queries from read to invoke_query. The auth gate change is a deliberate behavior break that the linked TypeScript SDK does not reflect yet.
crates/omnigraph-mcp/src/transport.rs	Stateless Streamable-HTTP transport with fail-closed Origin guard (origin_guard) and McpHostPolicy::from_bind constructor. Loopback vs. public bind logic is correct; DenyBrowsers default for non-loopback with no configured origins is appropriate.
crates/omnigraph-mcp/src/lib.rs	Clean seam crate — McpBackend trait, rmcp type re-exports, no omnigraph types. Dependency direction server→mcp correctly enforced.
crates/omnigraph-policy/src/lib.rs	Adds InvokeQuery action (graph-scoped, no branch dimension) and permits_on_any_branch for list-time capability probing. Branch-shape enumeration (branchless / protected / unprotected) correctly covers all distinguishable request forms. New tests cover the relaxation semantics.
crates/omnigraph-server/src/queries.rs	Registry refactored: expose/tool_name moved from spec fields to source @mcp(...) annotations; from_specs now validates tool names and reserves the full built-in + meta pair namespace at boot. exposed_by_name correctly gates unexposed queries from the MCP surface.
crates/omnigraph-api-types/src/lib.rs	Adds param_json_schema (single mapping for both OpenAPI catalog and MCP input schemas) and description field on ParamDescriptor. Nullable handling (anyOf + null) and integer/bigint dual-type schemas match the engine coercer contract documented in the equivalence tests.
crates/omnigraph-server/src/lib.rs	Mounts the MCP router into per-graph protected routes; derives McpHostPolicy from the bound socket address after TcpListener::bind (preventing the loopback-default fail-open on public binds). Tests skip with_mcp_host_inputs, correctly getting the loopback-safe default.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Agent as MCP Agent
    participant Transport as McpHostPolicy + origin_guard
    participant Auth as require_bearer_auth / resolve_graph_handle
    participant Backend as OmnigraphMcpBackend
    participant Cedar as PolicyEngine
    participant Engine as Graph Engine

    Agent->>Transport: "POST /graphs/{id}/mcp"
    Transport->>Transport: Check Host header (allowed_hosts)
    Transport->>Transport: Check Origin header (OriginPolicy)
    Transport->>Auth: Axum route_layer
    Auth->>Auth: resolve bearer → ResolvedActor (extensions)
    Auth->>Auth: resolve graph → GraphHandle (extensions)
    Auth->>Backend: tools/list or tools/call

    alt tools/list
        Backend->>Cedar: authorize / permits_on_any_branch per tool
        Cedar-->>Backend: allow / deny per built-in
        Backend->>Cedar: allowed(invoke_query) for stored surface
        Cedar-->>Backend: can_invoke
        Backend-->>Agent: filtered Tool list
    end

    alt call_tool (built-in)
        Backend->>Cedar: authorize_request (per-call gate)
        Cedar-->>Backend: Authz::Allowed / Denied
        Backend->>Engine: run_query / run_mutate / run_ingest
        Engine-->>Backend: result
        Backend-->>Agent: CallToolResult (structuredContent)
    end

    alt call_tool (stored query)
        Backend->>Cedar: authorize invoke_query
        Cedar-->>Backend: Allowed or Denied→unknown_tool
        Backend->>Engine: run_query / run_mutate (inner read/change gate)
        Engine-->>Backend: result
        Backend-->>Agent: CallToolResult (isError on 4xx)
    end

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant Agent as MCP Agent
    participant Transport as McpHostPolicy + origin_guard
    participant Auth as require_bearer_auth / resolve_graph_handle
    participant Backend as OmnigraphMcpBackend
    participant Cedar as PolicyEngine
    participant Engine as Graph Engine

    Agent->>Transport: "POST /graphs/{id}/mcp"
    Transport->>Transport: Check Host header (allowed_hosts)
    Transport->>Transport: Check Origin header (OriginPolicy)
    Transport->>Auth: Axum route_layer
    Auth->>Auth: resolve bearer → ResolvedActor (extensions)
    Auth->>Auth: resolve graph → GraphHandle (extensions)
    Auth->>Backend: tools/list or tools/call

    alt tools/list
        Backend->>Cedar: authorize / permits_on_any_branch per tool
        Cedar-->>Backend: allow / deny per built-in
        Backend->>Cedar: allowed(invoke_query) for stored surface
        Cedar-->>Backend: can_invoke
        Backend-->>Agent: filtered Tool list
    end

    alt call_tool (built-in)
        Backend->>Cedar: authorize_request (per-call gate)
        Cedar-->>Backend: Authz::Allowed / Denied
        Backend->>Engine: run_query / run_mutate / run_ingest
        Engine-->>Backend: result
        Backend-->>Agent: CallToolResult (structuredContent)
    end

    alt call_tool (stored query)
        Backend->>Cedar: authorize invoke_query
        Cedar-->>Backend: Allowed or Denied→unknown_tool
        Backend->>Engine: run_query / run_mutate (inner read/change gate)
        Engine-->>Backend: result
        Backend-->>Agent: CallToolResult (isError on 4xx)
    end

Loading

_{Reviews (7): Last reviewed commit: "test(mcp): harden symptomatic MCP fixes ..." | Re-trigger Greptile}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3009564437

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Configure allowed hosts for non-loopback MCP deployments

In any remote or cloud deployment, keeping rmcp's default allowed_hosts makes /mcp reject valid clients before bearer auth, because rmcp 1.7 defaults Host validation to loopback authorities only (localhost, 127.0.0.1, ::1). This RFC explicitly targets remotely reachable MCP clients, so the blueprint should require a server-configured allowed-host allowlist (or a documented reverse-proxy Host validation setup) instead of preserving the loopback default.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Reconcile the stale rollout with locked decisions

These locked decisions conflict with the still-active Rollout and Testing sections below, which continue to tell implementers to ship graphs_list, read/change aliases, a server-level /mcp, and an mcp.allow_adhoc switch. Since the status says the blueprint only supersedes the older §5 sketches, someone following the Rollout section would build surface area this canonical section says was dropped; please update those later sections or explicitly mark them historical too.

Useful? React with 👍 / 👎.

[ragnorc]

Addressed the valid review findings as correct-by-construction fixes (commit 2ade97f) so a from-scratch build can't reintroduce them:

• allowed_hosts loopback-only → 403s remote clients (codex/greptile here; cursor/devin on feat(server): in-server MCP surface over Streamable HTTP (RFC-003) #157): host/origin policy is now derived from the server bind + config (B.3.1), never rmcp's fixed loopback default. Loopback bind → loopback hosts; non-loopback → configured public host, else Host-allowlisting off (bearer + Origin are the controls).
• stored-query branch/snapshot param collision (feat(server): in-server MCP surface over Streamable HTTP (RFC-003) #157: cursor High, greptile P1, devin): params nested under a params object (B.6/B.7), mirroring POST /queries/{name} — the knobs and query params are separate namespaces, so collision is unrepresentable. Mutation tools omit snapshot + additionalProperties:false, so "mutation against a snapshot" is unrepresentable (vs silently dropped).
• 5xx surfaced as isError (feat(server): in-server MCP surface over Streamable HTTP (RFC-003) #157): one canonical classify(Result<_, ApiError>) for tool errors (B.8) — 5xx → JSON-RPC, 4xx/409 → isError; no second mapper to drift.
• vector_dim: None → 0-length-array schema (feat(server): in-server MCP surface over Streamable HTTP (RFC-003) #157): dim made intrinsic to the Vector kind (B.7); unwrap_or(0) can't exist.
• branch-scope preflight hides callable tools (codex on feat(server): in-server MCP surface over Streamable HTTP (RFC-003) #157): list visibility now uses the call-path default-branch authorization, not a branch: None probe (B.8).
• stale Rollout/Testing + Summary count (codex/greptile here): reconciled with banners pointing at B.12/B.4/B.13 and the count corrected.

The "missing server.md MCP section" finding was stale — reviewers saw commit 94bbf67, before the docs commit added it.

[greptile-apps]

ragnorc has reached the 50-review limit for trial accounts. To continue receiving code reviews, upgrade your plan.

[greptile-apps]

ragnorc has reached the 50-review limit for trial accounts. To continue receiving code reviews, upgrade your plan.

[greptile-apps]

ragnorc has reached the 50-review limit for trial accounts. To continue receiving code reviews, upgrade your plan.

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit fbf455a. Configure here.}

[cursor]

Filter ignores MCP tool name

Low Severity

The stored_query_list filter only matches registry name and description, not tool_name. Summary rows include tool_name, so substring search fails when the @mcp(tool_name: …) override differs from the registry key—agents cannot discover queries by the MCP id the list shows.

 

^{Reviewed by Cursor Bugbot for commit fbf455a. Configure here.}