# `AshAi.Mcp.Client.Auth`
[🔗](https://github.com/ash-project/ash_ai/blob/v1.5.6/lib/ash_ai/mcp/client/auth.ex#L5)

Supplies credentials for the requests `AshAi.Mcp.Client` makes to an MCP server.

Configure a server with `auth: {module, opts}`. Before each request the client
calls `c:headers/2`. When the server answers 401 or 403, the client calls
`c:handle_challenge/3`, and retries the request once if it returns `:retry`.

`AshAi.Mcp.OAuth` implements this behaviour for the MCP authorization spec.

# `challenge`

```elixir
@type challenge() :: %{status: 401 | 403, www_authenticate: String.t() | nil}
```

What the server answered when it rejected a request.

`www_authenticate` is the raw `WWW-Authenticate` header, or `nil` when the
server sent none.

# `handle_challenge`

```elixir
@callback handle_challenge(server_url :: String.t(), challenge(), opts :: keyword()) ::
  :retry | {:error, term()}
```

Called when the server rejects a request with 401 or 403.

Return `:retry` after obtaining new credentials (for example by refreshing a
token) and the client retries the request once. Otherwise return
`{:error, reason}`, which the client returns to its caller.

# `headers`

```elixir
@callback headers(server_url :: String.t(), opts :: keyword()) ::
  {:ok, [{String.t(), String.t()}]} | {:error, term()}
```

Headers to add to a request to the MCP server at `server_url`.

Return `{:error, reason}` when no usable credentials exist, for example
`{:error, {:authorization_required, info}}` when the user has to authorize.

---

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