[FEATURE] Configurable inbound MCP authentication for hosted gateway scenarios (Connector Namespaces)

[sajeetharan]

Feature Description

Make inbound MCP authentication on the toolkit configurable so the server can run cleanly behind an authenticated gateway (e.g., Azure Logic Apps Connector Namespaces managed MCP hosting) without requiring its own Entra app registration or enforcing duplicate client auth.

Today the server expects AzureAd:TenantId / AzureAd:ClientId and enforces JWT bearer validation. A DEV_BYPASS_AUTH / DevelopmentMode:BypassAuthentication flag exists for local/emulator scenarios only. We need a first-class, supported "hosted-behind-gateway" mode.

Problem or Use Case

The Cosmos DB MCP Toolkit is being onboarded to the Connector Namespaces hosted MCP platform. In that environment:

• Inbound auth is terminated at the connector namespace gateway.
• Only a few whitelisted headers are forwarded to the downstream MCP server.
• Tool-level authorization is handled outside the server (gateway/namespace access control).
• The server runs in an isolated sandbox; no IP allowlist needed inside the server.

Forcing the server to require its own Entra app registration in this scenario is duplicate work and blocks onboarding. The same shape is also useful for any reverse-proxy / API Management / APIM-as-AI-Gateway hosting pattern.

Proposed Solution

1. First-class config flag for inbound auth mode, e.g.:
   • Authentication:Mode = EntraJwt (current default) | Gateway (trust upstream) | None
   • Equivalent env var: MCP_AUTH_MODE
   • Rename / promote the existing DEV_BYPASS_AUTH from a dev-only switch to a supported configuration option (kept backward compatible).
2. When Mode=Gateway:
   • Skip JWT bearer validation entirely.
   • Do not require AzureAd:TenantId or AzureAd:ClientId.
   • Cosmos data-plane access continues to use DefaultAzureCredential (managed identity of the hosting compute).
3. Documented threat model for the Gateway mode: clear callout that the server MUST be deployed behind an authenticated gateway and not exposed publicly.
4. Startup validation: fail fast with a clear error message if Mode=EntraJwt and required config is missing; warn (not fail) if Mode=Gateway and the listener is reachable on a public ingress without a gateway sentinel header.
5. Optional caller identity propagation: if Connector Namespaces (or any gateway) forwards a known header (e.g., X-MS-CLIENT-PRINCIPAL), read it for logging/telemetry context only — never for authorization decisions. (Per Connector Namespaces team: today no caller identity headers are forwarded; design the hook so we can light it up later.)

Example Usage

# Hosted behind Connector Namespaces gateway — minimal contract
MCP_AUTH_MODE=Gateway
COSMOS_ENDPOINT=https://<account>.documents.azure.com:443/

# Standalone Entra-protected deployment (existing behavior, default)
MCP_AUTH_MODE=EntraJwt
AzureAd__TenantId=<tenant>
AzureAd__ClientId=<client>
COSMOS_ENDPOINT=https://<account>.documents.azure.com:443/

Alternatives Considered

• Keep the existing DEV_BYPASS_AUTH flag and document it for production gateway hosting — rejected because the name advertises "dev only" and discourages production use.
• Require all hosted deployments to ship their own Entra app registration — rejected; duplicates the gateway's auth layer and blocks Connector Namespaces onboarding.

Context

Tracking ask from the Connector Namespaces team for onboarding the Cosmos DB MCP Toolkit to their hosted MCP platform. Reference implementation pattern: Azure/data-api-builder.