Skip to content

Design: UniFi Network MCP behind LiteLLM

See openspec/changes/unifi-mcp-behind-litellm/proposal.md for the problem and for the decisions that Sean made on 2026-10-14.

The estate already runs three in-cluster MCP servers behind LiteLLM, and firewalla-mcp is the closest precedent: one namespace, one Deployment, one ClusterIP Service, one Cilium policy that admits only the litellm namespace, and one ExternalSecret. These facts of the server and of the estate shape the design:

  • The server unifi-network-mcp 0.38.1 serves MCP over Streamable HTTP on /mcp when UNIFI_MCP_HTTP_ENABLED=true. It binds 127.0.0.1 unless UNIFI_MCP_HOST says otherwise. HTTP starts for PID 1 only, and the image runs the console script as PID 1. The server has no caller authentication and no health endpoint. It validates the Host header against UNIFI_MCP_ALLOWED_HOSTS and answers 421 to a mismatch. A bare host in that list is normalized to host:*, so one hostname covers every port.
  • The image ghcr.io/sirkirby/unifi-network-mcp:0.38.1 is python:3.14-slim with the workspace installed by uv sync --frozen into /app/.venv. It sets no USER, so the Deployment sets one. The published wheel matches its git tag, and the security review of 2026-10-14 found no telemetry, no shell use and a policy gate on all 106 mutating tools.
  • The server signs in with a local UniFi OS account over a session. It opens a websocket to the controller for the tool unifi_recent_events. TLS verification is off by default (UNIFI_NETWORK_VERIFY_SSL=false).
  • Each secret accepts one spelling: plain, _FILE or _COMMAND. Two spellings at one level refuse startup with exit code 6.
  • The policy gate reads UNIFI_POLICY_NETWORK_<ACTION> for CREATE, UPDATE and DELETE. A refused call returns {"success": false, "error": "<Action> is disabled by policy for <category>. Set <variable>=true to enable."}.
  • Tool registration lazy exposes the meta-tools unifi_tool_index, unifi_execute, unifi_batch, unifi_batch_status and unifi_load_tools, plus two read-only tools. Domain tools load on demand through notifications/tools/list_changed, which LiteLLM does not relay. unifi_tool_index and unifi_execute need no registration.
  • The ExternalSecrets policy policy-external-secrets-operator.tf reads secret/data/fzymgc-house/cluster/* and nothing under infrastructure/.
  • The controller is the UCG-Fiber at 192.168.40.1 on Core, per docs/reference/network.md, and answers at unifi.fzymgc.house with a Let’s Encrypt certificate. The dns-control policy already allows egress to that address on 443 for the same reason.
  • LiteLLM derives a route id from the name, the URL, the transport, the auth type and the alias unless server_id pins it. A key grant names the id.

This change adds no address and no prefix, so docs/reference/network.md does not change. No field of this change is behind a full-replace API that Terraform manages.

Goals:

  • One read-only MCP route for the UniFi controller, reachable by the key claude-code through LiteLLM, with the smallest tool list in the client’s context.
  • The same shape as firewalla-mcp, so the runbooks and the policies read the same way.
  • No secret in git and no new Vault policy.

Non-Goals:

  • Write access through the route. The account is View Only and the gates are off. A later change can add a second route with a Full Management account and a scoped key.
  • The Protect and Access servers. Nothing in the estate runs Protect or Access.
  • Caller identity at the upstream. The server has no token validation, so an identity route in the shape of kubernetes is not possible. The virtual key is the caller.
  • A health endpoint. The server has none, and a sidecar for one is more than the route needs.

D-1. One Deployment in the namespace unifi-mcp, in the shape of firewalla-mcp

Section titled “D-1. One Deployment in the namespace unifi-mcp, in the shape of firewalla-mcp”

argocd/app-configs/unifi-mcp/ holds kustomization.yaml, namespace.yaml, external-secret.yaml, deployment.yaml, service.yaml and networkpolicy.yaml. argocd/cluster-app/templates/unifi-mcp.yaml is the Application, sync wave 6, with the same ignoreDifferences for the ExternalSecret as firewalla-mcp.yaml. The namespace joins both stateless exclusion lists of argocd/app-configs/velero/backup-schedule.yaml, because the pod holds no state.

The image is public on GHCR, so the Deployment has no imagePullSecrets. If the first pull fails with an authorization error, the fallback is the ghcr-pull-secret ExternalSecret of firewalla-mcp, which holds a read-only token.

Alternative: a Helm chart. The upstream ships none, and six manifests need no chart.

D-2. The image pin is a tag and a digest in deployment.yaml

Section titled “D-2. The image pin is a tag and a digest in deployment.yaml”

image: ghcr.io/sirkirby/unifi-network-mcp:0.38.1@sha256:07a42219f615aa6c4456e909ca03f1dad62da355ae2d23280092e0dcdf0e29e3, in the form of clickhouse-mcp. Renovate’s kubernetes manager reads argocd/**/*.yaml and moves the tag and the digest together. The kustomization has no images: entry, so the pin has one place.

