> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.kuudo.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.kuudo.com/_mcp/server.

# AI agents

> Connect Claude Code, Cursor, Codex, or another Agent Auth client to your Kuudo account.

Kuudo can connect directly to an AI coding agent — Claude Code, Cursor, Codex,
or any other client built on the Agent Auth protocol. You approve the
connection once from your browser; after that, your agent can read basic
account and organization details on your behalf. The agent always acts as
you, inside the one organization you approved. It never creates a Kuudo
account of its own or bypasses your sign-in.

## How this maps to the API

The MCP server is a local bridge to Kuudo's Agent Auth HTTP protocol. The same
endpoints serve the CLI and SDK. The [Agent Auth API reference](/api-reference/agent-auth/discover-agent-auth)
documents their parameters, authentication, and responses.

| Action in this guide         | API reference                                                                    | HTTP request                           |
| ---------------------------- | -------------------------------------------------------------------------------- | -------------------------------------- |
| Discover Kuudo               | [Discover Agent Auth](/api-reference/agent-auth/discover-agent-auth)             | `GET /.well-known/agent-configuration` |
| Start a connection           | [Register agent](/api-reference/agent-auth/register-agent)                       | `POST /api/auth/agent/register`        |
| Wait for human approval      | [Get agent status](/api-reference/agent-auth/get-agent-status)                   | `GET /api/auth/agent/status`           |
| See available capabilities   | [List agent capabilities](/api-reference/agent-auth/list-agent-capabilities)     | `GET /api/auth/capability/list`        |
| Inspect capability arguments | [Describe agent capability](/api-reference/agent-auth/describe-agent-capability) | `GET /api/auth/capability/describe`    |
| Read account or organization | [Execute agent capability](/api-reference/agent-auth/execute-agent-capability)   | `POST /api/auth/capability/execute`    |
| Revoke through the SDK       | [Revoke agent](/api-reference/agent-auth/revoke-agent)                           | `POST /api/auth/agent/revoke`          |

`read_account` and `read_organization` are capability names passed to the same
execution endpoint. For `read_organization`, pass the approved `organization_id`
returned by `read_account` in `arguments`. The reference also covers batch
execution, requesting capabilities, key rotation, and reactivation.

The SDK signs fresh Agent Auth JWTs for authenticated protocol requests. These
are separate from the API-key-to-access-token flow in
[Exchange API key](/api-reference/authentication/exchange-api-key). Connecting
an agent does not issue an API key or grant access to the scoped REST API.
Human approval takes place in the browser at the returned approval URL.

## What your agent can do

A connected agent has two read-only capabilities:

* `read_account` returns your account ID, name, email, and the ID of the
  organization you approved.
* `read_organization` returns the name, ID, and slug of the organization you
  approved.

No deployment, billing, credential, or administrative capability is granted.
Every call is scoped to the single organization you chose when you approved
the connection.

## Connect with MCP (Claude Code, Cursor, Codex)

Add Kuudo as an MCP server. It runs `@auth/agent-cli`, pinned to `0.5.1`, as a
local process that bridges your editor or CLI to Kuudo:

```bash
claude mcp add kuudo -- npx @auth/agent-cli@0.5.1 mcp --url https://app.kuudo.com
```

```bash
codex mcp add kuudo -- npx @auth/agent-cli@0.5.1 mcp --url https://app.kuudo.com
```

Cursor doesn't have an add command; add the same server to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "kuudo": {
      "command": "npx",
      "args": ["@auth/agent-cli@0.5.1", "mcp", "--url", "https://app.kuudo.com"]
    }
  }
}
```

Once the server is added, ask your agent to connect to Kuudo. It requests
`read_account` and `read_organization`, and it should give the connection a
`name` (its tool and your project, e.g. `"Claude Code – acme/ads-reporting"`)
and a `reason` describing what the connection is for. You'll see both on the
approval page and later at `/developers/agent-connections`, so a specific
name and reason make it easy to recognize the connection.

## Connect with the CLI

`@auth/agent-cli` also connects without an editor's MCP integration. Kuudo
isn't in the client's default provider directory, so pass `--url` alongside
`--provider` to allow the direct connection:

```bash
npx @auth/agent-cli@0.5.1 connect \
  --provider https://app.kuudo.com \
  --url https://app.kuudo.com \
  --capabilities read_account read_organization \
  --name "Claude Code – acme/ads-reporting" \
  --reason "Read my organization ID for the ads-reporting pipeline" \
  --login-hint you@example.com
