If you're building on the Model Context Protocol (MCP) and trying to get your authorization flow right, the authorization server metadata document is where everything starts. Get it wrong and your agent either can't acquire tokens or silently bypasses consent — neither of which is acceptable in production AI systems.
What Is MCP Authorization Server Metadata?
MCP authorization server metadata is a standardized JSON document that describes how an authorization server behaves. It's modeled directly on RFC 8414 — the OAuth 2.0 Authorization Server Metadata specification — and exposed at a well-known discovery endpoint so MCP clients and servers can configure themselves automatically without hardcoded URLs.
When an MCP server needs to delegate user authorization, it fetches this document to learn which endpoints to use, which grant types are supported, and what token capabilities are available.
Key Fields in the Metadata Document
A conforming metadata document includes a set of required and optional fields. The ones that matter most for MCP agent flows:
issuer— The authorization server's canonical identifier. Tokens issued must match this value.authorization_endpoint— Where users are sent to grant or deny consent.token_endpoint— Where agents exchange authorization codes (or other credentials) for access tokens.jwks_uri— The URL of the JSON Web Key Set used to verify signed tokens at runtime.response_types_supported— Declares which OAuth response types (e.g.,code,token) the server accepts.grant_types_supported— Lists supported grant types:authorization_code,client_credentials,refresh_token, etc.scopes_supported— The permission scopes your agent can request on a user's behalf.token_endpoint_auth_methods_supported— How clients authenticate at the token endpoint (e.g.,client_secret_basic,private_key_jwt).code_challenge_methods_supported— PKCE support; critical for public clients like browser-based or CLI agents.
Missing or incorrect values in any of these fields will cause client discovery to fail or produce tokens that agents can't reliably verify.
How MCP Servers Discover Authorization Metadata
MCP follows OAuth 2.0's discovery convention. A client appends /.well-known/oauth-authorization-server (or /.well-known/openid-configuration for OIDC-compatible servers) to the issuer base URL and performs an HTTP GET.
For example, if your authorization server is https://auth.example.com, the discovery endpoint is:
GET https://auth.example.com/.well-known/oauth-authorization-server
The response is a JSON object containing all the fields listed above. MCP clients cache this document and use it to bootstrap the full auth flow — selecting endpoints, validating issuer claims in tokens, and constructing authorization requests with the correct parameters.
Key operational points:
- The document must be served over HTTPS with a valid certificate.
- The
issuerfield must exactly match the base URL used to discover the document. - The document should be served with appropriate cache headers; stale metadata can break token validation after key rotation.
Why Authorization Metadata Matters for Agent Consent
Authorization server metadata isn't just infrastructure plumbing — it's the specification layer that governs whether a user's consent decision is actually enforced. For AI agent builders, this creates a direct link between the metadata document and real compliance obligations.
When an agent takes an action on a user's behalf — sending an email, modifying a file, calling an external API — that action should only happen if:
- The user explicitly approved it (consent was granted).
- The approval is cryptographically verifiable (a signed token proves it).
- The scope of approval matches the scope of the action.
The authorization server metadata document defines the mechanism that makes all three points possible. Without it, there's no reliable discovery path, which means agents fall back to hardcoded assumptions — a pattern that breaks at scale and fails audits.
Linking Consent Grants to Authorization Server Tokens
Consent and authorization tokens need to be traceable to the same root event. When a user approves an agent action, that approval should produce a token (or be linked to one) that the agent presents at runtime. The authorization server's jwks_uri is what allows your agent to verify the token's signature without calling back to the server on every request.
In well-designed MCP agent systems, the consent record and the issued token share a correlation ID. This means your audit trail can answer: "Was this token issued as a result of explicit user consent, and has that consent since been revoked?"
This is exactly the gap that purpose-built consent infrastructure fills — connecting the user-facing approval moment to the cryptographic token that proves it.
Common Implementation Gaps in MCP Auth Flows
Even developers who implement the metadata document correctly often leave gaps in the surrounding flow:
- No PKCE enforcement — Skipping
code_challenge_methods_supportedleaves public clients vulnerable to authorization code interception. - Mismatched issuer claims — The
issuerin the metadata doesn't match theissclaim in issued tokens, causing verification failures. - Missing scope granularity — Declaring only broad scopes makes it impossible to issue minimally-scoped tokens per action.
- No revocation endpoint — Without
revocation_endpointin the metadata, there's no standardized way to invalidate consent after the fact. - Audit trail gaps — Tokens are issued without any linkage to the original consent event, making compliance reconstruction impossible.
How Permitly Sits Between Your MCP Server and Auth Metadata
Permitly is consent infrastructure designed specifically for AI agent builders, including MCP authors who need a compliant, auditable consent layer without building it from scratch.
When you integrate Permitly, it doesn't replace your authorization server — it sits in front of the user-facing consent moment. Your MCP server directs the user to Permitly's hosted consent screen, where the approval or denial is captured and logged. Permitly then issues a signed consent JWT that your agent verifies at runtime before taking any action.
This maps cleanly onto the MCP authorization metadata model:
- Permitly's consent JWTs are verifiable via a published
jwks_uri. - Every approval, decline, and revocation is written to an immutable audit log.
- The consent record is scoped to the specific action the agent requested — not a blanket permission grant.
For MCP server authors, this means you can advertise the correct scopes_supported in your authorization metadata, knowing that Permitly will enforce scope-level consent before a token is honored.
Getting a Signed Consent JWT Your Agent Can Verify
You redirect the user to Permitly's hosted consent screen with the requested scope and action context. After the user approves, Permitly returns a signed JWT your agent checks before proceeding:
import permitly
# Request consent for a specific agent action
consent_url = permitly.request_consent(
user_id="usr_123",
scope="email:send",
action_description="Send a weekly summary email on your behalf"
)
# Redirect user to consent_url, receive JWT on callback
The returned JWT includes the approved scope, timestamp, and a signature your agent verifies against Permitly's public keys — the same pattern enforced by MCP authorization server metadata, now applied to consent specifically.
FAQ
Does MCP require a specific authorization server, or can I bring my own? MCP doesn't mandate a specific server. It requires RFC 8414-compliant metadata discovery. You can use any conforming authorization server or layered consent infrastructure like Permitly.
What's the difference between the authorization server metadata and a JWT? The metadata document describes the server's capabilities and endpoints. A JWT is a token issued by that server. The metadata tells clients where to go; the JWT proves an authorization decision was made.
Can Permitly's consent JWTs be used alongside an existing OAuth server? Yes. Permitly issues consent-specific JWTs that complement — not replace — your existing access tokens.