# 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](/content/docs/operations/policy/index.html) 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](/content/docs/operations/mcp#enable-it/index.html)

`/mcp` is mounted whenever the server has a bearer credential source: static tokens, signed data tokens, or an [OIDC resource identity](/content/docs/operations/server#oidc-resource-identities-and-mcp/index.html) (`--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](/content/docs/operations/mcp#upgrade-tool-schemas/index.html)

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](/content/docs/operations/policy#learn-your-access/index.html). `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](/content/docs/operations/mcp#sign-in-and-discovery/index.html)

A request without a valid credential is refused with 401 before its body is read, with the same [challenge](/content/docs/operations/server#authentication/index.html) 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](/content/docs/operations/mcp#connect-a-stdio-agent/index.html)

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](/content/docs/operations/mcp#tools/index.html)

### [Read tools](/content/docs/operations/mcp#read-tools/index.html)

| 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](/content/docs/operations/mcp#write-tools/index.html)

| 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](/content/docs/operations/mcp#resources/index.html)

| 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](/content/docs/operations/mcp#results-and-errors/index.html)

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.
