From e8a43c67152d1e7a7d569037415bfbe5771d85ef Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Torjus=20H=C3=A5kestad?= Date: Sat, 7 Feb 2026 02:29:13 +0100 Subject: [PATCH] docs: add deploy_admin tool with opt-in flag to homelab-deploy plan MCP exposes two tools: - deploy: test-tier only, always available - deploy_admin: all tiers, requires --enable-admin flag Three security layers: CLI flag, NATS authz, Claude Code permissions. Co-Authored-By: Claude Opus 4.5 --- docs/plans/nats-deploy-service.md | 31 ++++++++++++++++++++++++------- 1 file changed, 24 insertions(+), 7 deletions(-) diff --git a/docs/plans/nats-deploy-service.md b/docs/plans/nats-deploy-service.md index 7a5af0c..c811cb8 100644 --- a/docs/plans/nats-deploy-service.md +++ b/docs/plans/nats-deploy-service.md @@ -151,18 +151,35 @@ This provides immediate feedback on validation errors (bad revision, already run ### MCP Mode -Runs as an MCP server providing tools for Claude Code: -- `deploy` - Deploy to specific host, all hosts in tier, or all hosts with a role -- `deploy_status` - Check deployment status/history -- `list_hosts` - List available deployment targets +Runs as an MCP server providing tools for Claude Code. -The MCP server runs with limited credentials (test-tier only), so Claude can: +**Tools:** +| Tool | Description | Tier Access | +|------|-------------|-------------| +| `deploy` | Deploy to test hosts (individual, all, or by role) | test only | +| `deploy_admin` | Deploy to any host (requires `--enable-admin` flag) | test + prod | +| `deploy_status` | Check deployment status/history | n/a | +| `list_hosts` | List available deployment targets | n/a | + +**CLI flags:** +```bash +# Default: only test-tier deployments available +homelab-deploy mcp --nats-url nats://nats1:4222 + +# Enable admin tool (requires admin NKey to be configured) +homelab-deploy mcp --nats-url nats://nats1:4222 --enable-admin --admin-nkey-file /path/to/admin.nkey +``` + +**Security layers:** +1. **MCP flag**: `deploy_admin` tool only exposed when `--enable-admin` is passed +2. **NATS authz**: Even if tool is exposed, NATS rejects publishes without valid admin NKey +3. **Claude Code permissions**: Can set `mcp__homelab-deploy__deploy_admin` to `ask` mode for confirmation popup + +By default, the MCP only loads test-tier credentials and exposes the `deploy` tool. Claude can: - Deploy to individual test hosts - Deploy to all test hosts at once (`deploy.test.all`) - Deploy to test hosts by role (`deploy.test.role.`) -Production deployments require admin credentials. - ### Tiered Permissions Authorization is enforced at the NATS layer using subject-based permissions. Different deployer credentials have different publish rights: