> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agent-loadout.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP OAuth 2.1 — Authenticate Your AI Client with PKCE

> How MCP clients authenticate with Agent Loadout using OAuth 2.1 with PKCE — discovery documents, token lifetimes, and all available scopes.

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.

<Note>
  If you are an end user connecting a chat client, you don't need this page. Follow the [Connect a client](/api-reference/mcp/overview) guide instead.
</Note>

## Discovery

Clients discover both the authorization server and the protected resource from these well-known documents:

```
https://agent-loadout.com/.well-known/oauth-authorization-server
https://agent-loadout.com/.well-known/oauth-protected-resource/api/mcp
```

The resource indicator to include in all token requests is:

```
https://agent-loadout.com/api/mcp
```

## 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

<Info>
  Access tokens expire after **1 hour**. Refresh tokens rotate on every use and expire after **90 days without use**.
</Info>

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.

| Scope            | What it grants                                                                 |
| ---------------- | ------------------------------------------------------------------------------ |
| `email:read`     | List and read messages, threads, drafts, attachments, and inbox events         |
| `email:send`     | Send, reply, forward, manage mailbox folders, sender rules, and drafts         |
| `vault:metadata` | List the agent's credentials without values                                    |
| `vault:use`      | Read agent-readable credential values and TOTP codes                           |
| `vault:write`    | Create and update the agent's own credentials                                  |
| `wallet:read`    | View payment cards, spending rules, and card activity (feature-flagged)        |
| `wallet:pay`     | Reveal card details for an authorized purchase (feature-flagged)               |
| `compute:read`   | List machines and read files on them (feature-flagged)                         |
| `compute:run`    | Start, stop, and resume machines; run commands; expose ports (feature-flagged) |
| `compute:admin`  | Delete machines and open the machine desktop (feature-flagged)                 |

<Tip>
  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.
</Tip>

## Example authorization flow

<Steps>
  <Step title="Fetch discovery documents">
    Retrieve `https://agent-loadout.com/.well-known/oauth-authorization-server` to get the `authorization_endpoint`, `token_endpoint`, and `registration_endpoint`.
  </Step>

  <Step title="Register your client">
    POST a Client ID Metadata Document to the `registration_endpoint`, or use your pre-registered `client_id` if you have one.
  </Step>

  <Step title="Generate a PKCE pair">
    Generate a cryptographically random `code_verifier` (43–128 chars). Compute `code_challenge = BASE64URL(SHA256(code_verifier))`.
  </Step>

  <Step title="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`.
  </Step>

  <Step title="Exchange the code for tokens">
    POST to the `token_endpoint` with `grant_type=authorization_code`, `code`, `redirect_uri`, `client_id`, `code_verifier`, and `resource`.
  </Step>

  <Step title="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.
  </Step>
</Steps>