Authorization
How the ATP MCP server verifies tokens, which scopes exist, and how per-application gates work.
Not deployed
The ATP MCP server is an OAuth resource server. It checks every bearer token itself and decides which tools the caller may use. It never issues tokens. Authorization here answers one question only: may this client call this tool? Whether an action is allowed on chain is decided by other layers, described in the overview.
Scopes
Scope matching is exact. No scope implies another, and there are no wildcards.
| Scope | Allows | Also needs |
|---|---|---|
atp:read | atp_get_atom, atp_get_delegation_session, atp_get_execution_attempt, atp_get_execution_result | Nothing |
atp:preflight | atp_simulate_authorized_action | Operator gate ATP_MCP_PREFLIGHT_ENABLED_APPS |
atp:execute | atp_request_authorized_execution | Operator gate ATP_MCP_EXECUTION_ENABLED_APPS |
OAuth scopes are not ATP action bits. A scope never grants cancel, dispute, filing, governance or arbitration rights, and a token never creates an on-chain session. See the Tool reference for the tool behind each scope.
Token requirements
The server validates RFC 9068 JWT access tokens locally and does not call an introspection endpoint.
| Requirement | Detail |
|---|---|
| Format | Compact JWT, at most 12000 characters. The typ header is absent, at+jwt, application/at+jwt or jwt. ID tokens are refused. |
| Signature | Asymmetric algorithms only, limited to ATP_MCP_AUTH_ALGORITHMS (default ES256,RS256,EdDSA). none and HS* are refused. Keys come only from ATP_MCP_AUTH_JWKS_URL. |
| Issuer | iss equals ATP_MCP_AUTH_ISSUER exactly. |
| Audience | aud contains the resource URL. Request the token with the resource indicator (RFC 8707). |
| Time | exp and sub are required. Clock tolerance is 30 seconds. exp may be at most 24 hours ahead. |
| Client | client_id or azp is required, and the id must be in ATP_MCP_CLIENTS. |
| Scopes | scope (space-delimited) or scp (array), not both. |
The server refuses tokens in the URL query, a second Authorization header, and any scheme other than Bearer. It never forwards your token to an application backend.
Protected resource metadata
The server publishes RFC 9728 metadata at /.well-known/oauth-protected-resource/<resource path>. It lists the resource URL, authorization_servers (your configured issuer), scopes_supported, and bearer_methods_supported: ["header"]. The server does not host or proxy authorization-server metadata. Your issuer must publish its own discovery document.
An unauthenticated request gets 401 with WWW-Authenticate: Bearer resource_metadata="...", which is how a client finds the metadata.
Per-application gates
The application a caller belongs to comes only from the server-side registry in ATP_MCP_CLIENTS:
{ "my-client": { "application": "sinera" } }The values are sinera or dashboard. No token claim, header or tool argument can change it. A valid token from an unregistered client is rejected with HTTP 403, and an empty registry denies every token.
Two gates control the risky tools, one list per gate:
| Gate | Variable | Default |
|---|---|---|
| Preflight | ATP_MCP_PREFLIGHT_ENABLED_APPS | Off |
| Execution | ATP_MCP_EXECUTION_ENABLED_APPS | Off |
Gates are read at startup and change only by restart. A gate that errors denies. Turning a gate on does not grant ATP authority, because the application backend still decides every request on its own. A listed application must also have a configured backend, or the server will not start.
HTTP responses
Rejections use a JSON-RPC body with a stable reason code. No token content or claim value is echoed.
| Situation | Status | Reason codes |
|---|---|---|
| No credentials | 401 | TOKEN_MISSING |
| Bad header or token in the query | 401 | TOKEN_IN_QUERY, AUTHORIZATION_HEADER_MULTIPLE, AUTHORIZATION_HEADER_MALFORMED, AUTHORIZATION_SCHEME_UNSUPPORTED |
| Invalid token | 401 | TOKEN_MALFORMED, TOKEN_EXPIRED, TOKEN_ISSUER_INVALID, TOKEN_AUDIENCE_INVALID, TOKEN_SIGNATURE_INVALID, TOKEN_ALGORITHM_REJECTED, and related TOKEN_* codes |
| Client not registered | 403 | CLIENT_NOT_REGISTERED |
| None of the three scopes | 403 | SCOPE_INSUFFICIENT (insufficient_scope challenge) |
| Key set unreachable | 503 | AUTH_UNAVAILABLE |
| Rate limit | 429 | RATE_LIMITED (Retry-After: 60) |
A tool denial, such as the wrong scope for one tool or a gate that is off, is a tool result with isError: true (FORBIDDEN / INSUFFICIENT_SCOPE, BLOCKED_POLICY / PREFLIGHT_DISABLED or EXECUTION_DISABLED). A client that needs more scope should authorize again with it.
Setting up your authorization server
| Item | Requirement |
|---|---|
| Resource | Register the MCP server's URL as an audience with the three scopes. |
| Keys | Publish a stable issuer and an https JWKS with asymmetric keys. Rotate by adding new kid values. |
| Clients | Register each MCP client, then put its client_id in ATP_MCP_CLIENTS. Public clients should use authorization code with PKCE. |
| Lifetimes | Keep them short. The server rejects tokens valid for more than 24 hours. |
| Revocation | The server does not check revocation before exp. Use short lifetimes and remove clients from the registry. |
This flow has only been tested with locally minted tokens, not with a real authorization server.