What you’re building
In MCP, your server doesn’t sign anyone in. It’s an OAuth 2.1 resource server: it accepts access tokens issued by an authorization server, your own or a provider’s, and checks each one before it does any work. So adding OAuth comes down to four jobs: choose an authorization server that can serve MCP clients, publish where to find it, challenge requests that have no token, and validate the tokens that arrive.
This guide follows the 2026-07-28 revision of the MCP authorization specification. Authorization is optional in the specification, but any remote server that holds private data should have it. It applies to HTTP transports. Local servers on stdio shouldn’t use this flow: they take their credentials from the environment instead.
The MCP OAuth flow
-
The client calls your server with no token. Your server answers
401with aWWW-Authenticateheader that points to its metadata. - The client reads your protected resource metadata (RFC 9728) and finds your authorization server.
-
The client reads that server’s metadata (RFC 8414 or OpenID
Connect discovery). It rejects the metadata if
issuerdoesn’t match, and refuses to continue if PKCE support isn’t listed. - The client identifies itself: pre-registered, by a client ID metadata document, or by dynamic registration.
-
The user signs in through the authorization code flow with PKCE. The client sends your server’s address as
resource(RFC 8707) on both the authorization request and the token request. -
The client checks
stateandisson the response (RFC 9207), then swaps the code for a token. - The client sends
Authorization: Beareron every request, and your server validates the token each time. - If a call needs more access, your server answers
403and the client asks the user for the extra scope.
Your code handles steps 1, 2, 7 and 8. The authorization server handles the rest, which is why choosing one is the first decision.
Step 1: Check your authorization server
MCP asks more of an authorization server than most web apps do, so check before you commit to one. Read its metadata,
at /.well-known/oauth-authorization-server or /.well-known/openid-configuration:
{
"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",
"code_challenge_methods_supported": ["S256"],
"client_id_metadata_document_supported": true,
"authorization_response_iss_parameter_supported": true
}
code_challenge_ methods_ supported -
Must be there and include
S256. If the field is absent, the specification tells clients to refuse to proceed, even if the provider does support PKCE. client_id_metadata_ document_ supported -
The way the specification prefers for clients to identify themselves. Without it, look for
registration_endpoint, which is dynamic client registration. That still works but is deprecated, and without either one, clients you’ve never seen can’t sign in unless the user enters client details by hand. authorization_response_iss_ parameter_ supported -
Says the server sends
isswith its authorization responses, which protects clients from mix-up attacks when they talk to more than one authorization server. The specification says authorization servers should send it. - Audience
-
Metadata won’t tell you this one, so test it. Request a token with
resourceset to your server’s address and look at itsaud, for example in the JWT decoder. Your address has to be there. Some providers set the audience another way, such as Auth0’saudienceparameter or a default on the tenant, and need configuring before they’ll honourresource. - Token lifetimes
- Access tokens should be short-lived, and refresh tokens for public clients must rotate. Most MCP clients are public clients.
Step 2: Publish protected resource metadata
This JSON document is how a client gets from your server to your authorization server. For a server at
https://mcp.example.com/mcp, serve it at
https://mcp.example.com/.well-known/oauth-protected-resource/mcp:
{
"resource": "https://mcp.example.com/mcp",
"authorization_servers": ["https://auth.example.com"],
"scopes_supported": ["files:read"]
}
resource is your server’s canonical address, and authorization_servers is required. Keep
scopes_supported to what a first request needs: a client that gets no scope in the challenge asks for
everything listed here. Don’t list offline_access in it.
The specification also lets clients try the root, /.well-known/oauth-protected-resource, so serve it
there too if the server is the only thing on that host. The official SDKs can serve this document for you: the
MCP Security Checker shows the code for the TypeScript SDK, the Python SDK and
FastMCP.
Step 3: Challenge requests with no token
A request without a valid token gets a 401 that says where to go and what to ask for:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource/mcp",
scope="files:read"
The scope value is optional but worth sending. It’s what lets a client ask for read access first rather
than everything you offer. Send the same challenge for tokens that are invalid or expired.
Step 4: Validate every token
This is the step that makes the rest mean something. On every request, check the signature, issuer, expiry and audience. Here it is with jose:
import { createRemoteJWKSet, jwtVerify } from 'jose';
const RESOURCE = 'https://mcp.example.com/mcp';
const ISSUER = 'https://auth.example.com';
const JWKS = createRemoteJWKSet(new URL(`${ISSUER}/.well-known/jwks.json`));
// Runs on every request. A thrown error means: answer 401 with the challenge above.
export async function verifyAccessToken(authorization: string | undefined) {
const token = authorization?.match(/^Bearer (.+)$/i)?.[1];
if (!token) throw new Error('No bearer token');
const { payload } = await jwtVerify(token, JWKS, {
issuer: ISSUER,
audience: RESOURCE,
algorithms: ['RS256'],
});
return {
subject: payload.sub,
scopes: typeof payload.scope === 'string' ? payload.scope.split(' ') : [],
};
}
Four details decide whether this holds up:
- The audience check is required. The specification says servers must reject any token not issued for them. Without the check, a token your provider issued for another of your APIs works here too. If the check fails, Fixing “jwt audience invalid” covers the usual causes.
-
Addresses compare as exact strings.
https://mcp.example.com/mcpandhttps://mcp.example.com/mcp/are different audiences. Use one form everywhere; the specification prefers no trailing slash. -
Providers differ on scopes. The sample reads the standard
scopeclaim. Some providers usescp, as a string or an array, so check a real token. JWT claims, explained covers the rest. - Not every token is a JWT. If your provider issues opaque tokens, call its introspection endpoint (RFC 7662) instead, and check the audience in the response.
Tokens must arrive in the Authorization header, never the query string. And check on every request:
under the 2026-07-28 revision there’s no protocol session to hang a sign-in on.
Step 5: Design scopes and ask for more only when needed
Sign-in decides who gets in. Scopes decide what an agent can do once it’s there, so give each tool the narrowest scope that fits, and check it when the tool runs:
| Tool | Scope | Requested |
|---|---|---|
search_files | files:read | At sign-in |
save_file | files:write | The first time it’s called |
delete_file | files:delete | The first time it’s called |
When a token lacks the scope a call needs, answer with a 403 challenge:
HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope",
scope="files:read files:write",
resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource/mcp",
error_description="Saving a file requires files:write"
The client adds those scopes to what it already holds and sends the user back to approve them. List every scope the
operation needs in one challenge, so the user is asked once. If one of your scopes implies another, your check has to
respect that. Avoid wildcard scopes such as files:*, which turn one approval into all of them.
Have a tools/list output already? Paste it into the review box on the
checker for a suggested scope per tool, or map them by role with the
RBAC Matrix Builder.
How MCP clients identify themselves
On the web, you register each client with your provider in advance. MCP clients show up unannounced, so the specification gives them an order to try:
- Pre-registered client
- A client ID the client already holds for this authorization server. It’s the simplest choice for an internal server with a known set of clients.
- Client ID metadata document
-
The
client_idis an HTTPS address that serves a JSON document with the client’s name and redirect addresses. The authorization server fetches it, so there’s nothing to register. An authorization server that does this has to guard against server-side request forgery and show users the redirect host. - Dynamic client registration
-
The client registers itself at
registration_endpoint. It’s deprecated and kept for compatibility. If you leave it on, limit who can register and which redirect addresses they can use. - Asking the user
- The fallback when none of these is available: the user enters client details by hand.
If your server calls other APIs
Your server may need to call GitHub, Salesforce or your own back end on the user’s behalf. It must never forward the token it received. Your server acts as an OAuth client to that API and gets a separate token for it, from that API’s authorization server. If you use one shared client ID for all your users, you also need per-client consent, or you have a confused deputy.
Test it
-
Run the MCP Security Checker against your server. It walks the discovery
chain the way a client would, and sends a made-up token and an unsigned one, both of which should get a
401. - Sign in with the MCP Inspector to run the full flow with a real token and call your tools.
-
Send tests only you can run, since they need real tokens: one for another API from the same provider, one expired,
and one missing the scope a tool needs. They should get
401,401and403.
Common MCP OAuth mistakes
- Skipping the audience check, so any token from your provider works.
- Sending an ID token to the server instead of an access token.
- Listing every scope in
scopes_supported, so a client’s first sign-in asks for all of them. - A
resourcevalue that differs from the address clients use, even by a trailing slash. - A provider that supports PKCE but doesn’t publish
code_challenge_methods_supported. - Checking scopes when a connection starts rather than when each tool runs.
- Writing tokens to logs, error messages or URLs.
Sign-in is one part of securing a server. For the rest, read MCP security best practices.