Connect over MCP

The endpoint

Point your MCP client at /mcp on this deployment. It is a remote server over Streamable HTTP, and an OAuth 2.1 resource server: the first unauthenticated call returns a 401 pointing your client at the protected-resource metadata, which names Heron as its own authorization server. A compliant client discovers the rest — authorization-server metadata, dynamic registration, the authorization code flow with PKCE — on its own.

Connect from your client

Every recipe below uses https://heron.theona.ai/mcp. If you run your own Heron, swap that host for your deployment’s. There is no key to paste anywhere — on first use the client opens a browser, you sign in, and it stores the token for you.

Claude Code

One command, then finish the sign-in from inside Claude Code:

claude mcp add --transport http heron https://heron.theona.ai/mcp

Then run /mcp in Claude Code and complete the browser sign-in. HTTP is the transport that carries OAuth.

Cursor

Add Heron to ~/.cursor/mcp.json (global) or .cursor/mcp.json (this project):

{
  "mcpServers": {
    "heron": { "url": "https://heron.theona.ai/mcp" }
  }
}

Cursor opens your browser to sign in the first time the agent uses a Heron tool.

Claude Desktop

Settings → Connectors → Add custom connector, and paste https://heron.theona.ai/mcp. Claude Desktop runs the sign-in and stores the token.

Any other client (stdio only)

A client that speaks only stdio can still reach a remote server through the mcp-remote bridge — the same shape works for most editors and desktop apps:

{
  "mcpServers": {
    "heron": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://heron.theona.ai/mcp"]
    }
  }
}

Signing in

When your client starts the flow, it opens a browser to Heron. You sign in the same way you sign in to the dashboard — through Google — and approve the client. Your client receives a token and uses it as a bearer on every call. There is no API key to paste: the token is minted for you, and it expires.

The token identifies who you are, never where you may act. Every tool but heron_list_areastakes an organization and project and re-checks your grant on them each call — exactly as the dashboard resolves permission from the URL, never from an ambient “current organization”. A client holding your token still reaches only the projects you already have a grant on.

What the tools do

Reads (any grant):

• heron_list_areas— the organizations and projects you hold a grant on, with your role and each project’s environments. Takes no arguments; start here, because these are the slugs every other tool asks for.
• heron_list_sessions, heron_get_session— agent sessions and their actions, with our verdict and the vendor’s execution outcome per action.
• heron_list_anomalies— the reconciliation findings: where our decision and the vendor’s reported execution disagree.
• heron_get_evidence— the derived AARM and conformance assessment for a project’s evidence, recomputed from the window. Coverage, never a conformance claim.
• heron_list_audit — the signed operator audit chain (admin or owner), actors by pseudonym.
• heron_policy_candidate_report — how a staged policy would have decided, in shadow.

The list tools are paged. Each returns its rows alongside a next_cursor; pass that back as cursor to continue into older rows, and keep the other arguments identical while you do — a cursor names the row you stopped at, not the query you ran. A null next_cursor is the end of the list, which is the point of returning one at all: a bare array cannot tell you whether it was the whole project or the first page of it.

Writes (role-gated, each chained and signed):

• heron_resolve_anomaly — resolve or reopen a finding with a reason (operator+).
• heron_promote_policy — promote the staged policy to active (admin+).
• heron_set_break_glass — suspend or resume enforcement, with a reason (admin+).
• heron_take_snapshot — take an immutable evidence snapshot (operator+).

What an agent here cannot do

It cannot decide anything Heron proves. No tool returns a verdict or an AARM badge — those stay computed from the evidence, so an agent that uses these tools reports facts and drafts claims, and a reviewer still recomputes every status for themselves. And every write runs through the same signed audit chain as a human’s, under your identity: there is no path here that a person using the dashboard does not also have.