Add server OAuth protection conformance tests

[tobinsouth]

Summary

Starting a discussion on adding OAuth conformance tests for servers behind an --auth flag. The scenarios are still somewhat basic and only tests resource server protection and metadata. This PR stops at the point where a bearer would need to be passed, only validating server OAuth infrastructure (discovery, metadata, HTTP responses) without requiring access tokens.

In general, the concerns of the auth server are separated from the resource server, which puts auth conformance somewhat out of scope of SDKs. Having said that, it's a huge pain in the butt to achieve full auth conformance for Auth vendors, open-source auth solutions, or custom auth setups. This repo feels like a great place to put a reliable test of auth conformance testing for AS' wrapping servers against a high quality client.

Changes

New Test Scenarios (10 total)

Scenario	Purpose
server/auth-prm-discovery	Protected Resource Metadata endpoint (RFC 9728)
server/auth-as-metadata-discovery	Authorization Server metadata (RFC 8414)
server/auth-discovery-mechanism	Discovery endpoint availability
server/auth-as-pkce-support	PKCE S256 support (RFC 7636)
server/auth-as-cimd-supported	Client ID Metadata Document support
server/auth-as-token-auth-methods	Token endpoint auth methods
server/auth-as-grant-types	Grant types (client_credentials/SEP-1046)
server/auth-prm-resource-validation	Resource URI format validation
server/auth-401-unauthorized	401 response for unauthenticated requests
server/auth-www-authenticate-header	WWW-Authenticate header format (RFC 6750)

New Files

src/scenarios/server/auth/
├── helpers/
│   ├── auth-fetch.ts           # HTTP client with header parsing
│   └── as-metadata.ts          # AS metadata fetching utilities
├── scenarios/
│   ├── prm-discovery.ts
│   ├── as-metadata-discovery.ts
│   ├── discovery-mechanism.ts
│   ├── as-pkce-support.ts
│   ├── as-cimd-supported.ts
│   ├── as-token-auth-methods.ts
│   ├── as-grant-types.ts
│   ├── prm-resource-validation.ts
│   ├── unauthorized-response.ts
│   └── www-authenticate-header.ts
├── spec-references.ts          # RFC/spec reference definitions
└── index.ts

CLI Options Added

# Run OAuth test suite
npx @modelcontextprotocol/conformance server --url <url> --suite auth

# Include OAuth tests with active suite
npx @modelcontextprotocol/conformance server --url <url> --auth

# List OAuth scenarios
npx @modelcontextprotocol/conformance list --auth

Specifications Covered

• RFC 9728 (Protected Resource Metadata)
• RFC 8414 (Authorization Server Metadata)
• RFC 7636 (PKCE)
• RFC 6750 (Bearer Token Usage)
• RFC 7235 (HTTP Authentication)
• MCP Authorization Spec (2025-06-18)
• IETF CIMD Draft (Client ID Metadata Documents)
• MCP SEP-1046 (Client Credentials)

There are more to cover here, but the rest will require handling bearer tokens robustly and likely interactive auth flows.

Test Plan

• npm run typecheck passes
• npm run lint passes
• npm run build passes
• npm test passes (52 tests)
• Manual test against OAuth-enabled MCP server (production servers with functioning OAuth)

[tobinsouth]

@pcarleton do you even want something like this in the conformance repo, or should I go move some AS conformance testing towards the inspector. This PR is still a pretty basic auth scenario, and expanding the auth suite to handle bearer tokens will become increasingly painful with the current vitest infrastructure. So it might be best left elsewhere. Open to thoughts.

[pkg-pr-new]

Open in StackBlitz

npx https://pkg.pr.new/modelcontextprotocol/conformance/@modelcontextprotocol/conformance@64

commit: 4a8aa8a

[pcarleton]

I'm open to it, I think it could be helpful.

Originally, i was not going to test AS behavior, or at least not prioritize it because:

1. The SDK's generally don't provide a fully functional AS (and I don't think they should)
2. I was hoping we could get an OIDC conformance suite going

However, I think having the tests here would still be valuable if you're up for building it. Even if the SDK's don't provide it, it could be useful for testing an SDK + a chosen AS, so we have a "fully blessed" server example of the full suite. And it could be useful for a start to live server testing.

I'd love to get an example going to see what the results look like. I have a branch where I've scooted the Typescript SDK to be on node-oidc-provider for its examples which might be useful here, since it should have all the things.

If we like that approach, we could even give a way to spin up a conformant AS for servers and provide them the AS URL to check the AS <> SDK boundaries.

[pcarleton]

next steps on this for me would be:

• Let's just do 1 to 3 scenarios to start, focusing on a few aspects
  • at first glance, I think several of these could be multiple checks in the same scenario. e.g. "basic-auth" could have checks for each small step in a standard configured auth flow
• let's get an example that passes, and an example that fails

we've got some implicit best practices for scenarios starting to coalesce from writing a bunch for the spec release, which we can try to enumerate for this new batch.

[nbarbettini]

I've been using these new scenarios for the past few weeks and they're giving me a good signal on server auth conformance. Thanks @tobinsouth!

These scenarios helped me realize that many public remote MCP servers already use the path insertion style of AS metadata URLs (from 2025-11-25). The only change I had to make was expanding the helper to support that style: tobinsouth#1

[tobinsouth]

Amazing to hear @nbarbettini! Folded your PR in. I'm not actively maintaining this PR — there are some todo's like better unit testings and review to make sure we have coverage of the auth edge case weirdness.

Might be worth revisiting and pulling into the repo if it's useful for auth vendors or folks doing specific SDK work on auth.