# auth.md — X1 MCP authentication

X1 MCP supports human-delegated agents through OAuth and manually provisioned X1 API keys. An OAuth client may register through the advertised compatibility endpoint, but registration alone grants no X1 account or data access. A person must sign in, approve the consent screen, and use an approved client callback before the MCP resource server will accept the token.

## Discovery

- MCP resource: `https://mcp.x1wealth.com/mcp`
- Protected Resource Metadata: `https://mcp.x1wealth.com/.well-known/oauth-protected-resource`
- Authorization Server Metadata: `https://clerk.x1wealth.com/.well-known/oauth-authorization-server`
- Credential presentation: `Authorization: Bearer <credential>`

## OAuth method

1. Fetch the Protected Resource Metadata and the advertised Authorization Server Metadata.
2. If the MCP client has no pre-registered client ID or supported client-metadata document, it may use the advertised compatibility `registration_endpoint`. X1 accepts only the documented Claude, ChatGPT, Antigravity, and local loopback callback shapes at the resource boundary.
3. Use Authorization Code with PKCE. A human must sign in to X1 and approve access; the agent must never collect or relay the user's X1 password.
4. Exchange the authorization code at the advertised token endpoint.
5. Send the resulting access token only to `https://mcp.x1wealth.com/mcp` in the `Authorization` header.

## X1 API-key method

Eligible signed-in users can create a read-only or read-and-write key at `https://app.x1wealth.com/settings/api-keys`. This setting is entitlement-gated. The key is shown once and should be stored only in the user's MCP client configuration or an approved secret manager.

Send the key as `Authorization: Bearer x1k_...` to `https://mcp.x1wealth.com/mcp`.

## Scopes and authority

- `mcp:read` permits only the tools and records allowed by current server-side authorization.
- `mcp:write` is not blanket authority. Every write remains subject to its tool-specific target, role, relationship, review, receipt, and current-authorization checks.
- Call `get_user_capabilities` before claiming what can be read, saved, sent, shared, or changed.

## Revocation and recovery

Users can revoke X1 API keys from the API-key settings page. OAuth clients should use the revocation endpoint advertised by the Authorization Server Metadata. On `401 Unauthorized`, discard the rejected credential and restart discovery and authorization.