```

`--login-hint` is optional; it's shown on the approval page as a hint about
who should approve, never as an authorization check. This opens the approval
link in your default browser; add `--no-browser` to print the link instead.
Once approved, call a capability directly:

```bash
npx @auth/agent-cli@0.5.1 execute <agent-id> read_account
npx @auth/agent-cli@0.5.1 execute <agent-id> read_organization \
  --args '{"organization_id":"<organization-id>"}'
```

## Approve the connection

Your agent registers with Kuudo and gets back an approval link at
`/developers/agent-connections/approve`; depending on your client, it opens
that link in your browser or prints it for you to open.

If you don't have a Kuudo account yet, the page offers to create one first —
sign up, verify your email, and you land back on the same approval request.
If you already have an account, sign in.

Once you're signed in, the page shows what the agent said about itself: its
name, the device it's running on, its stated reason — a claim from the agent
itself, not verified by Kuudo — and the capabilities it's requesting. Pick
the organization to connect it to — you need to be an owner or admin of that
organization — then approve or deny. If the agent's login hint doesn't match
who's signing in, the page warns you before you approve; approving still
connects the agent to your account, not the hinted one.

## Approval links expire in 15 minutes

An approval link stays valid for 15 minutes. Some clients, including
`@auth/agent-cli`, stop waiting for approval after 5 minutes even though the
link is still good for the other 10. If your agent reports a timeout, check
status before reconnecting — the approval may already have gone through:

```bash
npx @auth/agent-cli@0.5.1 status <agent-id>
```

If the link truly expired, ask your agent to reconnect. That registers a new
agent with a new link; the old one can no longer be used.

## One installation, one human

Each local Agent Auth installation — its stored keys and connections — is
meant for one human. The first person who approves a connection from a given
installation becomes its owner. If that same installation later registers
another agent, that agent inherits the same owner automatically, and a
different human trying to approve it is refused. To connect a second person,
have them use their own installation (for example, `--storage-dir` pointed
at a separate folder, or their own machine or account profile) rather than
approving from an installation someone else already owns. Don't use
`force_approval` (an option some clients offer) to switch the installation to
a different person; use a separate installation per person.

## Errors

| Error code                          | Where you see it     | What it means                                                                                                                        |
| ----------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `agent_access_denied`               | Agent or tool output | The connection no longer has access to that organization. Reconnect from your agent.                                                 |
| `organization_not_found`            | Agent or tool output | The requested organization doesn't match the one you approved.                                                                       |
| `agent_access_unavailable`          | Agent or tool output | Kuudo is temporarily unable to serve the request. Retry.                                                                             |
| `agent_revoked`                     | Agent or tool output | The connection was revoked. Reconnect from your agent to start a new one.                                                            |
| `agent_rejected`                    | Agent or tool output | You denied this connection request. Ask your agent to reconnect if you want to approve it.                                           |
| `approval_timeout`                  | Agent or tool output | Your agent's own client stopped waiting before the approval link expired. Run `status` — it may still complete.                      |
| `approval_expired`                  | Approval page        | The approval link's 15-minute window passed before anyone approved it. The page says the link expired; ask your agent for a new one. |
| `capability_request_owner_mismatch` | Approval page        | A different human than the one already linked to this installation tried to approve it. Use a separate installation per person.      |
| `fresh_session_required`            | Approval page        | Your Kuudo sign-in is more than 5 minutes old. Select **Sign in again**; after you sign in, you return to the approval link.         |

The approval page doesn't show these codes. It shows the expiry message for
`approval_expired`; other refusals, such as `capability_request_owner_mismatch`,
appear as a generic "The agent authorization request could not be completed."
message, and `fresh_session_required` adds the **Sign in again** button.

## Revoke a connection

Manage and revoke connections at
[`/developers/agent-connections`](https://app.kuudo.com/developers/agent-connections).
Connections are grouped by device, so you can revoke one agent or every agent
on a device at once. Revocation takes effect immediately — the agent's next
call fails with `agent_revoked`.