Build Firewalla MCP server rather than adopt off-the-shelf amittell server
Date: 2026-06-20 Status: Accepted Decision: hl-93zf Deciders: Sean Brandt, Claude Opus 4.8
Context
Section titled “Context”The cluster needs programmatic Firewalla access for AI-agent triage (and, later, scoped firewall mutation). An off-the-shelf MCP server, amittell/firewalla-mcp-server (MIT, published Docker image + npm, MSP API v2, 28 tools, full CRUD), exists and was explicitly evaluated against building our own. The decision controls who holds the MSP personal access token — a credential with firewall rule and target-list mutation power — and which party governs the tool surface and write-safety guarantees.
Decision
Section titled “Decision”Build a self-owned Go MCP server (fzymgc-house/firewalla-mcp) following the engram pattern (own repo, distroless image, CI-published, deployed in-cluster behind agentgateway) rather than adopting the existing third-party server.
Rationale
Section titled “Rationale”- The MSP PAT grants firewall rule and target-list mutation; placing it inside third-party code is an unacceptable trust boundary.
- Self-ownership is required to enforce the read-only-first topology (separate gateway routes) rather than relying on third-party in-server logic.
- The engram / clickhouse-mcp pattern is already proven in this cluster and provides CI, a distroless image, and cluster-wiring templates, bounding the build cost.
Alternatives Considered
Section titled “Alternatives Considered”- Adopt
amittell/firewalla-mcp-server(rejected): zero build time and an existing tool surface, but third-party code would hold a firewall-management token, with no control over write-safety enforcement or the topological read-only boundary. - Build (engram pattern) (chosen): full control of tool surface and write-safety; no third-party code holds a firewall-mutation credential; matches the established cluster pattern.
Consequences
Section titled “Consequences”- Positive: trust boundary over firewall credentials is owned and auditable; write-safety enforced topologically (two routes); tool surface evolves on the operator’s schedule.
- Negative: ongoing maintenance burden for the server and its Go MCP SDK dependency.
- Neutral: follows the established engram pattern; implementation cost is bounded by the existing template.