[Feature Request]: Option to completely remove Bearer token auth to MCP gateway

[CalebBartleMAA]

###Feature Summary
Briefly describe the issue or unexpected behavior.

I am doing auth using a frontend proxy that has proper OAuth and federation capabilities, thus I will not be leveraging any of the manual JWT generation on the MCP gateway side.

---

🧩 Affected Component

Select the area of the project impacted:

• [ X] mcpgateway - API
• mcpgateway - UI (admin panel)
• [] mcpgateway.wrapper - stdio wrapper
• [ X] Federation or Transports
• CLI, Makefiles, or shell scripts
• [X ] Container setup (Docker/Podman/Compose)
• Other (explain below)

---

🔁 Steps to Reproduce

1. Add MCP Server
2. Set Environment Variable to AUTH_REQUIRED: false
(This currently only disables the admin login, there isn't any separate environment variable to disable MCP Client Auth completely)

---

🤔 Expected Behavior

What should have happened instead?

We should be allowed to set an environment variable to disable MCP Client Auth

---

📓 Logs / Error Output

Paste any relevant stack traces or logs here.
⚠️ Do not paste secrets, credentials, or tokens.

---

🧠 Environment Info

You can retrieve most of this from the /version endpoint.

Key	Value
Version or commit	e.g. v0.9.0 or main@a1b2c3d
Runtime	e.g. Python 3.11, Gunicorn
Platform / OS	e.g. Ubuntu 22.04, macOS
Container	e.g. Docker, Podman, none

Running on Docker

🧩 Additional Context (optional)

Add any configuration details, flags, or related issues.

[crivetimihai]

Hi, converted this to an issue to add new config flags. Please me know if the assessment below makes sense.

Current Authentication Architecture

The MCP Gateway currently implements two distinct authentication mechanisms:

1. Admin UI Authentication

• Configuration: BASIC_AUTH_USER and BASIC_AUTH_PASSWORD
• Scope: Web-based admin panel at /admin
• Flow: HTTP Basic Auth → JWT cookie for session
• Purpose: Protect administrative interface

2. MCP Client Authentication

• Configuration: JWT_SECRET_KEY for token signing
• Scope: All API endpoints, SSE connections, WebSocket connections
• Flow: Bearer token in Authorization header or jwt_token cookie
• Token Generation: python3 -m mcpgateway.utils.create_jwt_token
• Purpose: Authenticate MCP client connections

The Problem

Currently, the AUTH_REQUIRED environment variable acts as a global switch that affects both authentication types, but doesn't fully disable JWT validation:

• When AUTH_REQUIRED=true (default): Both admin UI and MCP clients require authentication
• When AUTH_REQUIRED=false: Authentication becomes optional but JWT validation still occurs if tokens are provided

There is no way to completely bypass JWT bearer token authentication for MCP clients.

Your Use Case (Issue #705)

You have a legitimate enterprise deployment pattern:

User → Frontend Auth Proxy (OAuth/SAML) → MCP Gateway → MCP Servers

Your setup:

1. Frontend proxy (e.g., OAuth2 Proxy, Authelia, Cloudflare Access) handles all authentication
2. Proxy validates users against corporate identity provider (Okta, Auth0, Azure AD)
3. Proxy adds trusted headers like X-Authenticated-User or X-Remote-User
4. MCP Gateway should trust the proxy's authentication decision

Why Current Setup Doesn't Work

Even with AUTH_REQUIRED=false:

• Gateway still expects JWT tokens in the Authorization header
• Gateway validates tokens if provided (checking signature, expiration)
• Clients must generate and manage JWT tokens despite proxy authentication
• Adds unnecessary complexity when authentication is already handled upstream

Common Enterprise Patterns This Blocks

1. API Gateway Authentication: Kong, Traefik, AWS API Gateway handle auth
2. Identity-Aware Proxies: Google IAP, Cloudflare Access, Tailscale
3. Service Mesh: Istio/Linkerd with mTLS and identity propagation
4. Corporate SSO: Direct integration with SAML/OIDC providers

Proposed Solution

Add a new configuration option to completely disable MCP client JWT validation:

Option 1: Separate MCP Client Auth Toggle

# New environment variable
MCP_CLIENT_AUTH_ENABLED=false   # Completely skip JWT validation for MCP operations
AUTH_REQUIRED=true              # Still protect admin UI with basic auth

Option 2: Auth Mode Selection

# Authentication mode
AUTH_MODE=proxy        # Options: jwt (default), proxy, none
TRUST_PROXY_HEADERS=true
PROXY_USER_HEADER=X-Authenticated-User

Option 3: Granular Auth Control

# Separate controls for each auth type
ADMIN_UI_AUTH_ENABLED=true
MCP_CLIENT_AUTH_ENABLED=false
REQUIRE_TOKEN_VALIDATION=false

Implementation Considerations

Security Implications

• CRITICAL: This should only be enabled when MCP Gateway is behind a trusted proxy. Likely something we should flag in [SECURITY FEATURE]: Add Security Configuration Validation and Startup Checks #534
• Document clearly that disabling MCP auth removes a security layer
• Consider requiring explicit proxy trust configuration
• Maybe require setting TRUST_PROXY=true as a safety check

Code Changes Needed

1. config.py: Add new configuration variable(s)
2. verify_credentials.py: Modify require_auth() to skip validation when disabled
3. main.py: Update middleware to respect new settings
4. WebSocket endpoint: Currently has no auth - needs to be addressed

Header Passthrough Integration

• When proxy auth is enabled, automatically trust and use proxy headers
• Map proxy user header to the internal user context
• Ensure X-Authenticated-User or similar is available to downstream services

Benefits of Supporting This

1. Enterprise Ready: Aligns with standard enterprise deployment patterns
2. Simplified Operations: No need to manage JWT tokens when using proxy auth
3. Better Integration: Works seamlessly with existing auth infrastructure
4. Flexibility: Supports multiple authentication strategies

Recommended Approach

1. Implement MCP_CLIENT_AUTH_ENABLED as a separate toggle
2. Keep AUTH_REQUIRED for backward compatibility (controls admin UI)
3. Add safety checks to ensure proxy configuration when auth is disabled
4. Document the security implications clearly
5. Add examples for common proxy configurations (OAuth2 Proxy, Authelia, etc.)

Migration Path

For existing users:

• Default behavior unchanged (MCP_CLIENT_AUTH_ENABLED=true)
• AUTH_REQUIRED=false continues to work as before
• New option is opt-in for proxy authentication scenarios

Testing Requirements

1. Test with MCP_CLIENT_AUTH_ENABLED=false and no proxy (should warn)
2. Test with proxy headers being correctly passed through
3. Ensure admin UI auth still works independently
4. Verify WebSocket connections respect the new setting
5. Test federation scenarios with mixed auth modes

Documentation Updates Needed

1. Add "Proxy Authentication" section to deployment docs
2. Create example configurations for common proxies
3. Add security best practices guide
4. Update environment variable reference
5. Add architecture diagram showing proxy auth flow

[crivetimihai]

@CalebBartleMAA PR #710 is now available for review.

[CalebBartleMAA]

This is perfect @crivetimihai, thank you for taking the time to review this in detail.

[crivetimihai]

@CalebBartleMAA does it work for you, and can we merge the PR closing this issue?