feat(server-auth-legacy): add frozen v1 Authorization-Server package

[felixweinberger]

Part of the v2 backwards-compatibility series — see reviewer guide.

New @modelcontextprotocol/server-auth-legacy package — frozen v1 copy of mcpAuthRouter/ProxyOAuthServerProvider/handlers. npm deprecated on publish with a message pointing to a real IdP + the RS helpers in /express.

Motivation and Context

New @modelcontextprotocol/server-auth-legacy package — frozen v1 copy of mcpAuthRouter/ProxyOAuthServerProvider/handlers. npm deprecated on publish with a message pointing to a real IdP + the RS helpers in /express.

v1 vs v2 pattern & evidence

v1 pattern:

`import { mcpAuthRouter } from '@modelcontextprotocol/sdk/server/auth/router.js'`

v2-native:

Use a dedicated OAuth Authorization Server (IdP); SDK only ships Resource-Server glue

Evidence: Unblocks consumers on the v1 AS impl with a clear migration signal.

How Has This Been Tested?

• Existing v1 tests ported
• Integration: validated bump-only against 5 OSS repos via the v2-bc-integration validation branch
• pnpm typecheck:all && pnpm lint:all && pnpm test:all green

Breaking Changes

None — additive @deprecated shim. Removed in v3.

Types of changes

• New feature (non-breaking change which adds functionality)

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added or updated documentation as needed

Additional context

Stacks on: none

[changeset-bot]

🦋 Changeset detected

Latest commit: 51eabff

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@modelcontextprotocol/server-auth-legacy	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

@modelcontextprotocol/client

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/client@1908

@modelcontextprotocol/server

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/server@1908

@modelcontextprotocol/server-auth-legacy

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/server-auth-legacy@1908

@modelcontextprotocol/express

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/express@1908

@modelcontextprotocol/fastify

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/fastify@1908

@modelcontextprotocol/hono

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/hono@1908

@modelcontextprotocol/node

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/node@1908

commit: 51eabff

[felixweinberger]

@claude review

[felixweinberger]

@claude review

[felixweinberger]

@claude review

[felixweinberger]

@claude review

[felixweinberger]

Reviewer guide — what's copy-paste vs. modified

This package is a frozen copy of v1's src/server/auth/ Authorization-Server implementation. ~90% is verbatim from v1.x; the remaining ~10% is packaging and import-path adaptation.

Verbatim from v1 (skim — review is "did we copy faithfully?")

File	v1 source
src/handlers/authorize.ts	v1.x/src/server/auth/handlers/authorize.ts
src/handlers/token.ts	v1.x/.../token.ts
src/handlers/register.ts	v1.x/.../register.ts
src/handlers/revoke.ts	v1.x/.../revoke.ts
src/handlers/metadata.ts	v1.x/.../metadata.ts
src/middleware/bearerAuth.ts	v1.x/.../middleware/bearerAuth.ts
src/middleware/clientAuth.ts	v1.x/.../middleware/clientAuth.ts
src/middleware/allowedMethods.ts	v1.x/.../middleware/allowedMethods.ts
src/router.ts	v1.x/.../router.ts
src/provider.ts	v1.x/.../provider.ts
src/providers/proxyProvider.ts	v1.x/.../providers/proxyProvider.ts
src/clients.ts	v1.x/.../clients.ts
test/**	v1.x/.../*.test.ts (142 cases ported)

Modified / new (actually review these)

• src/errors.ts — has its own OAuthError base class instead of importing from core. Known limitation: import {OAuthError} from '@modelcontextprotocol/server' ≠ import {OAuthError} from '@modelcontextprotocol/server-auth-legacy' for instanceof checks. The router/handlers in this package check against this package's class.
• src/index.ts — barrel export; curated public surface.
• src/types.ts — re-exports AuthInfo/OAuthTokens etc. from @modelcontextprotocol/server instead of defining locally.
• Import paths throughout — ../../shared/auth.js → @modelcontextprotocol/server; ../../types.js → @modelcontextprotocol/server.
• package.json — new package, "deprecated" field, express as required peer.
• README.md — deprecation notice + pointer to @modelcontextprotocol/express for RS-only auth.
• .github/workflows/publish.yml (+1 line) — adds package to publish matrix.

Maintenance contract

Frozen. Security patches only. Consumers should migrate to an external AS (better-auth, etc.) for new work; this exists so v1 OAuth-provider servers (e.g. shortcut-mcp-server) can upgrade without rewriting their AS.

[claude]

51eabff resolves both remaining threads (express is back to a required peer, and the OAuth-error-consolidation sections in migration.md/migration-SKILL.md now scope the subclass→OAuthError rewrite to client-side) — nothing further from me. Leaving final sign-off to a human given this adds a new published package + OAuth AS code + a publish.yml change, and the npm deprecated banner / README forward-reference @modelcontextprotocol/express exports that only exist once #1907 lands.

Extended reasoning...

Overview

Adds @modelcontextprotocol/server-auth-legacy, a new workspace package that is a frozen copy of v1's src/server/auth/ (router, handlers, middleware, ProxyOAuthServerProvider, error hierarchy), plus the full ported v1 test suite (10 files / ~140 cases), package scaffolding (tsdown/eslint/vitest/typedoc), a changeset, an entry in .changeset/pre.json, an extra path in .github/workflows/publish.yml, and migration-doc edits in docs/migration.md, docs/migration-SKILL.md, and docs/faq.md.

State since last review

My two open inline comments from the previous round are addressed by 51eabff:

• package.json optional express peer — the peerDependenciesMeta block is gone; express is again a required peer (matching sibling @modelcontextprotocol/express).
• OAuth-error-consolidation contradiction — both docs/migration.md (§OAuth error refactoring) and docs/migration-SKILL.md (§5) now carry an explicit note that the v1 subclass hierarchy / OAUTH_ERRORS remain available from server-auth-legacy for AS implementations, with the OAuthError+OAuthErrorCode rewrite scoped to client-side.

The bug-hunting system found nothing new at this commit.

Security risks

The package is an OAuth 2.0 Authorization Server implementation (token issuance, PKCE verification, client-secret comparison, bearer-token verification, dynamic client registration). It's a verbatim port of code that has shipped in v1 for a long time and is covered by the ported v1 test suite, but it is unambiguously security-sensitive surface.

Level of scrutiny

High — new published npm package, security-relevant code paths, CI/publish workflow change, and migration-guide edits that will steer every v1→v2 consumer. The remaining intentional forward-reference (README L11, package.json "deprecated" field, changeset, src/index.ts @deprecated JSDoc all point at RS helpers in @modelcontextprotocol/express that ship in #1907) is a release-coordination decision the maintainer has explicitly accepted, but it does mean merge order with #1907 matters for the published deprecate banner.

Other factors

This PR has been through seven review rounds with substantive fixes each time (barrel completeness, full v1 test port, pkg-pr-new inclusion, doc self-consistency, peer-dep correctness). It's in good shape now; deferring solely on size/sensitivity, not on any open defect.