feat(upstream-auth): inherit auth format from interceptors.auth when upstream_mcp.auth omitted

When upstream_mcp.auth is absent, the gateway now derives the outbound auth
format from interceptors.auth using the same priority-based selection as
outbound OpenAPI calls (sort by priority, first non-oauth/session-cookie entry).
Only bearer/query/custom-header types are inherited.

On HTTP transport the downstream client's session token is always the credential;
the inherited config only controls the format (Bearer header, custom header, or
query param). On stdio, value_from_env from the effective auth (upstream_mcp.auth
or inherited from interceptors.auth) is used as the service-account credential.

The security gate (reject anonymous HTTP sessions when auth is configured) now
triggers on any effective auth — direct or inherited.

This eliminates the need to duplicate auth configuration when the upstream MCP
server accepts the same format as inbound clients (the common case).

Agent authored

Author: David Ruzicka

docs/PROFILE-GUIDE.md

@@ -104,52 +104,63 @@ When `enterprise_authorization.mode` is `required`, HTTP initialization accepts
 
 - `transport.type` must be `"http-streamable"`
 - `transport.url` must be an absolute `http` or `https` URL without inline credentials
-- `auth.type` may be `bearer`, `query`, or `custom-header`
-- `auth.value_from_env` names the env variable holding the credential — **stdio transport only**. On HTTP transport the downstream client's session Bearer token is always forwarded directly to the upstream; `value_from_env` is never read and may be omitted. Inline secrets are not supported for any auth type.
+- `auth` is **optional**. When omitted, the auth format is inherited from `interceptors.auth` (see below).
+- `auth.type` may be `bearer`, `query`, or `custom-header`. Set explicitly only when the upstream expects a different format than inbound clients use.
+- `auth.value_from_env` names the env variable holding the credential — **stdio transport only**. On HTTP transport the downstream client's session token is always forwarded directly; `value_from_env` is never read.
 - `upstream_mcp_from_env` must point to a single JSON object and takes precedence over static `upstream_mcp`
 - `stdio` upstream definitions are intentionally rejected in this iteration so the later feature-gated implementation can add process lifecycle hardening separately
 
-Example:
+#### Auth inheritance from `interceptors.auth`
+
+When `upstream_mcp.auth` is omitted, the gateway inherits the auth format from `interceptors.auth` using the same priority-based selection as outbound OpenAPI calls. Only `bearer`, `query`, and `custom-header` types are inherited — `oauth` and `session-cookie` are not forwarded.
+
+**Common case — client Bearer token forwarded as Bearer to upstream (zero config):**
 
 ```json
 {
-  "upstream_mcp_from_env": "MCP4_UPSTREAM_MCP_JSON",
+  "interceptors": {
+    "auth": { "type": "bearer", "value_from_env": "MY_API_TOKEN" }
+  },
   "upstream_mcp": {
     "name": "remote-mcp",
-    "transport": {
-      "type": "http-streamable",
-      "url": "https://remote-mcp.example/mcp"
-    },
-    "auth": {
-      "type": "bearer",
-      "value_from_env": "REMOTE_MCP_TOKEN"
-    },
-    "tool_prefix": "remote",
-    "tools": {
-      "allow": ["github_*"],
-      "deny": ["admin_*"]
-    },
-    "timeout_ms": 30000
+    "transport": { "type": "http-streamable", "url": "https://remote-mcp.example/mcp" }
   }
 }
 ```
 
