Skip to navigation

AI agents

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 documents their parameters, authentication, and responses.

Action in this guideAPI referenceHTTP request
Discover KuudoDiscover Agent AuthGET /.well-known/agent-configuration
Start a connectionRegister agentPOST /api/auth/agent/register
Wait for human approvalGet agent statusGET /api/auth/agent/status
See available capabilitiesList agent capabilitiesGET /api/auth/capability/list
Inspect capability argumentsDescribe agent capabilityGET /api/auth/capability/describe
Read account or organizationExecute agent capabilityPOST /api/auth/capability/execute
Revoke through the SDKRevoke agentPOST /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. 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:

claude mcp add kuudo -- npx @auth/agent-cli@0.5.1 mcp --url https://app.kuudo.com
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:

{
"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:

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:

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.

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:

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 codeWhere you see itWhat it means
agent_access_deniedAgent or tool outputThe connection no longer has access to that organization. Reconnect from your agent.
organization_not_foundAgent or tool outputThe requested organization doesn’t match the one you approved.
agent_access_unavailableAgent or tool outputKuudo is temporarily unable to serve the request. Retry.
agent_revokedAgent or tool outputThe connection was revoked. Reconnect from your agent to start a new one.
agent_rejectedAgent or tool outputYou denied this connection request. Ask your agent to reconnect if you want to approve it.
approval_timeoutAgent or tool outputYour agent’s own client stopped waiting before the approval link expired. Run status — it may still complete.
approval_expiredApproval pageThe 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_mismatchApproval pageA different human than the one already linked to this installation tried to approve it. Use a separate installation per person.
fresh_session_requiredApproval pageYour 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. 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.