docs: update OAuth configuration details and usage instructions in multiple files for clarity

Author: nickytonline

.cursorrules

@@ -105,13 +105,13 @@ The following environment variables are supported (see `src/config.ts`):
 
 ### OAuth Configuration (Optional)
 
-- `ENABLE_AUTH` - Enable OAuth authentication (default: false)
+- `ENABLE_AUTH` - Enable OAuth 2.1 authentication (default: false)
+- `OAUTH_ISSUER` - OAuth issuer URL (required if auth enabled)
 - `OAUTH_CLIENT_ID` - OAuth client ID (required if auth enabled)
 - `OAUTH_CLIENT_SECRET` - OAuth client secret (required if auth enabled)
-- `OAUTH_AUTH_ENDPOINT` - OAuth authorization endpoint (required if auth enabled)
-- `OAUTH_TOKEN_ENDPOINT` - OAuth token endpoint (required if auth enabled)
-- `OAUTH_SCOPE` - OAuth scope (default: "read")
-- `OAUTH_REDIRECT_URI` - OAuth redirect URI (required if auth enabled)
+- `OAUTH_AUDIENCE` - Expected audience in JWT tokens (optional but recommended)
+- `OAUTH_SCOPE` - OAuth scope (default: "openid profile email")
+- `OAUTH_REDIRECT_URI` - OAuth redirect URI (optional, defaults to BASE_URL/callback)
 
 ## Coding Guidelines
 
@@ -135,19 +135,38 @@ The following environment variables are supported (see `src/config.ts`):
 
 ## OAuth Implementation
 
-### Modular Authentication
+### Simple Binary Configuration
 
-The template includes optional OAuth 2.1 authentication that can be easily enabled or completely removed:
+The template includes optional OAuth 2.1 authentication with a simple on/off approach:
 
+- **Default**: No authentication required - server runs immediately with `ENABLE_AUTH=false`
+- **Enable When Needed**: Set `ENABLE_AUTH=true` and provide OAuth configuration
 - **Modular Design**: All OAuth code is in `src/auth/` directory
-- **Conditional Loading**: OAuth middleware only applies when `ENABLE_AUTH=true`
 - **Zero Impact When Disabled**: No performance overhead when authentication is disabled
 - **Easy Removal**: Delete `src/auth/` directory and remove auth import from `src/index.ts`
 
-### Authentication Patterns
+### Use Cases
 
-1. **External OAuth (Recommended)**: Use Pomerium or similar OAuth proxy
-2. **Built-in OAuth Server**: Use the provided OAuth implementation in `src/auth/`
+**Authentication Disabled** (`ENABLE_AUTH=false` or omitted):
+- Public MCP servers
+- Gateway-protected deployments (Pomerium, nginx with auth, etc.)
+- Development and testing
+- Internal corporate networks with perimeter security
+
+**Authentication Enabled** (`ENABLE_AUTH=true`):
+- Direct OAuth 2.1 with token validation
+- Self-contained secure deployment
+- Production servers without gateway infrastructure
+
+### Quick Setup
+
+To enable authentication, add to your `.env`:
+```bash
+ENABLE_AUTH=true
+OAUTH_ISSUER=https://your-provider.com
+OAUTH_CLIENT_ID=your-client-id
+OAUTH_CLIENT_SECRET=your-client-secret
+```
 
 ### Removing OAuth
 

.env.example

@@ -9,71 +9,58 @@ LOG_LEVEL=info
 # Defaults to http://localhost:PORT if not set (where PORT is the configured port)
 # BASE_URL=http://localhost:3000
 
-# Authentication Configuration (Optional)
-# Set ENABLE_AUTH=true to enable authentication
-ENABLE_AUTH=false
-
-# Authentication mode: "resource_server", "full", or "none" (default)
-AUTH_MODE=resource_server
-
 # ============================================================================
-# Resource Server Mode Configuration
-# ============================================================================
-# MCP server acts as a resource server and validates tokens from external OAuth providers
-# Commonly used with gateways that handle OAuth flows for enterprise deployments
-# Can also work with direct OAuth flows where clients get tokens themselves
-
-# OAuth issuer URL for token validation (required for resource_server mode)
-# Examples:
-#   Auth0: https://your-domain.auth0.com
-#   Okta: https://your-domain.okta.com
-#   Google: https://accounts.google.com
-OAUTH_ISSUER=https://your-domain.auth0.com
-
-# Expected audience in JWT tokens (optional)
-# If set, tokens must have this audience claim
-OAUTH_AUDIENCE=your-api-identifier
-
-# ============================================================================
-# Full Mode Configuration (OAuth Proxy + Resource Server)
+# Authentication Configuration (Optional)
 # ============================================================================
-# MCP server acts as both OAuth client (proxy to external IdP) AND resource server
-# Provides OAuth endpoints while delegating authentication to external providers
-# Production-ready but consider using resource_server mode with a gateway for enterprise deployments
-
-# OAuth client credentials (required for full mode)
-OAUTH_CLIENT_ID=your-client-id
-OAUTH_CLIENT_SECRET=your-client-secret
+# Default: No authentication required - server runs immediately
+# Enable when you need OAuth 2.1 authentication with token validation
+# ENABLE_AUTH=false
 
-# OAuth provider endpoints (required for full mode)
-OAUTH_AUTH_ENDPOINT=https://your-domain.auth0.com/authorize
-OAUTH_TOKEN_ENDPOINT=https://your-domain.auth0.com/oauth/token
+# When ENABLE_AUTH=true, configure your OAuth provider:
+# ENABLE_AUTH=true
+# OAUTH_ISSUER=https://your-provider.com
+# OAUTH_CLIENT_ID=your-client-id
+# OAUTH_CLIENT_SECRET=your-client-secret
 
-# OAuth configuration
-OAUTH_SCOPE=read
-# OAUTH_REDIRECT_URI=http://localhost:3000/callback  # Optional, defaults to BASE_URL/callback
+# Additional OAuth settings (optional)
+# OAUTH_AUDIENCE=your-api-identifier  # For token audience validation
+# OAUTH_SCOPE=openid profile email    # Default scope
+# OAUTH_REDIRECT_URI=http://localhost:3000/callback  # Defaults to BASE_URL/callback
 
 # ============================================================================
-# Example Configurations
+# Common OAuth Provider Examples
 # ============================================================================
 
-# Example: Auth0 Resource Server Mode
+# Auth0 Example:
 # ENABLE_AUTH=true
-# AUTH_MODE=resource_server
 # OAUTH_ISSUER=https://your-domain.auth0.com
+# OAUTH_CLIENT_ID=your-auth0-client-id
+# OAUTH_CLIENT_SECRET=your-auth0-client-secret
 # OAUTH_AUDIENCE=your-api-identifier
 
-# Example: Auth0 Full Mode
+# Okta Example:
 # ENABLE_AUTH=true
-# AUTH_MODE=full
-# OAUTH_CLIENT_ID=your-auth0-client-id
-# OAUTH_CLIENT_SECRET=your-auth0-client-secret
-# OAUTH_AUTH_ENDPOINT=https://your-domain.auth0.com/authorize
-# OAUTH_TOKEN_ENDPOINT=https://your-domain.auth0.com/oauth/token
-# OAUTH_SCOPE=read
-# OAUTH_REDIRECT_URI=http://localhost:3000/callback  # Optional, defaults to BASE_URL/callback
+# OAUTH_ISSUER=https://your-domain.okta.com
+# OAUTH_CLIENT_ID=your-okta-client-id
+# OAUTH_CLIENT_SECRET=your-okta-client-secret
 
-# Example: No Authentication Mode (Default)
-# Note: Consider enabling auth even for local development for security best practices
-# ENABLE_AUTH=false
-# AUTH_MODE=none
+# Google Example:
+# ENABLE_AUTH=true
+# OAUTH_ISSUER=https://accounts.google.com
+# OAUTH_CLIENT_ID=your-google-client-id.apps.googleusercontent.com
+# OAUTH_CLIENT_SECRET=your-google-client-secret
+
+# ============================================================================
+# Use Cases
+# ============================================================================
+# 
+# Auth Disabled (ENABLE_AUTH=false or omitted):
+# - Public MCP servers
+# - Gateway-protected deployments (Pomerium, nginx with auth, etc.)
+# - Development and testing
+# - Internal corporate networks with perimeter security
+#
+# Auth Enabled (ENABLE_AUTH=true):
+# - Direct OAuth 2.1 with token validation
+# - Self-contained secure deployment
+# - Production servers without gateway infrastructure

.github/copilot-instructions.md

@@ -74,6 +74,16 @@ See `src/config.ts` for all supported environment variables:
 - `SERVER_VERSION` - Server version
 - `LOG_LEVEL` - Logging level (error/warn/info/debug)
 
