Authenticate Users

Tool calls are anonymous by default: nothing in the protocol tells you who’s asking. OAuth closes that gap, and the host does most of the work: it discovers your authorization server, signs the user in, refreshes tokens, and attaches a Bearer token to every request. Your server keeps three jobs: publish the discovery metadata, verify the tokens, and read the user in your handlers.

Using Auth0, Clerk, Descope, Stytch, WorkOS, or any other OAuth provider? Connect it in one line instead of wiring this by hand, and still mix public and authenticated tools with auth: { allowsAnonymous: true }.

Here’s a complete server where every tool requires sign-in:

server.ts

import { McpServer, mcpAuthMetadataRouter, requireBearerAuth } from "skybridge/server";
import { z } from "zod";

import { verifyAccessToken } from "./auth.js";

const server = new McpServer({ name: "personal-shopper", version: "0.0.1" }, {})
  .use(
    mcpAuthMetadataRouter({
      oauthMetadata: {
        issuer: "https://auth.myshop.com",
        authorization_endpoint: "https://auth.myshop.com/authorize",
        token_endpoint: "https://auth.myshop.com/token",
        response_types_supported: ["code"],
      },
      resourceServerUrl: new URL(process.env.SERVER_URL),
    }),
  )
  .use("/mcp", requireBearerAuth({ verifier: { verifyAccessToken } }))
  .registerTool(
    {
      name: "search-products",
      description: "Show products matching a query in a carousel.",
      inputSchema: { query: z.string() },
      securitySchemes: [{ type: "oauth2" }],
      view: { component: "carousel" },
    },
    async ({ query }, extra) => ({
      structuredContent: { products: await search(query, extra.authInfo) },
    }),
  )
  .registerTool(
    {
      name: "create-checkout",
      description: "Create a checkout session for the given products.",
      inputSchema: { productIds: z.array(z.string()) },
      securitySchemes: [{ type: "oauth2", scopes: ["checkout"] }],
    },
    async ({ productIds }, extra) => ({
      structuredContent: { url: await checkout(productIds, extra.authInfo) },
    }),
  );

The sections below cover publishing the discovery metadata, verifying tokens with a middleware, declaring auth per tool, reading the user in handlers, and mixing public and authenticated tools.

Publish Discovery Metadata

Hosts find your authorization server through standard metadata documents (RFC 9728). mcpAuthMetadataRouter serves them at /.well-known/oauth-protected-resource, so the host can perform the authentication flow.

server.ts

const server = new McpServer({ name: "personal-shopper", version: "0.0.1" }, {})
  .use(
    mcpAuthMetadataRouter({
      oauthMetadata: {
        issuer: "https://auth.myshop.com",
        authorization_endpoint: "https://auth.myshop.com/authorize",
        token_endpoint: "https://auth.myshop.com/token",
        response_types_supported: ["code"],
      },
      resourceServerUrl: new URL(process.env.SERVER_URL),
    }),
  )
  .use("/mcp", requireBearerAuth({ verifier: { verifyAccessToken } }))
  .registerTool(/* search-products … */)
  .registerTool(/* create-checkout … */);

The endpoint values come from your OAuth provider’s documentation. resourceServerUrl is this server’s public URL: localhost in development, the tunnel URL when testing in a host, your domain in production.

Verify Tokens with a Middleware

Once the user is signed in, every request carries Authorization: Bearer <token>. requireBearerAuth validates it before any handler runs: missing, invalid, or expired tokens get a 401, insufficient scopes a 403. It takes a verifier you write, with one method: verifyAccessToken(token) resolves with an AuthInfo (handlers receive it as extra.authInfo) or throws InvalidTokenError (the middleware answers 401).

const server = new McpServer({ name: "personal-shopper", version: "0.0.1" }, {})
  .use(
    mcpAuthMetadataRouter({
      oauthMetadata: {
        issuer: "https://auth.myshop.com",
        authorization_endpoint: "https://auth.myshop.com/authorize",
        token_endpoint: "https://auth.myshop.com/token",
        response_types_supported: ["code"],
      },
      resourceServerUrl: new URL(process.env.SERVER_URL),
    }),
  )
  .use("/mcp", requireBearerAuth({ verifier: { verifyAccessToken } }))
  .registerTool(/* search-products … */)
  .registerTool(/* create-checkout … */);

import { type AuthInfo, InvalidTokenError } from "skybridge/server";

