# `AshAi.Mcp.OAuth.Discovery`
[🔗](https://github.com/ash-project/ash_ai/blob/v1.5.6/lib/ash_ai/mcp/oauth/discovery.ex#L6)

Finds an MCP server's authorization server.

Implements the discovery steps of the MCP authorization spec (2026-07-28):
the `WWW-Authenticate` challenge, OAuth 2.0 Protected Resource Metadata
(RFC 9728), and authorization server metadata through RFC 8414 or OpenID
Connect Discovery.

# `challenge`

```elixir
@type challenge() :: %{
  resource_metadata: String.t() | nil,
  scope: String.t() | nil,
  error: String.t() | nil,
  error_description: String.t() | nil,
  params: %{required(String.t()) =&gt; String.t()},
  www_authenticate: String.t()
}
```

The parameters of a `Bearer` challenge.

# `t`

```elixir
@type t() :: %{
  server: String.t(),
  resource: String.t(),
  issuer: String.t(),
  protected_resource: map(),
  authorization_server: map(),
  challenge: challenge() | nil
}
```

What `discover/2` found.

# `authorization_server_metadata`

```elixir
@spec authorization_server_metadata(String.t(), keyword()) ::
  {:ok, map()} | {:error, term()}
```

Fetches and validates the authorization server metadata for `issuer`.

Tries the endpoints the spec lists, in order, and requires the document's
`issuer` to be identical to `issuer`, HTTPS endpoints, and PKCE `S256`
support.

# `authorization_server_metadata_urls`

```elixir
@spec authorization_server_metadata_urls(String.t()) :: [String.t()]
```

The URLs to try for an issuer's metadata, in the spec's priority order.

# `canonical_resource`

```elixir
@spec canonical_resource(String.t()) :: {:ok, String.t()} | {:error, term()}
```

The canonical resource URI of an MCP server (RFC 8707), used as the
`resource` parameter and as the key tokens are stored under.

Lowercases the scheme and host, drops the fragment and a default port, and
drops a bare trailing slash.

# `discover`

```elixir
@spec discover(String.t(), keyword()) :: {:ok, t()} | {:error, term()}
```

Discovers the authorization server for the MCP server at `server_url`.

Uses the `resource_metadata` URL from `:challenge` (a `WWW-Authenticate`
header value or a parsed challenge) when present, and otherwise the
well-known URIs: with path insertion first, then at the root. If neither
exists and no challenge was given, it sends one unauthenticated request to
the server to obtain a challenge.

Uses the first authorization server the metadata lists.

# `parse_www_authenticate`

```elixir
@spec parse_www_authenticate(String.t() | [String.t()] | nil) :: challenge() | nil
```

Parses the `Bearer` challenge out of a `WWW-Authenticate` header.

Accepts one header value or a list of them, and returns `nil` when there is
no `Bearer` challenge.

# `protected_resource_metadata_urls`

```elixir
@spec protected_resource_metadata_urls(String.t()) :: [String.t()]
```

The well-known protected resource metadata URLs for an MCP server, in the
spec's priority order.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
