FastestMCP.Client.OAuth (fastest_mcp v0.2.0)

Copy Markdown View Source

MCP 2025-11-25 OAuth coordinator for Streamable HTTP clients.

The coordinator implements protected-resource and authorization-server discovery, PKCE S256, resource indicators, explicit client registration modes, refresh-token rotation, and scope step-up. Browser interaction remains behind FastestMCP.Client.OAuth.AuthorizationHandler.

Start one coordinator per connected client. The default token store is process-local and non-durable:

{:ok, oauth} =
  FastestMCP.Client.OAuth.start_link(
    redirect_uri: "http://127.0.0.1:8765/callback",
    registration: {:pre_registered, [client_id: "my-client"]},
    authorization_handler: MyApp.OAuthBrowser
  )

The connected client normally invokes this module automatically after a 401 response. Direct calls are useful to hosts that want to authorize eagerly.

Summary

Types

option()
registration()

Functions

authorization_header(server, resource)

Returns a cached/refreshable Bearer header, or :none before authorization.

authorize(server, resource, opts \\ [])

Performs authorization without requiring a preceding 401 response.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

clear(server, resource)

Deletes cached credentials for one resource.

handle_unauthorized(server, resource, response_headers, opts \\ [])

Handles a protected-resource challenge and returns a Bearer header.

start_link(opts)

Starts an OAuth coordinator from explicit client options.

Types

option()

@type option() ::
  {:redirect_uri, String.t()}
  | {:registration, registration()}
  | {:authorization_handler,
     module()
     | (FastestMCP.Client.OAuth.AuthorizationHandler.Request.t() -> term())}
  | {:token_store, {module(), term()}}
  | {:authorization_server, String.t()}
  | {:scopes, [String.t()]}
  | {:requester, (atom(), String.t(), keyword() -> term())}
  | {:timeout_ms, pos_integer()}
  | {:max_body_bytes, pos_integer()}

registration()

@type registration() ::
  {:pre_registered, keyword() | map()}
  | {:client_metadata_document, String.t()}
  | {:dynamic, keyword() | map()}

Functions

authorization_header(server, resource)

@spec authorization_header(GenServer.server(), String.t()) ::
  {:ok, String.t()} | :none | {:error, FastestMCP.Client.OAuth.Error.t()}

Returns a cached/refreshable Bearer header, or :none before authorization.

authorize(server, resource, opts \\ [])

@spec authorize(GenServer.server(), String.t(), keyword()) ::
  {:ok, String.t()} | {:error, FastestMCP.Client.OAuth.Error.t()}

Performs authorization without requiring a preceding 401 response.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

clear(server, resource)

@spec clear(GenServer.server(), String.t()) :: :ok

Deletes cached credentials for one resource.

handle_unauthorized(server, resource, response_headers, opts \\ [])

@spec handle_unauthorized(GenServer.server(), String.t(), list() | map(), keyword()) ::
  {:ok, String.t()} | {:error, FastestMCP.Client.OAuth.Error.t()}

Handles a protected-resource challenge and returns a Bearer header.

start_link(opts)

@spec start_link([option()]) :: GenServer.on_start()

Starts an OAuth coordinator from explicit client options.