Alternative: images: in kustomization.yaml, as firewalla-mcp does for a first-party image. That form carries a tag and no digest, and the digest is what proves the pull.

D-3. The server runs as a non-root user on a read-only root filesystem

Section titled “D-3. The server runs as a non-root user on a read-only root filesystem”

runAsUser: 65532, runAsNonRoot: true, readOnlyRootFilesystem: true, every capability dropped, and an emptyDir on /tmp. The venv under /app is world-readable, and the server writes nothing at runtime unless a settings file or a support bundle asks it to. Requests 50m and 128Mi, limits 500m and 512Mi: the server holds the tool catalogue and an event ring buffer, and the first tools/list compiles 210 tool schemas.

D-4. The HTTP transport binds every interface and allows one host

Section titled “D-4. The HTTP transport binds every interface and allows one host”
Variable Value
UNIFI_MCP_HTTP_ENABLED true
UNIFI_MCP_HOST 0.0.0.0
UNIFI_MCP_PORT 3000
UNIFI_MCP_ALLOWED_HOSTS unifi-mcp.unifi-mcp.svc.cluster.local

The only caller is LiteLLM, which dials the Service by its cluster DNS name. The bare name is normalized to host:*, so any port LiteLLM writes in Host matches. DNS rebinding protection stays on. The Deployment sets no UNIFI_MCP_HTTP_FORCE, because the server is PID 1.

The readiness and liveness probes are tcpSocket on 3000. The server answers the MCP client before the controller connects, so a controller outage does not restart the pod. An HTTP probe on /mcp would need the MCP Accept header and a session, and a wrong Host answers 421.

D-5. The credential is a copy of automation-readonly on a cluster path

Section titled “D-5. The credential is a copy of automation-readonly on a cluster path”

Sean decided on 2026-10-14 to reuse automation-readonly, the View Only account that scripts/unifi-readonly.sh uses from a workstation. The operator copies its username and password from secret/fzymgc-house/infrastructure/unifi/readonly to secret/fzymgc-house/cluster/unifi-mcp, and the ExternalSecret unifi-mcp-secrets projects both. The Deployment sets UNIFI_NETWORK_USERNAME and UNIFI_NETWORK_PASSWORD from the Secret, and no _FILE or _COMMAND spelling, so the server sees one spelling.

The controller runbook and the secrets reference list the new path as a second reader of the account. A rotation of the password updates both paths.

Alternatives: a Vault policy change so that the operator can point the ExternalSecret at the infrastructure/ path. That widens the policy for one field. A new account, as dns-control has with dns-control-observer. Sean chose the copy, and a later change can split the account.

D-6. The controller connection verifies TLS by hostname

Section titled “D-6. The controller connection verifies TLS by hostname”
Variable Value
UNIFI_NETWORK_HOST unifi.fzymgc.house
UNIFI_NETWORK_PORT 443
UNIFI_NETWORK_SITE default
UNIFI_NETWORK_VERIFY_SSL true

The server’s default is false. The console serves a certificate that the system trust store of the image verifies, and the repository forbids a skipped verification. The network policy allows egress to 192.168.40.1/32 on 443 and to kube-dns on 53, and nothing else. The websocket for events uses the same address and port.

D-7. Every gate is off and the registration mode is lazy

Section titled “D-7. Every gate is off and the registration mode is lazy”
Variable Value
UNIFI_POLICY_NETWORK_CREATE false
UNIFI_POLICY_NETWORK_UPDATE false
UNIFI_POLICY_NETWORK_DELETE false
UNIFI_NETWORK_TOOL_PERMISSION_MODE confirm
UNIFI_TOOL_REGISTRATION_MODE lazy

