# Mercator agent authorization

Mercator exposes an OAuth-protected MCP server. Agents register an OAuth client, ask the user to
authorize access in their browser, and use the resulting bearer token only with the protected MCP
endpoint.

## Discover

1. Read protected-resource metadata at
   `https://mercator.sh/.well-known/oauth-protected-resource/mcp/auth`.
2. Read authorization-server metadata at
   `https://mercator.sh/.well-known/oauth-authorization-server`.
3. Request only the advertised `mercator:tools` scope.

The protected-resource metadata is authoritative if this document and the live metadata differ.

## Register

Register a public OAuth client with `POST https://mercator.sh/oauth/register` using RFC 7591.
Provide the client's exact redirect URI: HTTPS for hosted clients, or HTTP on loopback for native
clients (for example, `http://127.0.0.1:43123/callback`). Use the same URI, including the selected
port and path, during authorization and code exchange. Non-loopback HTTP redirects are not suitable.
Include `authorization_code` and `refresh_token` grant types,
the `code` response type, and `none` as the token endpoint authentication method. Keep the returned
`client_id`; Mercator does not issue a client secret to public clients.

## Authorize

Start an OAuth authorization-code flow at `https://mercator.sh/authorize` with PKCE S256.
The user reviews and approves the wallet capability in their browser. Exchange the returned code at
`https://mercator.sh/oauth/token` with the original PKCE verifier.

## Use the access token

Send `Authorization: Bearer <access_token>` to `https://mercator.sh/mcp/auth`. Refresh through the
advertised token endpoint when the access token expires. Never send a Mercator token to another
origin.

## Errors and recovery

- `invalid_client`: register again or correct the client ID and redirect URI.
- `invalid_grant`: restart authorization; do not replay an expired code or refresh token.
- `invalid_scope`: request only scopes listed by authorization-server metadata.
- HTTP 401 from MCP: follow its `WWW-Authenticate` `resource_metadata` link and reauthorize.

## Revocation

Prefer revoking a connection in [Mercator Account](https://mercator.sh/account): Mercator removes
the OAuth grant first, then asks Tempo Wallet to revoke the same on-chain access key. If the Wallet
step fails or is canceled, Account keeps an explicit retry for the remaining key. Already expired or
revoked keys can be removed without opening Tempo Wallet again.

Revoking only an OAuth token blocks MCP access but cannot sign the on-chain Wallet revocation. The
now-inaccessible access key remains authorized until it expires or is revoked in Tempo Wallet.

See [Mercator documentation](https://mercator.sh/docs) for installation and payment behavior.