Locus product guide · Updated November 10, 2026

MCP OAuth: how MCP server authentication works

An MCP server on HTTP authenticates clients with OAuth 2.1. An unsigned request gets HTTP 401 with a link to the server’s protected resource metadata (RFC 9728). The client finds the authorization server, registers with a Client ID Metadata Document, signs the user in with Authorization Code plus PKCE and a resource parameter, then sends a bearer token on every request. Local stdio servers read credentials from the environment instead.

How does MCP OAuth work, step by step?

The flow below follows the 2026-07-28 authorization spec. The MCP server is an OAuth resource server. The authorization server can be the same service or a separate one.

How does MCP OAuth work, step by step?
Step	What happens
1. Challenge	The client calls the server with no token. The server answers 401 with a WWW-Authenticate header that holds a resource_metadata URL and, usually, the scopes it needs.
2. Resource metadata	The client fetches the protected resource metadata. It names one or more authorization servers.
3. Server metadata	The client fetches the authorization server metadata from its well-known URL. If the issuer in the document does not match exactly, the client must not use it.
4. Client ID	The client uses a pre-registered ID, a Client ID Metadata Document, or dynamic client registration, in that order.
5. Browser sign-in	The client opens the browser with a PKCE challenge, the scopes, and a resource parameter that names the MCP server.
6. Code exchange	The user approves. The client checks the iss value in the redirect against the issuer it recorded, then trades the code for tokens.
7. Calls	Every request sends Authorization: Bearer with the access token. Tokens never go in the URL.

What does a real MCP OAuth handshake return?

These values come from the live Locus Pro MCP server, read on November 10, 2026. An unsigned POST to https://api.paywithlocus.com/api/credits/mcp returned 401 with this challenge: Bearer resource_metadata="https://api.paywithlocus.com/.well-known/oauth-protected-resource/api/credits/mcp", scope="mcp:read mcp:execute".

What does a real MCP OAuth handshake return?
Field	Value returned
Protected resource	https://api.paywithlocus.com/api/credits/mcp
Authorization server (issuer)	https://api.paywithlocus.com/api/credits/mcp/oauth
Resource scopes	mcp:read, mcp:execute
client_id_metadata_document_supported	true
Dynamic registration endpoint	Present
PKCE methods	S256 only
Grant types	authorization_code, refresh_token, device code
Token endpoint client auth	none (public clients, no secret)
authorization_response_iss_parameter_supported	true

Which client registration method should a client use?

A client needs a client ID before it can start sign-in. The spec defines three ways to get one. Clients that support all three try them in the order below.

Which client registration method should a client use?
Method	How it works	Status in 2026-07-28
Pre-registration	The client already holds a client ID for that authorization server, hard-coded or typed in by the user	Clients should support it. It is first in priority when available.
Client ID Metadata Document	The client_id is an HTTPS URL. The server fetches a JSON document there with client_id, client_name and redirect_uris.	Recommended. It works across authorization servers with no re-registration.
Dynamic client registration (RFC 7591)	The client POSTs its details to a registration endpoint and gets an ID back	Deprecated. Kept for servers without metadata document support. Clients must send an application_type.

What are the most common MCP OAuth mistakes?

Each of these breaks sign-in or weakens security.

Token passthrough. A server must reject tokens issued for other services and must not forward them downstream.
Wrong resource value. The resource must be the server’s canonical URI. On Locus Pro the transport URL can carry ?surface=compact, but the OAuth resource is the bare URL.
Asking for every scope. Request the scopes in the 401 challenge first. A server that needs more returns 403 insufficient_scope with the scopes to add.
Redirect URI mismatch. Many servers compare redirect URIs as exact strings, so a localhost callback and a 127.0.0.1 callback do not match.
A static Authorization header in the client config. Claude Code treats a configured header as the server’s credential and does not fall back to OAuth.
Skipping the iss check. Since 2026-07-28 clients must compare a returned iss to the recorded issuer before redeeming the code.
Trusting any authorization URL. Clients must allow only https, or http on loopback, and reject javascript: or data: URLs.

How do headless agents and companies sign in to MCP servers?

Browser sign-in does not suit every caller. Three options cover the gaps.

Device authorization (RFC 8628): the client shows a code and link, a person approves on any device, and the client polls for tokens. Locus Pro supports it.
OAuth client credentials extension (io.modelcontextprotocol/oauth-client-credentials): a service signs in with its own client secret or a signed JWT, with no user. Support varies by client.
Enterprise-managed authorization extension: the company identity provider decides which MCP servers each employee may use, and issues an ID-JAG token the server trades for an access token. Okta, Ping Identity and Descope list support for both issuing and accepting these tokens.

AI agent governance controls

How does Locus Pro use MCP OAuth?

Each person signs in once in the browser. The MCP client stores and refreshes the tokens. Access tokens last 15 minutes and refresh tokens rotate.

The two scopes split discovery from spending. mcp:read covers search, describe, results, call history and balance, all free. mcp:execute adds paid calls. A read-only connection cannot spend.

A connected app can also get its own monthly budget, set at sign-in or later, and calls can carry a max_credits ceiling. Example prices: Hunter email finder costs 1 to 10.1 credits and Firecrawl search costs 1.7 credits, where 1,000 credits equal $1. Prices checked November 10, 2026.

Which auth method fits my MCP server?

Pick by who calls the server and where it runs.

Public remote server for many users: OAuth 2.1 with Client ID Metadata Documents, plus dynamic registration as a fallback for older clients.
Internal server for employees: enterprise-managed authorization, or a gateway that signs users in through your identity provider.
Service-to-service calls: the client credentials extension, or a plain API key on your own HTTP API if no MCP client is involved.
Local stdio server: credentials from the environment. The spec says stdio servers should not use the OAuth flow.

MCP gateways compared

Frequently asked questions

Does MCP require OAuth?

No. Authorization is optional. HTTP servers that need it should follow the OAuth 2.1 flow in the spec. Stdio servers should read credentials from the environment instead.

Is dynamic client registration still supported in MCP?

Yes, but it is deprecated as of 2026-07-28. Client ID Metadata Documents are now preferred. Dynamic registration stays for authorization servers that do not support metadata documents.

Why does my MCP client keep asking me to sign in again?

Usually the client got no refresh token or lost it. Clients may ask for offline_access when the authorization server lists it. Servers can also expire refresh tokens or require a new scope.

Can I use an API key instead of OAuth for an MCP server?

Many clients let you set a static header, and some servers accept one. It suits service accounts. For a person using their own account, OAuth fits better: each user signs in once, and each token can be scoped and revoked.

Implementation references

Use these first-party references for current request contracts and account requirements. Tool availability, prices, and negotiated terms can change.

Sources

Third-party details were checked on November 10, 2026. Vendors change pricing and features often, so confirm on their site before you decide.