From 78a7d1c1d019360a3d28fe5ecf0adcf7c341902b Mon Sep 17 00:00:00 2001
From: Basil Hosmer <basil@anthropic.com>
Date: Tue, 7 Oct 2025 16:56:03 -0400
Subject: [PATCH] Deduplicate OAuth provider replacement docs

Consolidate three redundant 'Production Replacement' sections into
a single canonical location in docs/oauth-architecture-patterns.md.
Both server READMEs now point to this guide.
---
 auth-server/README.md               | 11 +++----
 docs/oauth-architecture-patterns.md | 49 ++++++++++++++++++++++++-----
 mcp-server/README.md                | 20 ++----------
 3 files changed, 50 insertions(+), 30 deletions(-)

diff --git a/auth-server/README.md b/auth-server/README.md
index aff4f49..d2a6aff 100644
--- a/auth-server/README.md
+++ b/auth-server/README.md
@@ -98,14 +98,13 @@ npm run typecheck     # Type checking
 npm run build         # Build to dist/
 ```
 
-## Production Replacement
+## Production Usage
 
-Commercial OAuth providers supporting RFC 7662 introspection:
-- Auth0, Okta, Azure AD/Microsoft Entra
-- AWS Cognito, Google Identity Platform
-- GitHub OAuth
+This demo server should be replaced with a commercial OAuth provider in production.
 
-The MCP server integrates with any RFC 7662-compliant provider.
+See [OAuth Architecture Patterns](../docs/oauth-architecture-patterns.md#using-a-commercial-auth-provider) for detailed integration guidance.
+
+**Supported providers:** Auth0, Okta, Azure AD, AWS Cognito, Google, GitHub, and any RFC 7662-compliant OAuth provider.
 
 ## Redis Data
 
diff --git a/docs/oauth-architecture-patterns.md b/docs/oauth-architecture-patterns.md
index af8df69..12c000e 100644
--- a/docs/oauth-architecture-patterns.md
+++ b/docs/oauth-architecture-patterns.md
@@ -41,14 +41,49 @@ The current implementation demonstrates this pattern with separate authorization
 
 ### Using a Commercial Auth Provider
 
-Replacing the demo auth server with a commercial provider:
+The demo auth server should be replaced with a commercial OAuth provider in production.
 
-1. **Configure provider**: Set up OAuth app in commercial provider (e.g. Auth0/Okta)
-2. **Update metadata URL**: Point to provider's discovery endpoint
-3. **Configure introspection**: Set up token validation
-4. **Update redirect URIs**: Configure allowed callbacks
-5. **Migrate users**: Import existing users if needed
-6. **Test integration**: Verify full OAuth flow
+**Supported providers:**
+- Auth0, Okta, Azure AD/Microsoft Entra
+- AWS Cognito, Google Identity Platform
+- GitHub OAuth
+- Any RFC 7662-compliant OAuth provider
+
+#### Integration Steps
+
+1. **Configure provider**: Set up OAuth app in your provider
+   - Register your MCP server as a resource server
+   - Configure allowed redirect URIs
+   - Enable token introspection endpoint
+
+2. **Update MCP server environment** (`mcp-server/.env`):
+   ```bash
+   AUTH_SERVER_URL=https://your-tenant.auth0.com
+   # or https://your-domain.okta.com
+   # or https://login.microsoftonline.com/your-tenant
+   ```
+
+3. **Adjust token introspection** if needed (`mcp-server/src/auth/external-verifier.ts`):
+   ```typescript
+   // Most providers use RFC 7662 standard format, but some may differ
+   const response = await fetch(`${this.authServerUrl}/oauth/introspect`, {
+     method: 'POST',
+     headers: {
+       'Content-Type': 'application/x-www-form-urlencoded',
+       // Some providers require authentication here
+       'Authorization': `Basic ${Buffer.from('client_id:client_secret').toString('base64')}`
+     },
+     body: `token=${token}`
+   });
+   ```
+
+4. **Update redirect URIs**: Configure your provider's allowed callbacks to match your deployment URLs
+
+5. **Test the integration**: Verify the full OAuth flow with your provider
+
+**Note on token introspection:** Most providers use the RFC 7662 standard format. If your provider uses a non-standard format, you may need to adjust the response parsing in `mcp-server/src/auth/external-verifier.ts`.
+
+The MCP server code otherwise remains unchanged - it only needs to know where to validate tokens.
 
 ---
 
diff --git a/mcp-server/README.md b/mcp-server/README.md
index 974c763..57d707f 100644
--- a/mcp-server/README.md
+++ b/mcp-server/README.md
@@ -115,25 +115,11 @@ npm run typecheck     # Type checking
 npm run build         # Build to dist/
 ```
 
-## Production Adaptation
+## Production Usage
 
-To use a commercial OAuth provider:
+To use a commercial OAuth provider instead of the demo auth server, see [OAuth Architecture Patterns](../docs/oauth-architecture-patterns.md#using-a-commercial-auth-provider) for detailed integration guidance.
 
-1. Update `.env` with provider URL:
-```bash
-AUTH_SERVER_URL=https://your-tenant.auth0.com
-```
-
-2. Modify `src/auth/external-verifier.ts` for provider-specific introspection:
-```typescript
-const response = await fetch(`${this.authServerUrl}/oauth/introspect`, {
-  // Add provider-specific authentication
-})
-```
-
-3. Adjust response parsing if the introspection format differs from RFC 7662 standard
-
-The MCP server code otherwise remains unchanged.
+**Summary:** Update `AUTH_SERVER_URL` in `.env` to point to your provider. You may need to adjust `src/auth/external-verifier.ts` for provider-specific introspection formats, but the MCP server code otherwise remains unchanged.
 
 ## References