Skip to content
fzymgc-house Cluster Docs

Per-server path-routed MCP gateway with per-upstream client-auth choice (OAuth or VK)

Date: 2026-06-07 Status: Accepted Decision: hl-nhi Deciders: Sean, Claude

Context

Section titled “Context”

The MCP gateway fronts six servers with distinct trust profiles: engram is an internal OAuth Resource Server needing per-user JWT validation; exa/firecrawl/context7/fal are SaaS upstreams needing a static virtual-key for client auth plus a per-server bearer injected toward the upstream; deepwiki needs client auth but no upstream key. This mixed auth topology cannot be a single shared listener mode.

Decision

Section titled “Decision”

Deploy one AgentgatewayBackend + HTTPRoute + AgentgatewayPolicy per MCP server under mcp-gw.fzymgc.house/mcp/. engram uses traffic.jwtAuthentication (OAuth/JWT + mock-DCR clientId); SaaS servers use traffic.apiKeyAuthentication (the vk_claude_code virtual key) for the client plus backend.auth.secretRef to inject each server’s bearer to the upstream; deepwiki uses VK client auth with no upstream key.

Rationale

Section titled “Rationale”
  • Operator requirement: maximal per-upstream independence in path, auth mode, and upstream key.\n- engram stays an OAuth Resource Server, extending hl-23m’s trust model into the CRD path; SaaS upstreams use static bearer (correct for keys the operator controls server-side).\n- Per-server Secrets via ESO in two shapes (VK accept-list; per-SaaS Authorization bearer) keep upstream keys out of git.\n- One resource set per server makes each auth contract explicit + auditable.

Alternatives Considered

Section titled “Alternatives Considered”
  • Single MCP listener with one shared auth mode (rejected): cannot express mixed OAuth + VK across servers, nor per-server upstream-key injection.\n- One Backend + HTTPRoute + Policy per server (chosen): full per-server independence; adding a server is additive.

Consequences

Section titled “Consequences”
  • Positive: future MCP upstreams independently choose OAuth or VK without touching existing servers; SaaS keys injected server-side, never exposed to clients; engram OAuth defense-in-depth (hl-23m) preserved.\n- Negative: six sets of CRs to author/maintain; two distinct ESO Secret shapes must stay structurally distinct.\n- Neutral: deepwiki (VK, no upstream key) is the degenerate case confirming the pattern generalizes.