Use VK + static upstream bearer auth for Firewalla MCP (not per-user OIDC)
Date: 2026-06-20 Status: Accepted Decision: hl-nmix Deciders: Sean Brandt, Claude Opus 4.8
Context
Section titled “Context”The cluster agentgateway supports two client-auth modes: per-user JWT/OAuth (used by engram) and VK + static upstream bearer (used by SaaS MCP upstreams and clickhouse-mcp). The Firewalla MCP server holds a firewall-management credential and must authenticate both inbound clients (at the gateway) and the upstream MSP API. The choice determines audit-trail granularity and the operational complexity of the auth stack.
Decision
Section titled “Decision”Authenticate gateway clients via a virtual key (vk_firewalla) and inject a static bearer from gateway to server, mirroring the clickhouse-mcp pattern, rather than adopting engram’s per-user OIDC. (Relates to hl-nhi; this is a per-app instantiation, not a supersession.)
Rationale
Section titled “Rationale”- A read-only triage tool with known, operator-controlled clients does not require per-user JWT identity; adding OIDC would be premature complexity.
- The clickhouse-mcp VK+bearer pattern is proven, already codified in hl-nhi, and avoids the Authentik DCR workaround (hl-23m).
- A NetworkPolicy (ingress only from the gateway namespace) plus a server-side bearer middleware provides the required in-cluster trust boundary without per-user identity.
- The choice is revisable when writes are enabled — the rw route can adopt JWT if per-user accountability is later required.
Alternatives Considered
Section titled “Alternatives Considered”- Per-user OIDC (JWT, engram pattern) (rejected): per-user audit trail and alignment with the MCP Resource Server model (hl-23m), but heavier operational complexity for a read-only tool and requires the Authentik DCR mock short-circuit.
- VK + static upstream bearer (clickhouse-mcp pattern) (chosen): sufficient for read-only triage with operator-controlled clients; no DCR workaround; lighter operational surface.
Consequences
Section titled “Consequences”- Positive: simpler operational auth stack for v1; no dependency on Authentik DCR; consistent with the established SaaS-upstream auth pattern.
- Negative: server-level audit logs do not distinguish individual gateway clients sharing the VK; per-user accountability for writes would need a different auth mode on the rw route.
- Neutral: the VK accept-list in
agentgateway-vkeysprovides the client allow-list boundary.