MCP server authentication patterns: API keys, bearer tokens, and OAuth with a hosted identity provider

A remote MCP server needs to know who is calling before it runs a tool, and the MCP specification only standardizes one way to find out: OAuth 2.1, with the server acting as a resource server. In practice there are three patterns in use, and the right one depends less on security preference than on which clients have to connect. This page compares them, gives tested code for the API key gate and the OAuth resource server, lists the settings each hosted identity provider needs, and maps which clients support which pattern.

The three patterns

The specification makes authorization optional, and says a local stdio server should take credentials from its environment instead. For a remote server open to more than one person, OAuth is the only pattern every chat-style client can complete without the user handling a secret. API keys remain the right choice for automation, CI, and agents that run without a person present.

Pattern 1: an API key gate

An API key gate is a few lines in front of the MCP handler. This version runs on any web-standard runtime, stores only SHA-256 digests of issued keys, and accepts the key either as a bearer token or as X-API-Key, so it works with clients that only let you set Authorization and with tools, like mcptest's CLI, that send X-API-Key. It was type-checked with @modelcontextprotocol/server 2.3.1 and run on Node.js 22.

// server.ts
import { createMcpHandler, McpServer, type AuthInfo } from '@modelcontextprotocol/server';
import { z } from 'zod';

// SHA-256 hex digests of the keys you issued; the keys themselves are never stored.
const KEY_DIGESTS = new Map<string, string>([
  [process.env.ACME_KEY_SHA256 ?? '', 'acme-ci'],
]);

async function sha256Hex(value: string): Promise<string> {
  const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(value));
  return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, '0')).join('');
}

async function authenticateApiKey(request: Request): Promise<AuthInfo | Response> {
  const header = request.headers.get('Authorization');
  const key = header?.match(/^Bearer (.+)$/i)?.[1] ?? request.headers.get('X-API-Key');
  const clientId = key ? KEY_DIGESTS.get(await sha256Hex(key)) : undefined;
  if (!key || !clientId) {
    return Response.json(
      { jsonrpc: '2.0', error: { code: -32001, message: 'A valid API key is required' }, id: null },
      { status: 401, headers: { 'WWW-Authenticate': 'Bearer realm="orders-mcp"' } }
    );
  }
  return { token: key, clientId, scopes: ['orders:read'] };
}

function buildServer() {
  const server = new McpServer({ name: 'orders', version: '1.0.0' });
  server.registerTool(
    'get-order',
    {
      description: 'Look up one order by its id and return its shipping status',
      inputSchema: z.strictObject({
        id: z.string().regex(/^ord_[a-z0-9]{1,32}$/).describe('Order id, for example ord_123'),
      }),
      annotations: { readOnlyHint: true },
    },
    async ({ id }, ctx) => ({
      content: [{ type: 'text', text: `Order ${id} for ${ctx.http?.authInfo?.clientId}: shipped` }],
    })
  );
  return server;
}

const handler = createMcpHandler(buildServer);

export default {
  async fetch(request: Request): Promise<Response> {
    const auth = await authenticateApiKey(request);
    if (auth instanceof Response) return auth;
    return handler.fetch(request, { authInfo: auth });
  },
};

Hashing first means the lookup never compares a raw secret byte by byte, and a leaked database contains no usable keys. Passing authInfo to handler.fetch gives tools the caller's identity as ctx.http.authInfo. Add the CORS headers from the CORS reference if browser clients will connect, and list X-API-Key in Access-Control-Allow-Headers.

What the 401 should not contain. This challenge has no resource_metadata and the server publishes no OAuth metadata, because there is no OAuth. That is deliberate, but some clients probe anyway. Copilot CLI 1.0.101, configured with a static Authorization header, answered a 401 by requesting /.well-known/oauth-protected-resource/mcp, /.well-known/oauth-protected-resource, and /mcp/.well-known/oauth-protected-resource before giving up, which is why a wrong key can look like an OAuth failure in client logs. Return 401 only when the key is missing or wrong, never for a valid key.

What mcptest reports. Without a key, the headless gate stops at authorization-required and exits with code 2. With the key in an environment variable, npm run mcptest -- --api-key-env MCPTEST_API_KEY https://mcp.example.com/mcp sends it as X-API-Key; the run scored 49 out of 55, because Security Posture is only scored when OAuth metadata exists.