+### OAuth Configuration (Optional)
+
+- `ENABLE_AUTH` - Enable OAuth 2.1 authentication (default: false)
+- `OAUTH_ISSUER` - OAuth issuer URL (required if auth enabled)
+- `OAUTH_CLIENT_ID` - OAuth client ID (required if auth enabled)
+- `OAUTH_CLIENT_SECRET` - OAuth client secret (required if auth enabled)
+- `OAUTH_AUDIENCE` - Expected audience in JWT tokens (optional but recommended)
+- `OAUTH_SCOPE` - OAuth scope (default: "openid profile email")
+- `OAUTH_REDIRECT_URI` - OAuth redirect URI (optional, defaults to BASE_URL/callback)
+
 ## Common Patterns
 
 ### Adding a New MCP Tool
@@ -134,9 +144,30 @@ const port = config.PORT;
 const serverName = config.SERVER_NAME;
 ```
 
+## Authentication
+
+### Simple Binary Configuration
+
+The template includes optional OAuth 2.1 authentication:
+
+- **Default**: No authentication required (`ENABLE_AUTH=false`)
+- **Enable when needed**: Set `ENABLE_AUTH=true` and provide OAuth config
+- **Use cases**: Public servers (auth disabled) or secure deployments (auth enabled)
+
+### Quick Setup
+
+To enable authentication, add to `.env`:
+```bash
+ENABLE_AUTH=true
+OAUTH_ISSUER=https://your-provider.com
+OAUTH_CLIENT_ID=your-client-id
+OAUTH_CLIENT_SECRET=your-client-secret
+```
+
 ## Important Notes
 
 - **File extensions**: Use `.js` in import statements (TypeScript compilation requirement)
 - **OpenTelemetry ready**: Logger automatically correlates with OTel traces when configured
 - **Production ready**: Includes graceful shutdown, error handling, and structured logging
-- **Template usage**: This is a template - customize for your specific MCP server needs
+- **Template usage**: This is a template - customize for your specific MCP server needs
+- **Authentication**: Server starts immediately with no auth setup required, add OAuth when needed

CLAUDE.md

@@ -93,13 +93,13 @@ The following environment variables are supported (see `src/config.ts`):
 
 ### OAuth Configuration (Optional)
 
-- `ENABLE_AUTH` - Enable OAuth authentication (default: false)
+- `ENABLE_AUTH` - Enable OAuth 2.1 authentication (default: false)
+- `OAUTH_ISSUER` - OAuth issuer URL (required if auth enabled)
 - `OAUTH_CLIENT_ID` - OAuth client ID (required if auth enabled)
 - `OAUTH_CLIENT_SECRET` - OAuth client secret (required if auth enabled)
-- `OAUTH_AUTH_ENDPOINT` - OAuth authorization endpoint (required if auth enabled)
-- `OAUTH_TOKEN_ENDPOINT` - OAuth token endpoint (required if auth enabled)
-- `OAUTH_SCOPE` - OAuth scope (default: "read")
-- `OAUTH_REDIRECT_URI` - OAuth redirect URI (required if auth enabled)
+- `OAUTH_AUDIENCE` - Expected audience in JWT tokens (optional but recommended)
+- `OAUTH_SCOPE` - OAuth scope (default: "openid profile email")
+- `OAUTH_REDIRECT_URI` - OAuth redirect URI (optional, defaults to BASE_URL/callback)
 
 ## Logging Best Practices
 
@@ -124,19 +124,28 @@ When adding new tools to the MCP server:
 
 ## OAuth Implementation
 
-### Modular Authentication
+### Simple Binary Configuration
 
-The template includes optional OAuth 2.1 authentication that can be easily enabled or completely removed:
+The template includes optional OAuth 2.1 authentication with a simple on/off approach:
 
+- **Default**: No authentication required - server runs immediately
+- **Enable When Needed**: Set `ENABLE_AUTH=true` and provide OAuth config
 - **Modular Design**: All OAuth code is in `src/auth/` directory
-- **Conditional Loading**: OAuth middleware only applies when `ENABLE_AUTH=true`
 - **Zero Impact When Disabled**: No performance overhead when authentication is disabled
 - **Easy Removal**: Delete `src/auth/` directory and remove auth import from `src/index.ts`
 
-### Authentication Patterns
+### Use Cases
 
-1. **External OAuth (Recommended)**: Use Pomerium or similar OAuth proxy
-2. **Built-in OAuth Server**: Use the provided OAuth implementation in `src/auth/`
+**Authentication Disabled** (`ENABLE_AUTH=false` or omitted):
+- Public MCP servers
+- Gateway-protected deployments (Pomerium, nginx with auth, etc.)
+- Development and testing
+- Internal corporate networks with perimeter security
+
+**Authentication Enabled** (`ENABLE_AUTH=true`):
+- Direct OAuth 2.1 with token validation
+- Self-contained secure deployment
+- Production servers without gateway infrastructure
 
 ### Removing OAuth