# `OzMcp.Auth.Metadata`
[🔗](https://github.com/oz-elixir/oz_mcp/blob/v0.9.0/lib/oz_mcp/auth/metadata.ex#L1)

Protected Resource Metadata (RFC 9728) of a protected MCP server.

The metadata document tells the client where the authorization servers
of this MCP server are. A client that receives a `401` challenge reads
the `resource_metadata` URL of the `WWW-Authenticate` header, fetches
the document there and learns which authorization server can issue a
token for this MCP server. Its well-known URL is built from the
canonical URL of the MCP endpoint, see `url/1`.

The host application mounts the plug outside the MCP endpoint, because
the well-known URL sits at the root of the host:

    forward "/.well-known/oauth-protected-resource",
      to: OzMcp.Auth.Metadata,
      init_opts: [instance: MyApp.McpServer]

The forward prefix must be the well-known path: for a request to
`/.well-known/oauth-protected-resource/mcp` the plug receives the
segments of the `:resource_url` path (`["mcp"]`). The plug answers
`200` only for those segments, `404` for any other path and for a
server with no authorization and `503` when the instance does not
run. The document is public: no token is checked and the CORS
headers are a wildcard.

Configure `:resource_url` with the public URL of the MCP endpoint and
serve it behind TLS: the clients must be able to fetch this document
and the endpoint at that URL.

The `scopes_supported` field of the document is the value that the
server sets in the `authorization` block. When the server does not
set it, it is the sorted union of the `required_scopes` of the DSL
modules of the server and the field is omitted when that union is
empty.

# `build`

```elixir
@spec build(map(), String.t()) :: map()
```

The RFC 9728 document of the server. Keys with a `nil` value are not
sent.

# `url`

```elixir
@spec url(String.t() | nil) :: String.t() | nil
```

The URL of the Protected Resource Metadata document of the MCP
endpoint, or `nil` when the endpoint has no URL (server with no
authorization).

The well-known path is inserted before the path of the resource URL:

```
OzMcp.Auth.Metadata.url("https://mcp.example.com/mcp")
#=> "https://mcp.example.com/.well-known/oauth-protected-resource/mcp"

OzMcp.Auth.Metadata.url("https://mcp.example.com")
#=> "https://mcp.example.com/.well-known/oauth-protected-resource"
```

---

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