# Agent integration

Grantor's wedge for AI agents: an agent doesn't need a human to click
through a signup flow, and there is no Grantor server for it to talk to
either. It reads a couple of well-known documents, proves it belongs to its
tenant's on-chain registry, and mints a **deed** — a self-certifying
credential your app verifies directly against the public chain. Distribution
is the agents: any agent toolchain that can fetch a URL, sign a message, and
generate a ZK proof can adopt Grantor with no Grantor process ever involved.

This page is the overview. For the exact copy-paste steps, see [Agent
onboarding](onboarding.md). For the concept-level walkthrough of `agent-zk`
(claims, the origin-provenance vouch, what the verifier checks), see [Agent
tokens (`agent-zk`)](../guide/agent-tokens.md).

## The wedge: agents self-onboard

A human integrating an OAuth provider usually reads a dashboard, creates an
app, and copies a client secret. An agent does the equivalent by reading
machine-first documents instead:

1. Fetch `/llms.txt` or `/llms-full.txt` — a single file with the full
   product model, every deed mode, and the error codes, written for LLMs to
   consume directly.
2. Fetch the relying party's own `/.well-known/grantor-deed` — its
   discovery document: tenant, audience, accepted modes, challenge
   endpoint, chain id/registry, and its origin vouch.

From those two documents alone, an agent (or the harness generating its tool
calls) has everything it needs to build a request: no vendor docs site, no
dashboard, no human in the loop for the runtime flow.

## What still requires a human (once, on-chain)

Self-onboarding covers the *runtime* flow — discovering an app and minting a
deed. It does not make agent enrolment permissionless: a tenant admin still
has to, one time, on the `GrantorRegistry` contract:

1. `createTenant` — create the billing/ownership unit.
2. Fund it and `drawPeriod` so its status is `Active`.
3. `registerZkAgent` (or `registerZkAgentBatch` for several at once) — enrol
   the agent's Semaphore identity commitment in the tenant's on-chain
   membership tree.
4. Sign and publish an **origin vouch** for the app's origin — see
   [Sovereign tier § Origin
   provenance](../sovereign-tier.md#origin-provenance). `ZkAgent.mintDeed`
   refuses before it proves if the origin cannot show one.

Once that's done, any number of deeds from that agent are fully autonomous —
no further human involvement, no per-request approval. Full walkthrough:
[Agent onboarding](onboarding.md).

Prefer not to enrol an agent at all? The permissionless `user-sig` mode
needs no on-chain enrolment — see [Wallet login](../guide/wallet-login.md)
and its `authenticate()` helper.

## Machine entry points

| Path | What it is |
|---|---|
| `/llms.txt` | Machine index: links to every doc, plus the key facts inline. |
| `/llms-full.txt` | The entire product in one file — concepts, every deed mode, discovery, errors, security model. |
| `/.well-known/grantor-deed` | A relying party's own discovery document: tenant, audience, modes, challenge endpoint, chain, origin vouch. Published per-RP, not by Grantor. |

## The self-onboarding loop, in short

```
read discovery (the RP's own /.well-known/grantor-deed)
        │
        ▼
fetch a challenge from the endpoint it names
        │
        ▼
check the origin vouch on-chain, BEFORE signing or proving anything
        │
        ▼
prove ZK membership, bound to the challenge + audience + expiry
(ZkAgent.mintDeed)
        │
        ▼
present the deed to the RP's own API
(X-Grantor-Deed / X-Grantor-Challenge headers)
        │
        ▼
the RP verifies it itself — no Grantor process anywhere in this loop
```

The exact request/response shapes, the origin-provenance vouch, and the
errors to handle are in [Agent onboarding](onboarding.md).

## MCP: planned, not yet shipped

An MCP server for Grantor — so agent toolchains that speak MCP can discover
and use Grantor as a native tool, without an agent having to hand-roll the
discover/challenge/mint calls in onboarding.md — is planned but **does not
exist yet**. Until it ships, the onboarding steps in this section (plain
HTTP, a signature and a ZK proof) are the integration surface. Do not assume
an MCP endpoint is available.

## See also

- [Agent onboarding](onboarding.md) — the exact steps, copy-paste ready.
- [Agent tokens (`agent-zk`)](../guide/agent-tokens.md) — the mode explained
  for humans building or reviewing an integration.
- [Wallet login](../guide/wallet-login.md) — the permissionless `user-sig`
  alternative, for an agent that doesn't need on-chain enrolment.
- [Sovereign tier](../sovereign-tier.md) — the full deed reference.