OzMcp.Auth.Metadata (OzMcp v0.9.0)

Copy Markdown View Source

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.

Summary

Functions

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

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

Functions

build(auth, resource_url)

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

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

url(resource_url)

@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"