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.
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_accountreturns your account ID, name, email, and the ID of the organization you approved.read_organizationreturns 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:
Cursor doesn’t have an add command; add the same server to .cursor/mcp.json:
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:
--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:
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:
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
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.