Authentication
A hosted MCP server authenticates callers in one of two modes, set per server on its Authentication tab in the dashboard:
- API credentials in headers (default): the agent sends your API’s credential as a request header on every call, and the server forwards it to your API. Pass credentials covers this mode.
- OAuth sign-in: the server is an OAuth protected resource, as the MCP authorization specification describes. An MCP client such as Claude Code adds only the server URL, signs the user in with your authorization server in the browser, and sends the resulting access token. The server checks the token on every request and never forwards it to your API.
This page covers OAuth sign-in. Every setting on it takes effect without running fern generate again.
How sign-in works
- The client calls the server without a token. The server answers
401withWWW-Authenticate: Bearer resource_metadata="<server URL origin>/.well-known/oauth-protected-resource<path>". - The client reads that metadata. It names the server URL as
resourceand your issuer as the only entry inauthorization_servers. - The client registers with your authorization server through Dynamic Client Registration (DCR), a Client ID Metadata Document (CIMD), or a client ID you configured. It then signs the user in with the authorization code flow and Proof Key for Code Exchange (PKCE).
- The client sends
Authorization: Bearer <access token>on every request. The server accepts the token only when these hold:- It’s a JWT signed with
RS256,PS256orES256by a key from the issuer’s JSON Web Key Set (JWKS). issequals the issuer URL on the Authentication tab, character for character.audnames one of the server’s URLs (see Token audience).exphasn’t passed andnbf, if present, has, with 60 seconds of clock skew allowed. A token withoutexpis refused.- It carries every scope listed under Required scopes.
- It’s a JWT signed with
- Tools call your API with no credential, or with a separate token from token exchange.
Turn on OAuth sign-in
Set up your authorization server
Register an API (or resource server) for the MCP server at your identity provider before turning sign-in on. Configure your authorization server lists what each provider needs.
Configure your authorization server
Token audience
Each token’s aud claim must name one of the server’s URLs:
- The Fern URL, such as
https://acme.fernmcp.dev/petstore. - The custom domain once it’s active, written with a trailing slash:
https://mcp.example.com/. A custom domain serves at the root of the hostname, and MCP clients send a root URL as theresourceparameter with its trailing slash. Providers that match the audience exactly, such as Auth0, need the identifier in that form. - A toolset adds its path to each URL:
https://acme.fernmcp.dev/petstore/<toolset>,https://mcp.example.com/<toolset>. A token for one toolset isn’t accepted on another.
The server ignores a trailing slash when it compares aud, and a token for any of the server’s URLs works on every one of them (same toolset). A token issued for a different server is refused, even when both servers use the same issuer.
Client registration
The client has to be known to your authorization server before it can sign a user in. Each client supports one or more ways to register:
If the provider supports none of these for a client, the client reports an error such as Incompatible auth server: does not support dynamic client registration.
Auth0
Keycloak
Other providers
- Go to Applications > APIs > Create API. Set Identifier to the server URL from Token audience. Create one API per URL that clients connect to, since Auth0 issues one audience per API. Identifiers can’t be changed later, so check the trailing slash on a custom domain before creating it.
- On the API’s Permissions tab, add the scopes you listed under Required scopes, such as
mcp:tools. - In the API’s Settings, turn on Allow Offline Access. Clients such as Claude Code request
offline_accessto refresh tokens without signing the user in again. - For clients that register themselves, go to Settings > Advanced and turn on Dynamic Client Registration. Then open your login connection under Authentication (Database or Social) and turn on Promote Connection to Domain Level: Auth0 treats self-registered clients as third-party applications, and they can only use domain-level connections.
- On the API’s application access list, grant each client user-delegated access to the scopes. Self-registered clients appear there as Third Party applications.
- On the Authentication tab in the dashboard, set Issuer URL to
https://<tenant>.<region>.auth0.com/, with the trailing slash.
Auth0 answers a misconfigured authorization request with a generic “Oops!, something went wrong” page. Monitoring > Logs shows the reason. The causes seen most often are a resource with no matching API identifier (check the trailing slash), a connection that isn’t promoted to domain level, and a client without access to the API.
What your API receives
Under API access, choose what tools send to your API:
- No credential: tools call your API without credentials. Use this for a public API, or one that trusts the network the server calls from.
- Token exchange at the issuer: for each signed-in user, the server exchanges the user’s token at your authorization server, following the OAuth 2.0 token exchange standard, for a token meant for your API, and calls the API with that one. Your API sees the same user, never the caller’s original token.
Token exchange takes these fields:
Each exchanged token is reused for the same user’s token until it expires, and never past the user’s token. If the exchange fails, the tool call returns an error and your API isn’t called.
With Keycloak, turn on Standard Token Exchange on the exchanging client, and add a second audience mapper so the user’s token also lists the exchanging client in aud. Without it, the exchange fails with access_denied.
Limit tools by role
Tool roles (optional) takes a JSON object keyed by tool name. A user needs at least one of the listed roles:
- A tool with a list is hidden from
tools/listfor users without one of its roles, and the server refuses a call to it with JSON-RPC error-32001before your API is called. - A tool with an
argumentrule picks the roles from that argument’s value, falling back todefault. It stays listed, and each call is checked against the value it passes. A value with no entry and nodefaultis refused. - A tool that isn’t in the object needs no role.
Roles come from the token. By default the server reads Keycloak’s realm_access.roles and every resource_access.<client>.roles, then roles. Set Roles claim (optional) to read another claim, by name or dot path such as realm_access.roles.
Allow or block MCP clients
Client access limits which OAuth clients can connect:
- Allow only these clients: every other client is refused.
- Block these clients: the listed clients are refused, and every other client connects.
List one client ID per line, 1 to 100 of them. The server reads the client from the token’s azp claim, falling back to client_id. A refused client gets 403 with {"error":"access_denied","error_description":"This MCP client is not allowed on this server."} and no sign-in prompt. With an allow-list, a token that names no client is refused.
The MCP clientInfo name and the User-Agent can be faked, so they’re never used. A client that registers itself through DCR gets a new random ID at each registration, so name it only after pre-registering it at your provider. A CIMD client’s ID is a stable URL, such as https://vscode.dev/oauth/client-metadata.json.
Limit network access
The Network access card limits which IP addresses can reach the server, in both authentication modes. List IPv4 or IPv6 addresses or CIDR ranges, one per line, up to 100. A bare address becomes /32 or /128, and an empty list leaves the server open to every network. Changes apply within about 60 seconds.
A caller outside the list gets 403 with {"error":"forbidden","error_description":"Your IP address is not allowed to reach this server."} on MCP calls, on the OAuth metadata and on the connect page, before the server runs.
The address checked is the one Cloudflare sees. Web clients such as Claude.ai and ChatGPT call from their provider’s network rather than the user’s machine (Claude.ai uses 160.79.104.0/21), so list those ranges for them to work. A virtual private network changes the address too: requests then come from the network’s exit address, which can differ from the one an IP lookup site shows in the browser.
An allow-list narrows who can try to connect. OAuth sign-in or API credentials still decide who gets in.
Connect a client
Claude Code
Postman
Run /mcp, select the server, and choose Authenticate. The browser opens your provider’s sign-in page. Once signed in, View tools lists the tools.
Claude Code registers itself through DCR, with a loopback callback at http://localhost:<port>/callback. To use a pre-registered client instead, pass its ID and a fixed callback port, and add http://localhost:<port>/callback to the client’s redirect URIs:
Other MCP clients follow the same flow. They differ in how they register (DCR, CIMD or a pre-registered client) and in their callback URLs, which must be allowed at your provider.
Self-hosted servers
The generated HTTP server and Cloudflare Worker read the same settings from environment variables. stdio ignores them. The generated README.md in the zip lists the basic ones.
A missing or invalid value stops the server with a message that names the variable, such as MCP_AUTH_MODE is "oauth" but MCP_PUBLIC_URL is not set. The IP allow-list is a Fern hosting feature with no environment variable.