Kyle Isom
84c487e7f8
The agent connects to mc-proxy via Unix socket and automatically registers/removes routes during deploy and stop. This eliminates manual mcproxyctl usage or TOML editing. - New ProxyRouter abstraction wraps mc-proxy client library - Deploy: after container starts, registers routes with mc-proxy using host ports from the registry - Stop: removes routes from mc-proxy before stopping container - Config: [mcproxy] section with socket path and cert_dir - Nil-safe: if mc-proxy socket not configured, route registration is silently skipped (backward compatible) - L7 routes use certs from convention path (<cert_dir>/<service>.pem) - L4 routes use TLS passthrough (backend_tls=true) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
MCP — Metacircular Control Plane
MCP is the orchestrator for the Metacircular platform. It manages container lifecycle, tracks what services run where, and transfers files between the operator's workstation and managed nodes.
Architecture
CLI (mcp) — thin client on the operator's workstation. Reads local
service definition files, pushes intent to agents, queries status.
Agent (mcp-agent) — per-node daemon. Manages containers via rootless
podman, stores a SQLite registry of desired/observed state, monitors for
drift, and alerts the operator.
Quick Start
Build
make all # vet, lint, test, build
make mcp # CLI only
make mcp-agent # agent only
Install the CLI
cp mcp ~/.local/bin/
mkdir -p ~/.config/mcp/services
Create ~/.config/mcp/mcp.toml:
[services]
dir = "/home/<user>/.config/mcp/services"
[mcias]
server_url = "https://mcias.metacircular.net:8443"
service_name = "mcp"
[auth]
token_path = "/home/<user>/.config/mcp/token"
[[nodes]]
name = "rift"
address = "100.95.252.120:9444"
Authenticate
mcp login
Check status
mcp status # full picture: services, drift, events
mcp ps # live container check with uptime
mcp list # quick registry query
Deploy a service
Write a service definition in ~/.config/mcp/services/<name>.toml:
name = "myservice"
node = "rift"
active = true
[[components]]
name = "api"
image = "mcr.svc.mcp.metacircular.net:8443/myservice:v1.0.0"
network = "mcpnet"
user = "0:0"
restart = "unless-stopped"
ports = ["127.0.0.1:8443:8443"]
volumes = ["/srv/myservice:/srv/myservice"]
cmd = ["server", "--config", "/srv/myservice/myservice.toml"]
Then deploy:
mcp deploy myservice
Commands
| Command | Description |
|---|---|
mcp login |
Authenticate to MCIAS |
mcp deploy <service>[/<component>] |
Deploy from service definition |
mcp stop <service> |
Stop all components |
mcp start <service> |
Start all components |
mcp restart <service> |
Restart all components |
mcp list |
List services (registry) |
mcp ps |
Live container check |
mcp status [service] |
Full status with drift and events |
mcp sync |
Push all service definitions |
mcp adopt <service> |
Adopt running containers |
mcp service show <service> |
Print spec from agent |
mcp service edit <service> |
Edit definition in $EDITOR |
mcp service export <service> |
Export agent spec to file |
mcp push <file> <service> [path] |
Push file to node |
mcp pull <service> <path> [file] |
Pull file from node |
mcp node list |
List nodes |
mcp node add <name> <addr> |
Add a node |
mcp node remove <name> |
Remove a node |
Documentation
- ARCHITECTURE.md — design specification
- RUNBOOK.md — operational procedures
- PROJECT_PLAN_V1.md — implementation plan
- PROGRESS_V1.md — progress and remaining work