Record the MCP server deployment decisions in the spec #36

2026-09-23T01:56:40Z

dev-agent commented

2026-09-23 01:56:40 +00:00

Records a design session on MCP server deployment in two steps. First a standalone amendment (commit 31bef59, for review on its own), then that amendment folded into the spec and removed, as with the Tiered Inference amendment.

What changed in the spec

Part F is now F1–F4 and applies to all agents.
- F1: every agent gets its own VM, justified by inter-agent isolation and per-agent credential attribution. Docker-in-Docker stays in B3 as an extra reason that applies only to the Dev Agent.
- F2: each agent instance has its own default-deny egress allowlist, declared as an artifact. It covers what the agent's MCP servers reach, and it calls out that the tailnet (100.64.0.0/10) is not RFC1918.
- F3: MCP servers run per agent VM, one instance per (service, site, privilege). Site is part of the server's identity, and read-only and elevated access use separate credentials. Records the rejected routed-meta-tools alternative.
- F4: the existing image pipeline, plus a carve-out: third-party MCP images are digest-pinned and excluded from Watchtower.
Part 0: site identifiers garrett-hall and hartman-hut.
A7: a Vaultwarden machine account per MCP server instance, in addition to the agent's own. (Settled with the operator while drafting.)
C2: every write, including a reversible restart, requires an approved plan first. The tiers govern execution within that plan. (Settled with the operator while drafting.)
B3 / C3 / C5: recast to match F1–F3. MCP becomes the primary path to Proxmox and UniFi.
Part H: the network-gear browser item is narrowed to fallback access, and relocating stateful MCP servers is parked.

🤖 Generated with Claude Code

Records a design session on MCP server deployment in two steps. First a standalone amendment (commit 31bef59, for review on its own), then that amendment folded into the spec and removed, as with the Tiered Inference amendment. ## What changed in the spec - **Part F is now F1–F4 and applies to all agents.** - F1: every agent gets its own VM, justified by inter-agent isolation and per-agent credential attribution. Docker-in-Docker stays in B3 as an extra reason that applies only to the Dev Agent. - F2: each agent instance has its own default-deny egress allowlist, declared as an artifact. It covers what the agent's MCP servers reach, and it calls out that the tailnet (100.64.0.0/10) is not RFC1918. - F3: MCP servers run per agent VM, one instance per (service, site, privilege). Site is part of the server's identity, and read-only and elevated access use separate credentials. Records the rejected routed-meta-tools alternative. - F4: the existing image pipeline, plus a carve-out: third-party MCP images are digest-pinned and excluded from Watchtower. - **Part 0:** site identifiers `garrett-hall` and `hartman-hut`. - **A7:** a Vaultwarden machine account per MCP server instance, in addition to the agent's own. *(Settled with the operator while drafting.)* - **C2:** every write, including a reversible restart, requires an approved plan first. The tiers govern execution within that plan. *(Settled with the operator while drafting.)* - **B3 / C3 / C5:** recast to match F1–F3. MCP becomes the primary path to Proxmox and UniFi. - **Part H:** the network-gear browser item is narrowed to fallback access, and relocating stateful MCP servers is parked. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

dev-agent added 2 commits 2026-09-23 01:56:40 +00:00

Add the MCP deployment amendment 31bef59151

Records a design session on MCP server deployment as a standalone
amendment, ahead of folding it into the spec:

- Every agent gets its own VM, justified by inter-agent isolation and
  per-agent credential attribution; Docker-in-Docker stays as an extra
  Dev Agent reason rather than the rule's foundation
- Egress is a declared, per-agent-instance default-deny allowlist,
  covering what MCP servers reach on the agent's behalf, with the
  tailnet's 100.64.0.0/10 called out as outside RFC1918
- MCP servers run per agent VM, one instance per (service, site,
  privilege), with site in the server identity rather than a tool
  argument
- Third-party MCP images are digest-pinned and excluded from Watchtower
- Routed meta-tools rejected; stateful-server relocation parked

Two consequences settled with the operator while drafting: each MCP
server instance gets its own Vaultwarden machine account (A7), and any
write, reversible or not, requires an approved plan (C2).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Fold the MCP deployment amendment into the spec

CI / checks (push) Skipped

CI / checks (pull_request) Successful in 1m4s

Details

cdc3881deb

Part F is restructured around rules that now apply to every agent:

- F1: every agent gets its own VM, for inter-agent isolation and
  per-agent credential attribution
- F2: a declared, per-instance default-deny egress allowlist that
  covers MCP servers' reach, with the tailnet's 100.64.0.0/10 called
  out
- F3: MCP servers per agent VM and per (service, site, privilege),
  plus the rejected routed-meta-tools alternative
- F4: the existing image pipeline, with third-party MCP images
  digest-pinned and excluded from Watchtower

Consequences land where they belong: site identifiers in Part 0, a
machine account per MCP server instance in A7, B3 and C5 recast as
instances of F1/F2, plan approval required for every write in C2, MCP
as the primary infrastructure path in C3, the network-gear browser
item narrowed to fallback access, and stateful-server relocation
parked in Part H.

The standalone amendment is removed now that its content lives here,
as with the Tiered Inference amendment; it remains in the previous
commit.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

dongar reviewed

2026-09-23 01:59:54 +00:00

docs/Architecture-Build-Spec.md Outdated

						
				@@ -32,6 +35,11 @@ same string across all of those: the VM, the container, the Caddy host, the Matr

				account, and the Bitwarden machine account for a given agent all share one name, so

				that grepping the infrastructure for `nisse-ops` finds everything.

				**Sites** are identified by their domain stem: `garrett-hall` (Arlington) and

dongar commented

2026-09-23 01:59:54 +00:00

One note (and I think this was wrong in the original prompt), the domains for the two sites end in garrett-hall.com, and hartman-hut.com.

dongar marked this conversation as resolved

dev-agent reviewed

2026-09-23 02:00:37 +00:00

docs/Architecture-Build-Spec.md Outdated

						
				@@ -32,6 +35,11 @@ same string across all of those: the VM, the container, the Caddy host, the Matr

				account, and the Bitwarden machine account for a given agent all share one name, so

				that grepping the infrastructure for `nisse-ops` finds everything.

				**Sites** are identified by their domain stem: `garrett-hall` (Arlington, hosts under

dev-agent commented

2026-09-23 02:00:37 +00:00

Good catch. The identifiers themselves stay the same: garrett-hall and hartman-hut are the stems of garrett-hall.com and hartman-hut.com. But the text said "domain stem" without naming the domains, so a reader could not check which domain it meant. Each site now names its domain: "hosts under garrett-hall.com" and "hosts under hartman-hut.com".

Good catch. The identifiers themselves stay the same: `garrett-hall` and `hartman-hut` are the stems of `garrett-hall.com` and `hartman-hut.com`. But the text said "domain stem" without naming the domains, so a reader could not check which domain it meant. Each site now names its domain: "hosts under `garrett-hall.com`" and "hosts under `hartman-hut.com`".

dev-agent added 1 commit 2026-09-23 02:00:45 +00:00

Name the site domains the identifiers are stems of

CI / checks (push) Skipped

CI / checks (pull_request) Successful in 54s

Details

3dbfbc8cf0

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

dev-agent force-pushed mcp-deployment from c5d373f4dc to 3dbfbc8cf0

2026-09-23 02:00:45 +00:00

Compare

dongar approved these changes

2026-09-23 02:01:15 +00:00

dongar merged commit 889615e3e2 into main

2026-09-23 02:03:59 +00:00

dongar deleted branch mcp-deployment

2026-09-23 02:03:59 +00:00

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: dev/nisse#36