mcp

MCP

omnigraph-server serves the Model Context Protocol at /mcp, so Claude, ChatGPT, Cursor and other MCP clients can work with a graph with a URL and the caller's own credential. MCP shares the server's listener and lifecycle; no separate service is needed.

Every tool calls the same handler as its HTTP route, under the same actor and the same policy action. A tool appearing in the list is not permission to use it: a call the policy refuses returns the route's refusal.

Enable it

/mcp is mounted whenever the server has a bearer credential source: static tokens, signed data tokens, or an OIDC resource identity (--oidc-identity-trust). A server without credentials has no MCP.

Credentials /mcp OAuth discovery Challenge on a 401
Static or signed data tokens mounted none Bearer
OIDC resource identity, alone or with tokens mounted served Bearer resource_metadata="<url>"

With static or signed tokens, configure the client with the URL and an Authorization: Bearer <token> header; Claude Code and Cursor support this directly. With OIDC, the resource identifier in the trust file is the URL users enter in their MCP client, for example https://graphs.example.com/mcp, and the client signs in through OAuth.

Upgrade tool schemas

After upgrading the server, reconnect clients and refresh cached tool schemas with tools/list. The access tool now returns actor_id instead of actor; clients with fixed response types must update those types before reconnecting. Its output matches the HTTP access report. queries now lists stored mutations too, marked mutation: true, and mutate no longer requires query.

MCP does not use the Omnigraph-Http-Api header, so an old MCP client is not automatically refused.

Sign-in and discovery

A request without a valid credential is refused with 401 before its body is read, with the same challenge as every other route.

WWW-Authenticate: Bearer resource_metadata="https://graphs.example.com/.well-known/oauth-protected-resource/mcp"

When a bearer credential was presented and refused (bad signature, expired, wrong audience or organization), the challenge also carries error="invalid_token", which tells a client to refresh or sign in again. Without OIDC the challenge is Bearer, which advertises no sign-in flow.

Connect a stdio agent

An agent that starts its MCP servers as child processes, such as Claude Code or Codex in a terminal, connects to an existing server through the CLI:

{"command": "omnigraph", "args": ["mcp", "--target", "staging"]}

Tools

Read tools

Tool Arguments Runs Policy action
health none GET /healthz none
graphs none GET /graphs/discovery for an identity credential; otherwise GET /graphs, narrowed to ids and names identity, or graph_list
schema graph GET /graphs/{graph_id}/schema read
queries graph GET /graphs/{graph_id}/queries read
query graph, query (source) or name (stored), optional params, branch, snapshot source: POST /graphs/{graph_id}/query; name: POST /graphs/{graph_id}/queries/{query_name} as a read source: read, and change for explain load csv; name: invoke_query, then read
snapshot graph, optional branch GET /graphs/{graph_id}/snapshot read
access graph, optional branch, target_branch GET /graphs/{graph_id}/access none
branches_list graph, optional detailed GET /graphs/{graph_id}/branches read; with detailed, details only for branches the caller may read
branches_diff graph, source, optional target, kind, type, op, page_token, limit GET /graphs/{graph_id}/branches/diff read on both branches
branches_merge_base graph, source, optional target GET /graphs/{graph_id}/branches/merge-base read on both branches

Write tools

Tool Arguments Runs Policy action
mutate graph, query, optional name, params, branch, if_graph_commit POST /graphs/{graph_id}/mutate, or /mutate/if-graph-commit with if_graph_commit change; a branch statement takes its branch action
commits_publish graph, commit_id POST /graphs/{graph_id}/commits/{commit_id}/publish commit_publish on the commit's recorded target

Resources

URI Content
omnigraph://graphs The graphs result, JSON, under the same rule
omnigraph://graphs/{graph}/schema (template) The graph's .pg source
omnigraph://best-practices/index Which reference to read for which task, Markdown

Results and errors

A successful call returns the route's JSON response body as structured content, plus a text copy for older clients. A refused call returns isError: true with { "status": <HTTP status>, "error": <error body> }: the error body every HTTP route answers, with its code, disposition and details, and the status the same failure answers over HTTP, for example 403 for a policy denial.