Skip to main content
The Agent Loadout MCP server uses OAuth 2.1. Most clients (Claude Code, Codex CLI, Cursor) handle the entire auth flow automatically when you add the server URL. This page is for client developers and custom integrations that need to implement the flow directly.
If you are an end user connecting a chat client, you don’t need this page. Follow the Connect a client guide instead.

Discovery

Clients discover both the authorization server and the protected resource from these well-known documents:
The resource indicator to include in all token requests is:

Registration

Clients register using a Client ID Metadata Document or dynamic registration. Both paths are supported and described in the authorization server’s discovery document.

PKCE requirement

All authorization code flows must use PKCE with the S256 code challenge method. Plain code challenges are rejected.

Token lifetime

Access tokens expire after 1 hour. Refresh tokens rotate on every use and expire after 90 days without use. Presenting a rotated refresh token again revokes the connection, with one exception: a client that lost the answer to a refresh may retry with the same refresh token within 60 seconds, as long as it has not used the new one. It receives a fresh pair, and the refresh token it never received stops working.
Each authorization creates one agent token that appears in the agent’s Tokens tab in the dashboard. Revoke it there at any time to immediately end the client’s access. Revocation is also available through the standard OAuth revocation endpoint listed in the discovery document.

Scopes

Request only the scopes your integration needs. Tokens are scoped per-agent: a token can only act on the one agent the user selected during authorization. Availability also depends on the capabilities enabled for your workspace and any account grants. A scope alone does not grant access to an unshared app or social account. email:send also requires email:read; wallet:pay also requires wallet:read. Request both scopes explicitly. Vault use and write require vault:metadata. Compute permissions follow compute:admin → compute:run → compute:read; compute:run does not grant admin access. Phone sending requires phone:read, and social posting requires social:read. Sharing the accountable owner with an app requires identity:sign_in alongside identity:share_owner.
Request the narrowest set of scopes that covers your use case. Users see the requested scopes on the consent screen, and narrower tokens are easier to audit and revoke.

Example authorization flow

1

Fetch discovery documents

Retrieve https://agent-loadout.com/.well-known/oauth-authorization-server to get the authorization_endpoint, token_endpoint, and registration_endpoint.
2

Register your client

For dynamic registration, POST client metadata to the registration_endpoint and use the returned client_id. Alternatively, host an HTTPS Client ID Metadata Document and use its URL as client_id; that path does not require dynamic registration.
3

Generate a PKCE pair

Generate a cryptographically random code_verifier (43–128 chars). Compute code_challenge = BASE64URL(SHA256(code_verifier)).
4

Redirect to the authorization endpoint

Include response_type=code, client_id, redirect_uri, scope, state, code_challenge, code_challenge_method=S256, and resource=https://agent-loadout.com/api/mcp.
5

Exchange the code for tokens

POST to the token_endpoint with grant_type=authorization_code, code, redirect_uri, client_id, code_verifier, and resource.
6

Use and refresh

Include the access token as Authorization: Bearer <token> on every request. Use the refresh token to obtain a new access token before it expires.