# Agents

> An agent is an AI client a person connected to their documents on your platform, acting for that person alone.

An **agent** is an AI client, such as Claude Code, Codex or any other MCP client, that one of your users approved to work in their documents. It reads, writes, suggests and comments through Proof's MCP server, and everything it writes is credited to it. An agent acts for exactly one person on one platform.

## Your MCP address

Each platform has its own MCP server address, made from your slug:

```text
https://mcp.proof.exalto.ai/acme
```

In test mode it ends `/test`, and reaches your test data. You show this address in your product, usually on a settings screen with a ready-made command or install link for each kind of agent. An agent needs nothing else: from the address, it finds Proof's sign-in, registers itself and asks its person to approve it.

An agent's tokens work only at the address they were issued for. Someone who uses two platforms built on Proof connects their agent to each separately. Agent clients keep tools from different servers apart, so the two connections sit side by side.

## Approving an agent

Proof has no accounts, so the approval step happens on your site:

1. The agent asks Proof to connect, and Proof sends the person's browser to your **consent URL** with a request id.
2. Your page signs the person in if needed and fetches the request: the agent's name and its verified domain, such as "Claude Code (claude.ai)".
3. The person allows or denies it. Your server tells Proof which user it is, and which documents the agent may reach.
4. Proof finishes the connection and issues the agent's tokens straight to the agent.

Your platform never holds an agent's tokens, so it can't act as the agent, and the agent's name comes from the agent's own registration, not from you. [Connect agents](/guides/connect-agents/) walks through building the consent page.

:::note
An agent's domain is checked: it's where the agent's own metadata document lives, or where it sends people back to. Two agents can share a name; the domain tells them apart.
:::

## What an agent may reach

An agent's access is one of two kinds:

| Access | The agent reaches |
| --- | --- |
| `all` | Every document its person can open, by membership or by link, editing at most. The default. |
| `chosen` | Only the documents its person gave it a role in: `editor`, `suggester` or `viewer`. |

Whichever it is, an agent can do at most what its person can do right now. Proof checks the lower of the agent's grant and the person's current role on every call, so when Ada loses access to a document, Ada's agents lose it too. Agents never own documents and never get more than `editor`.

An agent can also start documents for its person. They're owned by the person, with the agent as an editor, and Proof sends you `document.created` so the document shows up in your lists.

## Suggesting by default

Agents are told to propose changes as suggestions unless their person asked them to edit directly. Where an agent may only suggest, every edit it makes becomes a suggestion anyway. People accept or reject each one in the editor; an accepted suggestion an agent wrote counts as [AI](/concepts/provenance/) until a person changes its words.

## Credit

Every word an agent writes, every comment and every read is recorded under the agent, with its person's name beside it:

```text
Claude Code (Ada Lovelace's agent)
```

The agent's name is the one it registered with, which its person saw when approving it. The person's name is their current one, so it updates when you rename the user. The breakdown behind a seal lists each agent's reads and edits.

## What agents can do

Agents work through Proof's tools: listing and searching documents, reading them as Markdown, editing blocks and text, accepting and rejecting suggestions, commenting, mentioning people, and handling images. The [MCP tools reference](/reference/mcp/) lists them all.

Proof's tools cover what's inside documents. Folders, pins and anything else your product keeps for itself aren't there. If you want agents to reach those, register tools of your own, which Proof's server lists beside its own and forwards to your server; see [Add your own agent tools](/guides/your-own-agent-tools/).

When an agent and a person write in the same document at once, people's edits always go first. Each agent request gets a short slice of work at a time, so a burst of agent edits never holds typing back.

## Removing an agent

`DELETE /v1/agents/{agent_id}` removes an agent and revokes its tokens at once. Its words stay in documents, still credited to it. People usually do this from a list of their agents in your settings, which `GET /v1/users/{user_id}/agents` provides. Proof sends `agent.connected` and `agent.revoked`, so the list stays current however an agent arrives or leaves.

Deleting a user revokes their agents. [Merging](/concepts/users/) a user moves their agents to the user they join.

## Related

- [Connect agents](/guides/connect-agents/)
- [Agents reference](/reference/api/agents/) and [Agent requests reference](/reference/api/agent-requests/)
- [MCP tools](/reference/mcp/)