mcp-host-agent

What this is

mcp-host-agent is a system CLI you install — not a Python project you write. The thing you build is a Worker (a small mcp-worker-sdk repo exposing /health /tools /execute /meta). This CLI just points at your Worker's Git repo and does the clone/install/run/supervise/heal for you.

So no “worker directory structure” lives here — that belongs to mcp-worker-sdk. See the full command reference in docs/mcp-host-agent/CLI_REFERENCE.md.

Why

Deploying MCP Workers by hand means writing the same git clone + pip install + systemctl restart + heartbeat + self-healing glue every time — multiplied by the number of Workers and hosts you manage. mcp-host-agent turns that glue into a single, declarative, docker-style CLI.

• One agent per host manages N Worker services.
• Coolify-like Git UX — private/public Git repos plus push-to-deploy webhooks.
• Rich three-tier health — status, queue backpressure, and latency/reliability profile flow up to the Hub for smarter scheduling.
• Self-healing — process-level restart, rollback to the previous commit, and structured escalation.

Install

pip install mcp-host-agent

Requires Python 3.10+.

Quick start

# 1. Generate a standard agent.yaml.
mcp-host-agent config init \
  --hub-url https://hub.example.com \
  --agent-id agent-sandbox

# 2. Add a worker (writes back to agent.yaml atomically).
mcp-host-agent worker add \
  --name demo-worker \
  --repo https://git.example.com/owner/demo-worker.git \
  --port 9101

# 3. Validate, then run (bootstrap first → supervision loop → control API).
mcp-host-agent config validate --config /etc/mavis/agent.yaml
mcp-host-agent deploy run --config /etc/mavis/agent.yaml

Verify:

curl http://127.0.0.1:9200/health
curl http://127.0.0.1:9200/meta
curl http://127.0.0.1:9200/api/v1/agent/status -H "X-Agent-Token: <agent-token>"

Full CLI reference (every flag, example command, example output, and a zero-to-running workflow): docs/mcp-host-agent/CLI_REFERENCE.md.

Features

Configuration

The agent is driven by a single agent.yaml:

hub_url: "https://hub.example.com"
agent_id: "agent-sandbox"
jwt_token: "<jwt>"               # register with the Hub
agent_token: "<agent-token>"     # protect control endpoints
webhook_secret: "<webhook-secret>"  # Gitea/GitHub webhook signature

platform: linux                  # linux | macos
agent_port: 9200                 # control API port

workers:
  - name: sandbox-worker
    repo: "https://git.example.com/owner/worker-sandbox.git"
    branch: main
    port: 9101
    git_username: "will"         # private repo username
    git_token_env: "GITEA_TOKEN" # token read from env, never written to YAML
    # self-healing defaults (overridable by Worker /meta.recovery)
    auto_restart: true
    max_restart: 3
    restart_interval: 5
    fail_threshold: 3
    graceful_timeout: 10

The token referenced by git_token_env is read from the environment at clone time and is not persisted to disk. If both git_username and git_token_env are omitted, the host's own Git credential helper (or SSH config) is used.

Set up push-to-deploy (Gitea / GitHub)

1. Point your webhook at the agent:

   • Payload URL: http://<host-agent-ip>:9200/webhook
   • Content type: application/json
   • Secret: the same value as webhook_secret in agent.yaml

2. Gitea — enable “Push” events.

3. GitHub — enable “Just the push event”.

Every push with a valid signature triggers git pull → pip install → service restart and reports commit status back.

Supported platforms

Windows is not supported in v1. The agent manages native host processes (systemd/launchd). Containers such as Docker/K3s pods are self-healed by their own orchestrators, not by the agent.

Programmatic API

from mcp_host_agent import (
    AgentConfig,
    WorkerConfig,
    WorkerManager,
    Supervisor,
    create_app,
    SystemdRunner,
)

config = AgentConfig(
    hub_url="https://hub.example.com",
    agent_id="agent-sandbox",
    jwt_token="<jwt>",
    workers=[WorkerConfig(name="demo", repo="https://git.example.com/o/demo.git", port=9101)],
)

manager = WorkerManager(config)
manager.ensure_cloned(config.workers[0])
manager.install_deps(config.workers[0])
manager.start(config.workers[0])

supervisor = Supervisor(config, manager)
supervisor.poll_all()
heartbeats = supervisor.build_heartbeats("2026-08-16T00:00:00+00:00")

app = create_app(config, supervisor, manager)  # FastAPI control plane

See docs/mcp-host-agent/DELIVERY_INTEGRATION.md for the full integration guide.

Development

pip install -e ".[dev]"
pytest            # unit + integration + contract + compatibility
ruff check .

License

Apache-2.0