MCP OAuth Compliance Tester

Web-based tool for testing MCP server OAuth compliance with RFC 9728, RFC 8414, RFC 7591, RFC 9068, RFC 7519, RFC 7515, OAuth 2.1, and MCP 2025-11-25 specification.

✨ NEW: Now supports both Pre-2025-11-25 and MCP 2025-11-25 protocol versions!

GitHub Repository: https://github.com/gazzadownunder/MCP-OAuth-Compliance

Quick Start

npm install
npm start

Open http://localhost:3456 in your browser.

Global Installation (CLI)

Install globally to use as a command-line tool:

npm install -g .
mcp-oauth-compliance

Or install directly from GitHub:

npm install -g github:gazzadownunder/mcp-oauth-compliance
mcp-oauth-compliance

Or run directly via npx:

npx github:gazzadownunder/mcp-oauth-compliance

CLI Options

mcp-oauth-compliance [options]

Options:
  -p, --port <number>  Server port (default: 3001, or PORT env var)
  -h, --help           Show help message

Examples:

mcp-oauth-compliance --port 3000
mcp-oauth-compliance -p 9000
PORT=4000 mcp-oauth-compliance

Protocol Version Support

This compliance tester supports both the legacy and updated MCP authorization protocols:

Pre-2025-11-25 (Original MCP OAuth)

The original MCP OAuth specification supporting standard DCR and OAuth flows.

Supported Features:

• RFC 7591 Dynamic Client Registration (DCR)
• Optional PKCE (S256 or plain methods)
• Standard OAuth 2.0/2.1 authorization flows
• JWT access token validation
• Client registration via DCR or preregistration

MCP 2025-11-25 (Enhanced Security) 🆕

Enhanced specification with improved security and new capabilities.

New Requirements:

• ✅ S256 PKCE (REQUIRED): Mandatory S256 code challenge method, plain discouraged
• ✅ Client ID Metadata Documents: HTTPS URLs as client identifiers with hosted metadata
• ✅ Resource Parameter (RFC 8707): Resource indicators in authorization/token requests
• ✅ Token Audience Validation: Strict JWT aud claim verification
• ✅ Step-Up Authorization: Handle insufficient_scope with re-authorization flow
• ✅ Private Key JWT: Enhanced client authentication option

Client Registration Priority (MCP 2025-11-25):

1. Preregistration (Priority 1) - Use existing client credentials when available
2. Client ID Metadata Document (Priority 2) - HTTPS URL as client_id
3. Dynamic Client Registration (Priority 3) - RFC 7591 fallback

Selecting Protocol Version

In the web interface, select your desired protocol version from the dropdown:

1. Pre-2025-11-25: Test servers using the original specification
2. MCP 2025-11-25: Test servers implementing the latest specification

The tester automatically adjusts validation rules and test coverage based on your selection.

Features

Core Features

• Web Interface: Interactive compliance testing dashboard with collapsible test sections
• Dual Protocol Support: Test against Pre-2025-11-25 OR MCP 2025-11-25 specifications
• Comprehensive Tests: RFC 9728 (Protected Resource Metadata), RFC 8414 (AS Discovery), RFC 7591 (DCR), OAuth 2.1
• HTTPS Validation: Transport security checks per OAuth requirements
• Multiple Discovery Methods: Standard RFC 8414 + OIDC discovery
• Pre-configured Client Mode: Test with existing OAuth clients (bypasses DCR)
• Interactive OAuth Flow: Browser-based authorization with PKCE
• Smart Port Selection: Automatically avoids the server's port and finds available callback port (up to 20 attempts)
• Enhanced Debug Mode: Full HTTP request/response capture with expandable UI sections for troubleshooting
• RFC 7592 Validation: Validates registration_client_uri format with auto-correction for relative URLs
• Persistent UI State: Section collapse/expand preferences saved across test runs using localStorage

Configuration Options

| Option | Description | Protocol | |--------|-------------|----------| | Protocol Version | Select Pre-2025-11-25 or MCP 2025-11-25 | Both | | Skip DCR Tests | Bypass Dynamic Client Registration testing | Both | | Skip OAuth Flow | Skip token acquisition tests | Both | | Interactive Auth | Enable browser-based OAuth flow | Both | | Pre-configured Client | Use existing client credentials instead of DCR | Both | | Callback Port | Port for OAuth callback (default: 3000). Automatically finds next available port | Both | | Redirect URI | Full redirect URI registered with your IDP | Both | | Resource URI | Resource indicator for RFC 8707 (REQUIRED for 2025-11-25) | Both | | Privileged Tool Name | Tool name for scope challenge test (optional, for step-1.5) | 2025-11-25 | | Client ID Metadata URL | HTTPS URL for Client ID Metadata Document | 2025-11-25 | | Client ID/Secret | Pre-configured client credentials | Both | | Scope | OAuth scopes to request | Both | | Enable Debug | Capture and display HTTP request/response data for all server interactions | Both |

