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.