Two layers refuse a write: the gate in the server and the role of the account on the controller. The Deployment states the gate values although they equal the defaults, so a reader of the manifest sees the boundary without the upstream docs.

lazy keeps the first tools/list through LiteLLM to the meta-tools and two reads. An agent finds a tool with unifi_tool_index and runs it with unifi_execute. eager would put 210 tools into every client session, which is the cost this change removes. If the lazy mode’s unifi_load_tools confuses an agent because the loaded tools never appear, the fallback is meta_only, one value in the Deployment.

D-8. The LiteLLM route carries no upstream credential and no relay flag

Section titled “D-8. The LiteLLM route carries no upstream credential and no relay flag”
unifi_ro:
server_id: unifi_ro
url: "http://unifi-mcp.unifi-mcp.svc.cluster.local:3000/mcp"
transport: http
description: "UniFi Network controller MCP (in-cluster Service, read-only, View Only account)"

The server validates no bearer, so auth_type: bearer_token with a token would prove nothing, and oauth_passthrough would forward a Keycloak token that nothing reads. The route is the deepwiki shape on an in-cluster upstream. The server_id pin is the route name, as dns does, so a key grant and an access group name a stable id. The description names the disposition, because clickhouse_rw shows that the description is where a reader learns what a route can change.

The boundary is the pair of the key scope at LiteLLM and the Cilium ingress rule at the pod. LiteLLM’s health probe sends no credential, which this upstream accepts, so the route reads healthy.

D-9. No key changes, and the dotfiles template gains the route

Section titled “D-9. No key changes, and the dotfiles template gains the route”

The workstation MCP key that Claude Code and Codex send on every LiteLLM route belongs to a proxy_admin user and carries no object_permission list. LiteLLM v1.103.0-rc.1 was measured on 2026-09-27 to let such a key reach every route, so the key needs no /key/update. A 403 proof of the scope therefore uses a non-admin key, dns-agent-triage, whose only grant is the access group mcp-dns. The dotfiles template .chezmoitemplates/codex-mcp.json.tmpl gains the entry for both agents, with the same header secret as firewalla_ro. The dotfiles change is outside this repository.

A later consumer that is not a proxy_admin gets the route through object_permission or an access group that names the id unifi_ro, as docs/operations/litellm.md under “MCP client keys” describes.

  • [The websocket is refused for a View Only account] → unifi_recent_events returns an empty buffer and every REST read works. The server logs the refusal at startup. The acceptance reads devices, not events.
  • [LiteLLM does not relay tools/list_changed, so unifi_load_tools has no visible effect] → the runbook row tells the agent to use unifi_tool_index and unifi_execute. meta_only is the fallback.
  • [Anyone who reaches the pod can read the controller as View Only] → the Cilium policy admits the litellm namespace only. A pod in litellm is LiteLLM or its Valkey, both under the same operator.
  • [A future release of unifi-core or unifi-mcp-shared with a defect] → the image pins all three packages by lockfile, and the digest pin moves only through a Renovate pull request.
  • [The copy of the credential drifts from the source path] → the runbook names both paths in the rotation step of automation-readonly.
  • [The first tools/list is slow while 210 schemas compile] → LiteLLM’s probe timeout covers it, and the readiness probe is TCP, so the pod reads ready before the catalogue is warm.
  1. The operator writes secret/fzymgc-house/cluster/unifi-mcp before pull request 1 merges.
  2. Pull request 1 merges. ArgoCD creates the namespace and syncs the Application. The ExternalSecret resolves and the pod starts. Rollback: git revert of the merge commit and push. ArgoCD prunes the namespace. A fast stop without a revert is kubectl --context fzymgc-house -n unifi-mcp scale deployment/unifi-mcp --replicas=0, which self-heal undoes on the next sync, so the revert is the rollback.
  3. Pull request 2 merges. ArgoCD syncs litellm, which restarts the proxy with the route. Rollback: git revert of the merge commit and push. The route disappears on the next restart, and a key grant that names unifi_ro then names nothing, which LiteLLM ignores.
  4. The operator adds the route to the dotfiles template and runs the acceptance. Rollback: remove the entry from the template and apply.
  • Whether lazy or meta_only reads better in a Claude Code session through LiteLLM. Task 2.9 records the answer in the client runbook, and the value is one line of the Deployment.