MCP TypeScript SDK (V2) / @modelcontextprotocol/server / server/middleware/bearerAuth

server/middleware/bearerAuth

Interfaces

BearerAuthOptions

Defined in: packages/server/src/server/middleware/bearerAuth.ts:34

Options for verifyBearerToken, requireBearerAuth, and bearerAuthChallengeResponse.

Properties

requiredScopes?

optional requiredScopes?: string[]

Defined in: packages/server/src/server/middleware/bearerAuth.ts:44

Optional scopes that the token must have. When any are missing the request is refused with 403 insufficient_scope.

resourceMetadataUrl?

optional resourceMetadataUrl?: string

Defined in: packages/server/src/server/middleware/bearerAuth.ts:54

Optional Protected Resource Metadata URL to advertise in the WWW-Authenticate header on 401/403 responses, per RFC 9728.

Typically built with getOAuthProtectedResourceMetadataUrl, exported from this package.

verifier

verifier: OAuthTokenVerifier

Defined in: packages/server/src/server/middleware/bearerAuth.ts:38

A verifier used to validate access tokens.

---

OAuthTokenVerifier

Defined in: packages/server/src/server/middleware/bearerAuth.ts:13

Minimal token-verifier interface for MCP servers acting as an OAuth 2.0 Resource Server. Implementations introspect or locally validate an access token and return the resulting AuthInfo, which the serving entry surfaces to MCP request handlers via ctx.http.authInfo.

This is intentionally narrower than a full OAuth Authorization Server provider — it only covers the verification step a Resource Server needs.

Methods

verifyAccessToken()

verifyAccessToken(token): Promise<AuthInfo>

Defined in: packages/server/src/server/middleware/bearerAuth.ts:27

Verifies an access token and returns information about it.

Implementations should throw an OAuthError with OAuthErrorCode.InvalidToken when the token is unknown, revoked, or otherwise invalid; the bearer-auth helpers map that to a 401 with a WWW-Authenticate challenge.

Note: bearer-auth verification rejects tokens whose AuthInfo.expiresAt is unset (matches v1 behavior). Ensure your verifier populates it (e.g. from RFC 7662 introspection exp or the JWT exp claim).

Parameters

token

string

Returns

Promise<AuthInfo>

Functions

bearerAuthChallengeResponse()

bearerAuthChallengeResponse(error, options?): Response

Defined in: packages/server/src/server/middleware/bearerAuth.ts:136

Build the HTTP answer for a Bearer authentication failure.

Maps an OAuthError to its status — 401 for invalid_token and 403 for insufficient_scope (both carrying the WWW-Authenticate: Bearer … challenge, with resource_metadata when configured so clients can discover the Authorization Server), 500 for server_error, 400 for anything else. A non-OAuthError value answers 500 server_error. The body is the OAuth error JSON.

Parameters

error

unknown

options?

Pick<BearerAuthOptions, "requiredScopes" | "resourceMetadataUrl">

Returns

Response

---

requireBearerAuth()

requireBearerAuth(options): (request) => Promise<AuthInfo | Response>

Defined in: packages/server/src/server/middleware/bearerAuth.ts:185

Require a valid Bearer token on web-standard requests.

The framework-free counterpart of requireBearerAuth from @modelcontextprotocol/express, for hosts whose HTTP surface is a fetch(request) handler — Cloudflare Workers, Deno, Bun, Hono. The returned gate resolves to the verified AuthInfo, or to the ready-to-return challenge Response when the request must be refused.

Parameters

options

BearerAuthOptions

Returns

(request) => Promise<AuthInfo | Response>

Example

const gate = requireBearerAuth({ verifier, requiredScopes: ['mcp'] });

async function fetchHandler(request: Request): Promise<Response> {
    const auth: AuthInfo | Response = await gate(request);
    if (auth instanceof Response) return auth;
    return handler.fetch(request, { authInfo: auth });
}

---

verifyBearerToken()

verifyBearerToken(authorizationHeader, options): Promise<AuthInfo>

Defined in: packages/server/src/server/middleware/bearerAuth.ts:94

Validate a raw Authorization header value as a Bearer token and return the verified AuthInfo.

The runtime-neutral core of Bearer authentication: it parses the header, runs the verifier, enforces requiredScopes, and rejects tokens without an expiration or past it. On any failure it throws an OAuthError — pass that to bearerAuthChallengeResponse for the matching HTTP answer, or use requireBearerAuth to get both steps as one call.

Framework adapters build on this: requireBearerAuth from @modelcontextprotocol/express feeds it req.headers.authorization.

Parameters

authorizationHeader

string | null | undefined

options

BearerAuthOptions

Returns

Promise<AuthInfo>