OAuth discovery: telling an agent how to sign in without a human

401 is a dead end unless you say where the door is

Public content is only part of what an agent might need. Checking an order, reading account data, calling a metered API: all of these require identity. A person handles the 401 by finding the login page. An agent needs the same information in a form it can act on: which authorization server, which scopes, which flow. Without that, the agent reports 'this requires login' and the task ends.

The pieces exist. RFC 8414 defines authorization-server metadata at /.well-known/oauth-authorization-server: endpoints, supported grant types, PKCE methods. RFC 9728 defines protected-resource metadata at /.well-known/oauth-protected-resource: which authorization servers protect this resource and which scopes it accepts. The MCP authorization specification builds on exactly these two documents, which is why they appear on agent-readiness checklists.

The two documents

{
  "resource": "https://api.brand.ch/",
  "authorization_servers": ["https://auth.brand.ch/"],
  "scopes_supported": ["orders:read", "stock:read"],
  "bearer_methods_supported": ["header"],
  "resource_documentation": "https://developers.brand.ch/auth"
}

{
  "issuer": "https://auth.brand.ch/",
  "authorization_endpoint": "https://auth.brand.ch/authorize",
  "token_endpoint": "https://auth.brand.ch/token",
  "registration_endpoint": "https://auth.brand.ch/register",
  "scopes_supported": ["orders:read", "stock:read"],
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"]
}

• The 401 should point at the metadata. RFC 9728 specifies a resource_metadata parameter in the WWW-Authenticate header so the client does not even need to know the well-known path.
• PKCE and dynamic client registration matter for agents. An agent host cannot pre-register with every site. registration_endpoint (RFC 7591) and S256 are what let it obtain a client identity on the fly; the MCP spec requires PKCE and recommends dynamic registration.
• Scopes should be narrow and named for what they allow. orders:read tells the user what they are consenting to when the host shows the consent screen.
• OpenID Connect discovery (/.well-known/openid-configuration) is the same idea with a different path; if you run OIDC, publishing both is cheap.

auth.md, for letting an agent register a user

The RFC metadata assumes the user already has an account. auth.md, an open protocol authored by WorkOS, covers the step before that: a Markdown file at your domain that tells an agent how to register a user on their behalf without the sign-up form. It lists the supported flows (agent verified, where the agent's identity provider vouches for the user, or user claimed, where the user confirms a code), the scopes that exist and how to register. It composes existing standards, RFC 9728 protected-resource metadata and identity assertions, and the credential issued at the end is a normal scoped, short-lived OAuth token. Cloudflare's readiness scanner lists it under Protocol Discovery.

The exact file format is specified in the protocol's GitHub repository and is still evolving, so generate it from the published schema rather than from memory. The point for readiness is the same as for the RFC documents: an agent that wants to act for a user finds a machine-readable statement of how, at a predictable path.

What Qomvia checks

OAuth discovery for agents under Agent protocols passes when any of /.well-known/oauth-authorization-server, /.well-known/oauth-protected-resource or /.well-known/auth.md returns 200, and lists which. It is 1 point. Sites with no authenticated surface at all lose that point, which is intended: the protocols dimension is low-weight so that a purely public site is not punished, but a site with an API should be able to tell an agent how to use it. If you publish an MCP discovery document that says authentication: oauth, this is where it should point.

Questions

We only have API keys, no OAuth. What should we publish?

Document the key flow in your OpenAPI securitySchemes and on a page linked from llms.txt. The check itself looks for OAuth metadata or auth.md, so a key-only API will not pass it; the protocols dimension is low-weight for exactly this case.

Is exposing the authorization-server metadata a security risk?

No. It lists public endpoints and supported methods, all of which a client learns anyway on first use. Secrets never appear in it.

Does this replace the login page?

No. The authorization endpoint still shows a person a consent screen. Discovery is about getting the agent to that screen without a human finding it first.