Test Categories

Pre-2025-11-25 Protocol

1. Protected Resource Metadata (RFC 9728)

• HTTPS transport validation
• Well-known endpoint discovery
• WWW-Authenticate header parsing
• Authorization server reference validation

2. Authorization Server Discovery (RFC 8414)

• HTTPS transport validation
• Standard and OIDC discovery
• Required endpoint validation
• PKCE support detection

3. Client Registration

• Preregistration: Validate existing client credentials
• Dynamic Client Registration (RFC 7591/7592): Client registration with various grant types
  • Response validation (HTTP 201, client_id, etc.)
  • Client management URI validation (RFC 7592)
  • Auto-correction for servers returning relative URLs

4. OAuth 2.1 Flow

• PKCE requirement (S256 or plain)
• Authorization code flow
• Token exchange validation

5. JWT Access Token Validation (RFC 9068)

• Token structure and encoding
• Required claims (iss, sub, exp, iat)
• Issuer validation against AS metadata
• JWKS endpoint and key verification

6. Protected Resource Access

• Bearer token authentication
• Access token validation

MCP 2025-11-25 Protocol (Additional Tests) 🆕

7. PKCE S256 Enforcement

• S256 method required (not optional)
• Plain method discouraged warning
• Code challenge validation

8. Resource Parameter (RFC 8707)

• Resource parameter in authorization request
• Resource parameter in token request
• Resource validation in token response
• JWT resource claim validation

9. Token Audience Validation

• JWT aud claim presence
• Audience matches resource parameter
• Multi-audience support
• Prevents token passthrough attacks

10. Step-Up Authorization

• Insufficient scope error detection
• Required scope parsing from error response
• Re-authorization with elevated scopes
• Retry limit enforcement
• Scope challenge test (optional): Tests complete flow with privileged tool

11. Private Key JWT Authentication

• JWKS configuration validation
• JWT assertion creation
• Token endpoint authentication
• Signature verification

Documentation

• COMPLIANCE-TESTER.md - Detailed test documentation
• CLAUDE.md - Development guide

Development

npm run build        # Compile TypeScript
npm test             # Run unit tests
npm run lint         # Check code style
npm run type-check   # Type validation

TLS Version Support

The compliance tester supports modern TLS protocols for secure HTTPS connections:

• TLS 1.3 ✅ (Preferred - Latest and most secure)
• TLS 1.2 ✅ (Minimum supported version)
• TLS 1.1 and below ❌ (Not supported for security reasons)

Powered by Node.js v22.14.0 with OpenSSL 3.0.15+quic.

Certificate Handling

The compliance tester allows self-signed certificates by default to facilitate testing and development. Certificate warnings are automatically tracked and displayed in the test results with remediation recommendations.

Certificate Warnings Tracked:

• ⚠️ Self-signed certificates
• ⚠️ Expired certificates
• ⚠️ Not-yet-valid certificates
• ⚠️ Hostname mismatches
• ⚠️ Untrusted CA chains

All warnings include:

• Certificate details (issuer, subject, validity dates)
• Clear description of the issue
• Recommended actions for resolution

Environment Variables

• DEBUG_CERTS: Enable detailed certificate verification debugging for HTTPS requests

  • Set to true or 1 to enable
  • Displays certificate details (subject, issuer, validity dates, fingerprint, TLS version)
  • Shows detailed error messages for common certificate issues
  • Provides remediation suggestions for certificate problems
  • Example: DEBUG_CERTS=true npm start

• NODE_TLS_REJECT_UNAUTHORIZED: Enforce strict TLS certificate validation

  • Default: 0 (allows self-signed certificates with warnings)
  • Set to 1 to enforce strict certificate validation (will reject self-signed certificates)
  • Example: NODE_TLS_REJECT_UNAUTHORIZED=1 npm start

Project Structure

• src/compliance/ - Compliance tester implementation
• src/client/ - DCR client library
• src/validation/ - RFC 7591 validators
• src/types/ - TypeScript definitions
• public/ - Web interface