The MCP server complies with OAuth 2.0 Protected Resource Metadata as defined in RFC 9728. This compliance enables clients to discover resource details, authorization servers, and supported token methods automatically. It also improves interoperability and security by exposing metadata endpoints and enhancing error responses.

Automatic endpoint exposure

The MCP server automatically exposes the protected resource metadata /.well-known/oauth-protected-resource endpoint when service_account.enabled=true. This endpoint provides essential details about the resource and its associated authorization servers.

The following example shows the JSON structure returned by the metadata endpoint:
{
  "resource": "https://mcp-server.example.com",
  "authorization_servers": ["https://auth.example.com/realms/myapp"],
  "jwks_uri": "https://auth.example.com/realms/myapp/certs",
  "scopes_supported": ["api.read", "api.write", "admin.access"],
  "bearer_methods_supported": ["header", "body"],
  "resource_documentation": "https://docs.example.com/api/mcp-server",
  "resource_policy_uri": "https://example.com/policies/oauth",
  "revocation_endpoint": "https://auth.example.com/.../revoke",
  "introspection_endpoint": "https://auth.example.com/.../introspect"
}

Enhanced 401 responses

When require_metadata_on_401=true, which is the default value, all 401 Unauthorized responses include a WWW-Authenticate header with a link to the resource metadata. This helps clients discover the metadata and remediate authorization issues. Here is an example of the header:
WWW-Authenticate: Bearer realm="oemcp", 
resource_metadata="https://mcp-server.example.com/.well-known/oauth-protected-resource"

Client discovery flow

The following steps describe how a client discovers and uses resource metadata:
Step Description
Initial request Client attempts to access the resource without a token.
401 response Server returns a WWW-Authenticate header with the metadata URL.
Metadata discovery Client fetches the /.well-known/oauth-protected-resource endpoint.
Authorization server discovery Client uses the authorization_servers field from metadata.
Token acquisition Client obtains an OAuth token from the authorization server.
Retry with token Client retries the original request with a Bearer token.

Configuration parameters

The following table lists key configuration parameters for protected resource metadata:
Parameter Description
bearer_methods_supported Specifies supported token presentation methods such as header, body, or query.
require_metadata_on_401 Determines whether the metadata URL is included in WWW-Authenticate headers.
resource_documentation URL to human-readable API documentation.
resource_policy_uri URL to the token processing policy document.
revocation_endpoint OAuth token revocation endpoint.
introspection_endpoint OAuth token introspection endpoint.