Split read and write Firewalla MCP routes at the gateway for topology-enforced blast-radius
Date: 2026-06-20 Status: Accepted Decision: hl-rzrg Deciders: Sean Brandt, Claude Opus 4.8
Context
Section titled “Context”The Firewalla MSP API exposes write endpoints (rule create/pause/resume, target-list CRUD, alarm delete) that mutate live firewall policy. A v1 read-only MCP server is valuable for triage, but the path to enabling writes must not depend on trusting in-server logic alone to prevent mutation. The agentgateway supports per-route backends, HTTPRoutes, and auth/access policies.
Decision
Section titled “Decision”Expose the Firewalla MCP server on two separate agentgateway routes — /mcp/firewalla-ro for v1 read-only tools and a future /mcp/firewalla-rw for scoped writes — so the read-only blast-radius boundary is enforced by topology rather than by in-server logic.
Rationale
Section titled “Rationale”- A firewall-management credential warrants a stronger guarantee than in-server logic: a route that does not exist cannot be misused, whereas write tools gated by a flag can be exposed by a bug or misconfiguration.
- The two-route model makes enabling writes an explicit, reviewable infrastructure change (a new Backend/HTTPRoute/Policy PR) rather than a code flag flip.
- The agentgateway’s per-route AgentgatewayPolicy already supports this pattern (established in hl-nhi).
Alternatives Considered
Section titled “Alternatives Considered”- Single route; server enforces read-only via internal logic (rejected): simpler, but the blast-radius guarantee depends on server code, and adding writes later needs no structural change — so a bug could expose mutation prematurely.
- Two gateway routes (ro v1, rw deferred) (chosen): read-only guarantee is topological; clients on the ro route structurally cannot reach write tools; write enablement is an auditable infra change.
Consequences
Section titled “Consequences”- Positive: read-only guarantee survives server bugs or future tool additions; write enablement requires an explicit reviewable PR; per-route VK policies can grant different clients ro vs rw access.
- Negative: write tools must be served conditionally per route, and enabling writes adds a second Backend/HTTPRoute/Policy.
- Neutral: consistent with how other high-stakes MCP backends could be split in future.