Design: UniFi Network MCP behind LiteLLM
Context
Section titled “Context”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-mcp0.38.1 serves MCP over Streamable HTTP on/mcpwhenUNIFI_MCP_HTTP_ENABLED=true. It binds127.0.0.1unlessUNIFI_MCP_HOSTsays 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 theHostheader againstUNIFI_MCP_ALLOWED_HOSTSand answers421to a mismatch. A bare host in that list is normalized tohost:*, so one hostname covers every port. - The image
ghcr.io/sirkirby/unifi-network-mcp:0.38.1ispython:3.14-slimwith the workspace installed byuv sync --frozeninto/app/.venv. It sets noUSER, 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,
_FILEor_COMMAND. Two spellings at one level refuse startup with exit code 6. - The policy gate reads
UNIFI_POLICY_NETWORK_<ACTION>forCREATE,UPDATEandDELETE. A refused call returns{"success": false, "error": "<Action> is disabled by policy for <category>. Set <variable>=true to enable."}. - Tool registration
lazyexposes the meta-toolsunifi_tool_index,unifi_execute,unifi_batch,unifi_batch_statusandunifi_load_tools, plus two read-only tools. Domain tools load on demand throughnotifications/tools/list_changed, which LiteLLM does not relay.unifi_tool_indexandunifi_executeneed no registration. - The ExternalSecrets policy
policy-external-secrets-operator.tfreadssecret/data/fzymgc-house/cluster/*and nothing underinfrastructure/. - The controller is the UCG-Fiber at
192.168.40.1on Core, perdocs/reference/network.md, and answers atunifi.fzymgc.housewith 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_idpins 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 / Non-Goals
Section titled “Goals / Non-Goals”Goals:
- One read-only MCP route for the UniFi controller, reachable by the key
claude-codethrough 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
kubernetesis 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.
Decisions
Section titled “Decisions”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.
Risks / Trade-offs
Section titled “Risks / Trade-offs”- [The websocket is refused for a View Only account] →
unifi_recent_eventsreturns 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, sounifi_load_toolshas no visible effect] → the runbook row tells the agent to useunifi_tool_indexandunifi_execute.meta_onlyis the fallback. - [Anyone who reaches the pod can read the controller as View Only] → the Cilium policy admits
the
litellmnamespace only. A pod inlitellmis LiteLLM or its Valkey, both under the same operator. - [A future release of
unifi-coreorunifi-mcp-sharedwith 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/listis 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.
Migration Plan
Section titled “Migration Plan”- The operator writes
secret/fzymgc-house/cluster/unifi-mcpbefore pull request 1 merges. - Pull request 1 merges. ArgoCD creates the namespace and syncs the Application. The
ExternalSecret resolves and the pod starts. Rollback:
git revertof the merge commit and push. ArgoCD prunes the namespace. A fast stop without a revert iskubectl --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. - Pull request 2 merges. ArgoCD syncs
litellm, which restarts the proxy with the route. Rollback:git revertof the merge commit and push. The route disappears on the next restart, and a key grant that namesunifi_rothen names nothing, which LiteLLM ignores. - The operator adds the route to the dotfiles template and runs the acceptance. Rollback: remove the entry from the template and apply.
Open Questions
Section titled “Open Questions”- Whether
lazyormeta_onlyreads 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.