OAuth Authorization Server Metadata (RFC 8414) — how to make your site agent-ready

What it is

RFC 8414 defines a JSON document at a well-known URL describing where an OAuth server's /authorize, /token, /revoke, /jwks endpoints live, which grant types and scopes it supports, etc.

For AI agents, this is the key that unlocks scoped, revocable, human-granted access to protected resources. Instead of handing an agent a browser cookie, users walk through a normal OAuth flow and grant the agent narrow, revocable access.

Why it matters

Replaces the hack of "agent uses the user's browser session".
Lets agents perform the OAuth dance without any out-of-band documentation.
Any MCP server or authenticated API can point here.

Remediation Prompt

I want to improve my site's agent readiness. Please implement the following fix for OAuth Authorization Server Metadata (RFC 8414) across our codebase.

Instructions:
Please fix the OAuth Authorization Server Metadata (RFC 8414) issue on my site so it is agent-ready.

How we test it

Step	Method	URL
A	GET	`/.well-known/oauth-authorization-server`
B	GET	`/.well-known/openid-configuration` (fallback if A fails — OIDC's parent spec)

Body cap 128 KB.

Pass Warn Fail Matrix

Condition	Status	Score
A exists, parses, has `authorization_endpoint` + `token_endpoint` + `issuer`	pass	1.0
B exists (OIDC) with the same minimum fields	warn	0.8
Exists but missing required fields	warn	0.4
404	fail	0.0

Sub Tests

id	Weight	Pass when
`metadata-present`	0.5	200 + JSON at A or B
`has-required-fields`	0.5	issuer, authorization_endpoint, token_endpoint

Remediation Prompt

Please expose OAuth Authorization Server metadata at /.well-known/oauth-authorization-server (RFC 8414). The JSON must include at minimum:

    {
      "issuer": "https://auth.example.com",
      "authorization_endpoint": "https://auth.example.com/authorize",
      "token_endpoint": "https://auth.example.com/token",
      "jwks_uri": "https://auth.example.com/.well-known/jwks.json",
      "response_types_supported": ["code"],
      "grant_types_supported": ["authorization_code", "refresh_token"],
      "code_challenge_methods_supported": ["S256"],
      "scopes_supported": ["openid", "profile", "email", "offline_access"]
    }

Also:
- Serve with Content-Type: application/json.
- If you are using OIDC, also expose /.well-known/openid-configuration with the same content.
- Ensure your token endpoint supports PKCE (S256). Agents must use PKCE — they have no way to keep a client secret.

Implementation Examples

Most OAuth servers auto-expose this (Auth0, Clerk, Cloudflare Access, Keycloak, Ory Hydra, WorkOS). If not, a small route handler serving static JSON is fine.

Common Mistakes

issuer not matching the hostname of the well-known URL — RFC 8414 requires it.
HTTP instead of HTTPS on endpoints.
Missing code_challenge_methods_supported → PKCE-only clients (agents) cannot detect support.
Serving at /oauth-authorization-server without the /.well-known/ prefix.

References

Test Fixtures

pass-full.json
pass-oidc-fallback.json
warn-missing-fields.json
fail-404.json

← Previous Check

MCP Server Card

Next Check →

OAuth Protected Resource Metadata (RFC 9728)