Pattern 2: static bearer tokens

A personal access token is an API key bound to a user. Generate it in your product, show it once, store its digest with the user id, and look it up exactly as above; the only change is that clientId becomes the user. Give tokens an expiry and a revocation path, because nothing in MCP refreshes them.

Do not confuse this with OAuth bearer tokens. A static token is opaque to the client. An OAuth access token is obtained by the client through a flow, is short-lived, and must be validated for its audience.

Pattern 3: OAuth with a hosted identity provider

In this pattern the MCP server never issues tokens. It is an OAuth 2.1 resource server, and the hosted provider is the authorization server. The server has four jobs, all required by the 2026-07-28 specification:

1. Publish Protected Resource Metadata (RFC 9728) at /.well-known/oauth-protected-resource/mcp for an endpoint at /mcp, naming the exact resource URL and the provider's issuer in authorization_servers.
2. Challenge with 401 and WWW-Authenticate: Bearer resource_metadata="...", ideally with scope. Clients only start sign-in from a 401.
3. Validate every token: signature against the provider's JWKS, iss, expiry, and an audience that is this server. The specification forbids accepting tokens issued for anything else, and forbids passing a client's token through to upstream APIs.
4. Enforce scopes per operation, answering 403 with error="insufficient_scope" and the scopes needed.

The SDKs do most of this. Tested, complete servers: Express with requireBearerAuth and mcpAuthMetadataRouter, Hono and Cloudflare Workers with the fetch-level requireBearerAuth, FastAPI with TokenVerifier and AuthSettings, and Next.js with withMcpAuth. The core of every one is the same JWT check:

const { payload } = await jwtVerify(token, jwks, { issuer: ISSUER, audience: 'https://mcp.example.com/mcp' });

Copy ISSUER exactly from the provider's discovery document; jose compares it as a string, so a missing or extra trailing slash fails every token.

Client registration: CIMD first, DCR for compatibility

Before signing in, a client needs a client ID at the provider. The 2026-07-28 specification says authorization servers and clients should support Client ID Metadata Documents, where the client ID is an HTTPS URL serving the client's metadata. Dynamic Client Registration is deprecated and kept only for backward compatibility. Clients try a pre-registered ID first, then CIMD when the provider advertises client_id_metadata_document_supported, then DCR, then ask the user.

Many clients in use today still rely on DCR, so enable both on the provider until your client mix proves otherwise.

Provider settings

Two provider details change your code. Stytch's authorization endpoint is a page you host with Stytch's components, so the sign-in screen lives in your app. And with Stytch's project-ID audience, all MCP servers in one project accept each other's tokens; use one project per server, or add a check of a custom claim, if that matters.

OAuth versus the clients that cannot do it

JetBrains AI Assistant does not implement OAuth for MCP servers; the request is open as LLM-25012. GitHub's Copilot cloud agent explicitly does not support remote servers that use OAuth. For those, either accept a second credential type, such as a personal access token next to OAuth, or point users at a local bridge such as mcp-remote. Accepting both is common: try the JWT check, fall back to a token lookup, and return the OAuth challenge only when both fail.

What each client supports

"Limited" means beta, plan-gated or restricted to some accounts. "unknown" means the vendor's current documentation does not state it. Every cell, with its source page and verification date, is in clientCompatibility.json (opens in a new tab).

Four clients are not in that dataset yet. Their current documentation says:

Choosing

• A public server for chat clients: OAuth with a hosted provider. ChatGPT and claude.ai cannot send your API key in practice.
• An internal server used from IDEs and CI: API keys or personal access tokens, issued per person or per pipeline.
• Both audiences: OAuth plus personal access tokens on the same endpoint, with the OAuth challenge as the 401 response.

Whatever you choose, test the failure paths as well as the happy path: no credential, a wrong one, a token for another audience, and a token without the needed scope.

Check your auth in the playground

Paste your endpoint into the MCP Playground and connect. The OAuth flight recorder shows each discovery request, the registration method the provider accepted, and the token exchange; for an API key server, add the key as a header and confirm the tool list loads. When it passes, gate deploys on it with --bearer-token-env or --api-key-env as described in How to test an MCP server before you deploy it.