Skip to content

Changelog

New updates and improvements at Cloudflare.

Back to all posts

The best way to do MCP auth just got better: Workers OAuth Provider goes v1, with a new split API and full support for MCP 2026-07-28

View as MarkdownAgent setup

@cloudflare/workers-oauth-provider ↗︎ is now v1, with a new split API. One Worker acts as the authorization server: it signs users in and issues tokens. Your MCP server acts as the resource server, and can run in another Worker. It validates each token with the authorization server over a Service Binding, without crossing the public Internet.

The split API

import {
	OAuthAuthorizationServer,
	OAuthResourceServer,
	insufficientScope,
} from "@cloudflare/workers-oauth-provider";
import { WorkerEntrypoint } from "cloudflare:workers";

// auth-server Worker: signs users in and issues tokens for both MCP servers.
const authorizationServer = new OAuthAuthorizationServer({
	issuer: "https://auth.example.com",
	resources: [
		"https://calendar.example.com/mcp",
		"https://drive.example.com/mcp",
	],
	scopesSupported: ["calendar:read", "calendar:write", "offline_access"],
	clientIdMetadataDocumentEnabled: true,
});

export class AuthServer extends WorkerEntrypoint {
	fetch(request) {
		if (new URL(request.url).pathname === "/authorize") {
			return showConsent(request, this.env);
		}
		return authorizationServer.fetch(request, this.env, this.ctx);
	}

	validateToken(resource, token) {
		return authorizationServer.validateToken(resource, token, this.env);
	}
}

// calendar MCP Worker: checks tokens with AuthServer over a Service Binding.
export const calendar = new OAuthResourceServer({
	resourceMetadata: {
		resource: "https://calendar.example.com/mcp",
		authorization_servers: ["https://auth.example.com"],
	},
	requiredScopes: ["calendar:read"],
	validateToken: (env) => env.AUTH_SERVER.validateToken,
	handler: {
		fetch(request, env, ctx) {
			if (
				request.method === "POST" &&
				!ctx.auth.scope.includes("calendar:write")
			) {
				return insufficientScope(ctx.auth, ["calendar:read", "calendar:write"]);
			}
			return handleMcp(request, ctx.props);
		},
	},
});
import {
	OAuthAuthorizationServer,
	OAuthResourceServer,
	insufficientScope,
} from "@cloudflare/workers-oauth-provider";
import { WorkerEntrypoint } from "cloudflare:workers";

// auth-server Worker: signs users in and issues tokens for both MCP servers.
const authorizationServer = new OAuthAuthorizationServer<Env>({
	issuer: "https://auth.example.com",
	resources: [
		"https://calendar.example.com/mcp",
		"https://drive.example.com/mcp",
	],
	scopesSupported: ["calendar:read", "calendar:write", "offline_access"],
	clientIdMetadataDocumentEnabled: true,
});

export class AuthServer extends WorkerEntrypoint<Env> {
	fetch(request: Request) {
		if (new URL(request.url).pathname === "/authorize") {
			return showConsent(request, this.env);
		}
		return authorizationServer.fetch(request, this.env, this.ctx);
	}

	validateToken(resource: string, token: string) {
		return authorizationServer.validateToken(resource, token, this.env);
	}
}

// calendar MCP Worker: checks tokens with AuthServer over a Service Binding.
export const calendar = new OAuthResourceServer<Env, AuthProps>({
	resourceMetadata: {
		resource: "https://calendar.example.com/mcp",
		authorization_servers: ["https://auth.example.com"],
	},
	requiredScopes: ["calendar:read"],
	validateToken: (env) => env.AUTH_SERVER.validateToken,
	handler: {
		fetch(request, env, ctx) {
			if (
				request.method === "POST" &&
				!ctx.auth.scope.includes("calendar:write")
			) {
				return insufficientScope(ctx.auth, ["calendar:read", "calendar:write"]);
			}
			return handleMcp(request, ctx.props);
		},
	},
});

In the example, env.AUTH_SERVER.validateToken is that Service Binding call. The calendar Worker needs no KV namespace of its own.

{
	"name": "calendar-mcp",
	"main": "src/index.ts",
	// Set this to today's date
	"compatibility_date": "2026-10-01",
	"services": [
		{
			"binding": "AUTH_SERVER",
			"service": "auth-server",
			"entrypoint": "AuthServer",
		},
	],
}
name = "calendar-mcp"
main = "src/index.ts"
# Set this to today's date
compatibility_date = "2026-10-01"

[[services]]
binding = "AUTH_SERVER"
service = "auth-server"
entrypoint = "AuthServer"

OAuthResourceServer publishes the RFC 9728 ↗︎ protected resource metadata that MCP clients use to find your authorization server. It answers requests without a token with a 401 challenge that points to that metadata. It also rejects tokens issued for any other resource.

You can still use OAuthProvider as both the authorization server and the MCP server. For most 0.x deployments, the only required change is to add resourceMetadata: { resource }.

Other updates and helpers

Upgrade with the migration skill

npm i @cloudflare/workers-oauth-provider@latest

Point your coding agent at node_modules/@cloudflare/workers-oauth-provider/skills/migrate-to-1.0/SKILL.md, or follow the migration guide ↗︎.

For both Workers in full, refer to the split Workers example ↗︎.