export async function verifyAccessToken(token: string): Promise<AuthInfo> {
  try {
    // Provider-specific: JWKS verification, introspection endpoint, or SDK
    const payload = await validateToken(token);

    return {
      token,
      clientId: payload.clientId,
      scopes: payload.scopes,
      expiresAt: payload.expiresAt,
      extra: { subject: payload.sub },
    };
  } catch (err) {
    throw new InvalidTokenError(
      err instanceof Error ? err.message : "Token validation failed",
    );
  }
}

The validation body is provider-specific: JWKS verification for JWT-issuing providers, an introspection call for opaque tokens, or the provider’s own middleware in place of requireBearerAuth.

Type the Claims You Read

The claim shape belongs to the verifier, so handlers get it without declaring anything. On the provider path each provider ships the claims its own docs promise, and a type argument adds the ones your tenant sends:

server.ts

oauth: await workosProvider<{ tenant: string }>({ domain, audience }),

Writing the verifier yourself? Type it TokenVerifier<Claims> and the shape flows the same way. None of this is checked at runtime, so keep anything the IdP may omit optional. No provider ships email in an access token by default: WorkOS, Clerk, Descope and Stytch can add one through a JWT template or claims action, and Auth0 needs a namespaced claim, since it drops non-namespaced ones.

Mix Public and Authenticated Tools

Serving both anonymous and signed-in callers from one server takes three changes to the fully authenticated setup.

On the provider path (the oauth constructor option), these three steps collapse into one auth declaration per tool, and Skybridge enforces it for you:

server
  .registerTool({ name: "search-products", auth: { allowsAnonymous: true }, /* … */ }, handler)
  .registerTool({ name: "create-checkout", auth: { scopes: ["checkout"] }, /* … */ }, handler);

Any auth: { allowsAnonymous: true } tool makes the server serve anonymous callers; every other tool stays sign-in-gated, with scopes enforced before the handler. No manual middleware swap or handler guard. The lower-level steps below apply when you wire the middleware by hand instead.

Switch the Middleware

optionalBearerAuth validates the token when present, lets the request through when absent, and still rejects invalid tokens with a 401. Unauthenticated requests now reach your handlers.

server.ts

server
  .use("/mcp", optionalBearerAuth({ verifier: { verifyAccessToken } }))
  .registerTool(/* search-products … */)
  .registerTool(/* create-checkout … */);

Declare Tool Visibility

Three declarations cover the combinations:

`securitySchemes`	Meaning
`[{ type: "oauth2" }]`	Requires sign-in
`[{ type: "noauth" }]`	Works signed out
`[{ type: "noauth" }, { type: "oauth2" }]`	Works signed out, does more when signed in

server.ts

server.registerTool(
  {
    name: "search-products",
    // …
    securitySchemes: [{ type: "noauth" }, { type: "oauth2" }],
  },
  async ({ query }, extra) => ({
    structuredContent: { products: await search(query, extra.authInfo) },
  }),
);

search-products lists both schemes: anonymous callers browse the public catalog, signed-in callers get results scoped to their account. extra.authInfo is set or undefined accordingly.

Guard the Handler

With unauthenticated requests reaching handlers, the scope check is no longer a formality: it’s the only gate on protected tools.

server.ts

server.registerTool(
  {
    name: "create-checkout",
    // …
    securitySchemes: [{ type: "oauth2", scopes: ["checkout"] }],
  },
  async ({ productIds }, extra) => {
    if (!extra.authInfo?.scopes.includes("checkout")) {
      return { content: "Sign in to check out.", isError: true };
    }
    return {
      structuredContent: { url: await checkout(productIds, extra.authInfo) },
    };
  },
);

All done!

You now know how to authenticate users. Learn how to test your MCP App in the next chapter.

Go Further

Register Tools

Define what humans and agents can do

Create Views

Craft interactive UIs rendered in conversation

Manage State

Decide what the model sees

Get Started

Resources

Authenticate Users

Publish Discovery Metadata

Verify Tokens with a Middleware

Type the Claims You Read

Mix Public and Authenticated Tools

Switch the Middleware

Declare Tool Visibility

Guard the Handler

All done!

Go Further

Register Tools

Create Views

Manage State

​Publish Discovery Metadata

​Verify Tokens with a Middleware

​Type the Claims You Read

​Mix Public and Authenticated Tools

​Switch the Middleware

​Declare Tool Visibility

​Guard the Handler

All done!

​Go Further

Register Tools

Create Views

Manage State

Publish Discovery Metadata

Verify Tokens with a Middleware

Type the Claims You Read

Mix Public and Authenticated Tools

Switch the Middleware

Declare Tool Visibility

Guard the Handler

Go Further