-For HTTP session-passthrough deployments (client's own token forwarded upstream), omit `value_from_env`:
+The client's `Authorization: Bearer <token>` is extracted from the inbound request and forwarded as-is to the upstream. If the inbound request carries no token, the upstream connection is refused. On stdio, `value_from_env` from `interceptors.auth` is used as the service-account credential.
+
+**Override — upstream expects a different format than inbound clients:**
 
 ```json
 {
+  "interceptors": {
+    "auth": { "type": "custom-header", "header_name": "X-Client-Key", "value_from_env": "CLIENT_KEY" }
+  },
   "upstream_mcp": {
     "name": "remote-mcp",
-    "transport": {
-      "type": "http-streamable",
-      "url": "https://remote-mcp.example/mcp"
-    },
+    "transport": { "type": "http-streamable", "url": "https://remote-mcp.example/mcp" },
     "auth": { "type": "bearer" }
   }
 }
 ```
 
-The client's `Authorization: Bearer <token>` sent to the gateway is forwarded as-is to the upstream. If the inbound request carries no token, the upstream connection is refused.
+Clients authenticate with `X-Client-Key`; gateway forwards to upstream as `Authorization: Bearer`.
+
+**Explicit `value_from_env` on `upstream_mcp.auth` (stdio only):**
+
+```json
+{
+  "upstream_mcp": {
+    "name": "remote-mcp",
+    "transport": { "type": "http-streamable", "url": "https://remote-mcp.example/mcp" },
+    "auth": { "type": "bearer", "value_from_env": "UPSTREAM_TOKEN" },
+    "tool_prefix": "remote",
+    "tools": { "allow": ["github_*"], "deny": ["admin_*"] },
+    "timeout_ms": 30000
+  }
+}
+```
 
 **Profile selection**: If you set `profile_id` (or `profile_aliases`) and `openapi_spec_path`, you can launch the server with `--profile <id>` or `MCP4_PROFILE=<id>` without setting `--openapi-spec-path` or `MCP4_OPENAPI_SPEC_PATH`.
 

src/mcp/mcp-server.ts

@@ -50,7 +50,7 @@ import { OAUTH_RATE_LIMIT } from '../core/constants.js';
 import { HttpClient } from '../transport/interceptors.js';
 import { HttpClientFactory } from '../transport/http-client-factory.js';
 import { SchemaValidator } from '../validation/schema-validator.js';
-import type { Profile, ToolDefinition, AuthInterceptor, OAuthConfig, ProxyDownloadOperation, UpstreamMcpServerConfig } from '../types/profile.js';
+import type { Profile, ToolDefinition, AuthInterceptor, OAuthConfig, ProxyDownloadOperation, UpstreamMcpServerConfig, UpstreamMcpAuthConfig } from '../types/profile.js';
 import type { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { sanitizeToolList, isValidUpstreamToolName, applyProviderToolPolicy, isToolAllowedByProviderPolicy } from '../upstream/upstream-tool-sanitizer.js';
 import { UpstreamConnectionManager } from '../upstream/upstream-connection-manager.js';
@@ -1834,37 +1834,62 @@ export class MCPServer {
     return this.profile?.upstream_mcp;
   }
 
+  /**
+   * Resolve the effective upstream auth config for a provider.
+   * If upstream_mcp.auth is explicitly set, use it as-is.
+   * Otherwise inherit from interceptors.auth using the same selection logic as
+   * AuthStrategyRegistry (priority sort, first non-oauth/session-cookie entry).
+   * Only bearer/query/custom-header types are inherited — oauth and session-cookie
+   * cannot be meaningfully forwarded to an upstream MCP server.
+   */
+  private getEffectiveUpstreamAuth(provider: UpstreamMcpServerConfig): UpstreamMcpAuthConfig | undefined {
+    if (provider.auth) return provider.auth;
+    const raw = this.profile?.interceptors?.auth;
+    if (!raw) return undefined;
+    const configs = Array.isArray(raw) ? raw : [raw];
+    const sorted = [...configs].sort((a, b) => (a.priority ?? 0) - (b.priority ?? 0));
+    const selected = sorted.find(c => !['oauth', 'session-cookie'].includes(c.type)) ?? sorted[0];
+    if (!selected || !['bearer', 'query', 'custom-header'].includes(selected.type)) return undefined;
+    return {
+      type: selected.type as UpstreamMcpAuthConfig['type'],
+      header_name: selected.header_name,
+      query_param: selected.query_param,
+      value_from_env: selected.value_from_env,
+    };
+  }
+
   /**
    * Extract the auth token to use for upstream MCP calls.
-   * Downstream client token takes precedence; value_from_env acts as local fallback
-   * only for non-HTTP contexts (stdio) where there is no session concept.
+   * On HTTP transport the downstream client's session token is always forwarded directly.
+   * On stdio, value_from_env from the effective auth config (upstream_mcp.auth or inherited
+   * from interceptors.auth) is used as the service-account credential.
    *
-   * Security invariant: for HTTP transport, value_from_env (server-held upstream credential)
-   * is NEVER used — an HTTP session with no verified client token is an anonymous session
-   * (e.g. allowed by hasServerEnvAuthToken on the inbound side) and must not receive
-   * privileged upstream access. This closes the open-proxy escalation path regardless of
-   * whether inbound auth is configured.
+   * Security invariant: if any auth is configured (directly or inherited), an HTTP session
+   * with no verified client token is rejected — prevents anonymous clients from reaching
+   * privileged upstream resources.
    */
-  private getUpstreamToken(sessionId: string | undefined, profileId: string | undefined, provider: UpstreamMcpServerConfig): string | undefined {
+  private getUpstreamToken(
+    sessionId: string | undefined,
+    profileId: string | undefined,
+    provider: UpstreamMcpServerConfig,
+    effectiveAuth: UpstreamMcpAuthConfig | undefined,
+  ): string | undefined {
     if (this.httpTransport && sessionId && profileId) {
       const sessionToken = this.httpTransport.getSessionToken(profileId, sessionId);
       if (sessionToken) return sessionToken;
-      // HTTP session carries no verified client token — refuse to connect upstream
-      // on behalf of an anonymous caller. value_from_env is stdio-only and is never
-      // read on HTTP transport; its presence here signals an explicit auth requirement.
-      if (provider.auth?.value_from_env) {
+      // Reject anonymous HTTP sessions when auth is configured (directly or inherited)
+      if (effectiveAuth) {
         throw new UpstreamConnectionError(
           'upstream_mcp proxy requires an authenticated HTTP session — ' +
-          'the inbound client must supply a Bearer token ' +
-          '(value_from_env has no effect on HTTP transport).',
+          'the inbound client must supply a verified token.',
           provider.name,
         );
       }
       return undefined;
     }
-    // Non-HTTP path (stdio): no session concept; value_from_env allowed for service-account use.
-    if (provider.auth?.value_from_env) {
-      return process.env[provider.auth.value_from_env];
+    // Non-HTTP path (stdio): use value_from_env from effective auth (may come from interceptors.auth)
+    if (effectiveAuth?.value_from_env) {
+      return process.env[effectiveAuth.value_from_env];
     }
     return undefined;
   }
@@ -1892,8 +1917,10 @@ export class MCPServer {
       });
     }
     try {
-      const token = this.getUpstreamToken(sessionId, profileId, provider);
-      const client = await this.getUpstreamClientFn!(sessionId, provider, token);
+      const effectiveAuth = this.getEffectiveUpstreamAuth(provider);
+      const effectiveProvider = effectiveAuth !== provider.auth ? { ...provider, auth: effectiveAuth } : provider;
+      const token = this.getUpstreamToken(sessionId, profileId, provider, effectiveAuth);
+      const client = await this.getUpstreamClientFn!(sessionId, effectiveProvider, token);
       const result = await client.listTools();
       if (!result || typeof result !== 'object') {
         throw new UpstreamMalformedResponseError(
@@ -1986,8 +2013,10 @@ export class MCPServer {
     }
 
     try {
-      const token = this.getUpstreamToken(sessionId, profileId, provider);
-      const client = await this.getUpstreamClientFn!(sessionId, provider, token);
+      const effectiveAuth = this.getEffectiveUpstreamAuth(provider);
+      const effectiveProvider = effectiveAuth !== provider.auth ? { ...provider, auth: effectiveAuth } : provider;
+      const token = this.getUpstreamToken(sessionId, profileId, provider, effectiveAuth);
+      const client = await this.getUpstreamClientFn!(sessionId, effectiveProvider, token);
       const result = await (provider.timeout_ms !== undefined
         ? client.callTool({ name: toolName, arguments: args }, undefined, { timeout: provider.timeout_ms })
         : client.callTool({ name: toolName, arguments: args }));