OAuth for MCP clients

Flax's built-in OAuth 2.0/2.1 authorization server for MCP clients — discovery, dynamic client registration, authorize, token, and consent

Flax ships an OAuth 2.0/2.1 authorization server so MCP clients can obtain access on behalf of a signed-in user, without you pasting a long-lived token. This is the recommended way to authenticate the hosted MCP endpoint. This page is for developers integrating an MCP or OAuth client.

#When to use OAuth vs. a static token

  • OAuth — interactive clients where a human logs in and consents (for example, a hosted MCP connection in Claude). The client discovers, registers, and negotiates access dynamically.
  • A static token — headless scripts, cron jobs, and the local stdio MCP server. Use a service-account API token instead.

#Discovery

Clients bootstrap from two well-known documents served by your Flax host:

GET /.well-known/oauth-protected-resource
GET /.well-known/oauth-authorization-server

The protected-resource document points at the authorization server; the authorization-server metadata advertises the authorize, token, and registration endpoints below.

#The flow

  1. Register — a client registers dynamically to obtain a client id:

    POST /oauth/register

  2. Authorize — the client redirects the user to /oauth/authorize. Flax authenticates the user and shows a consent step where they approve the client and the requested scopes (read, write).

  3. Token — the client exchanges the resulting authorization code for an access token:

    POST /oauth/token

The issued access token is scoped and authorized exactly like an API token: every call is bounded by the user's scopes and team/row-level-security access.

Note

Consent is required — a newly registered client cannot act until a user approves it at the authorize step.