Adding OAuth to an MCP server.

Your MCP server doesn’t sign anyone in. It checks tokens from an authorization server. Here’s how to choose that server, publish the metadata clients need, validate tokens and design scopes.

By the NestedBit team · Updated

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

  1. The client calls your server with no token. Your server answers 401 with a WWW-Authenticate header that points to its metadata.
  2. The client reads your protected resource metadata (RFC 9728) and finds your authorization server.
  3. The client reads that server’s metadata (RFC 8414 or OpenID Connect discovery). It rejects the metadata if issuer doesn’t match, and refuses to continue if PKCE support isn’t listed.
  4. The client identifies itself: pre-registered, by a client ID metadata document, or by dynamic registration.
  5. 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.
  6. The client checks state and iss on the response (RFC 9207), then swaps the code for a token.
  7. The client sends Authorization: Bearer on every request, and your server validates the token each time.
  8. If a call needs more access, your server answers 403 and 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 iss with 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 resource set to your server’s address and look at its aud, for example in the JWT decoder. Your address has to be there. Some providers set the audience another way, such as Auth0’s audience parameter or a default on the tenant, and need configuring before they’ll honour resource.
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/mcp and https://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 scope claim. Some providers use scp, 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:

ToolScopeRequested
search_filesfiles:readAt sign-in
save_filefiles:writeThe first time it’s called
delete_filefiles:deleteThe 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_id is 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

  1. 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.
  2. Sign in with the MCP Inspector to run the full flow with a real token and call your tools.
  3. 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, 401 and 403.

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 resource value 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.

Free tool · No sign-up

MCP Server Security Checker

Check an MCP server's sign-in, discovery and tools for security gaps, with code to fix each one.

Starts with a free 30-minute intro call, or email hello@nestedbit.com.