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 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.

Built on

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

The recommended path is a dedicated virtualenv (Debian/Ubuntu system Python is PEP 668 “externally managed” and won't allow pip install):

sudo apt-get update && sudo apt-get install -y python3-venv python3-full
python3 -m venv /opt/mavis-venv
/opt/mavis-venv/bin/pip install --upgrade mcp-host-agent
ln -sf /opt/mavis-venv/bin/mcp-host-agent /usr/local/bin/mcp-host-agent
mcp-host-agent --version

Requires Python 3.10+. The agent's own service unit is generated with {sys.executable} -m mcp_host_agent.cli ..., so it works from a venv, pipx, or system Python without a PATH symlink.

Quick start

# 1. Generate the config (--config defaults to /etc/mavis/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. Install as a system service: auto start-on-boot + crash-restart.
sudo mcp-host-agent deploy install-service

# 4. That's it — the agent is now running as a daemon.

Verify:

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

deploy install-service is the recommended production path (same philosophy as docker/tailscale: install → auto-enabled → boot + crash resilient). If you just want to run it in the foreground for a test, use mcp-host-agent deploy run.

Adding more Workers

# Add a second worker, then hot-reload (no restart).
mcp-host-agent worker add --name neo4j-worker --repo https://git.example.com/owner/worker-neo4j.git --port 9102
mcp-host-agent deploy reload

--config defaults to /etc/mavis/agent.yaml, so deploy run / reload / status / worker ls can all be invoked without repeating the path.

Features

Configuration

The agent is driven by a single agent.yaml (default /etc/mavis/agent.yaml):

hub_url: "https://hub.example.com"
agent_id: "agent-sandbox"
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

  - name: neo4j-worker
    repo: "https://git.example.com/owner/worker-neo4j.git"
    port: 9102

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.

What the agent does vs. does not do

mcp-host-agent deploys, supervises, and reports heartbeat only. It does not register Worker tools with the Hub — tool registration is the Hub/mcpstore's job. Each Worker's port in agent.yaml is the single source of truth: the agent passes it to the Worker as the MCP_WORKER_PORT environment variable so there's no drift between two places. (This requires mcp-worker-sdk to honour MCP_WORKER_PORT; without it, the Worker falls back to its own run(port=...).)

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,
)

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 the full integration guide at docs/mcp-host-agent/DELIVERY_INTEGRATION.md and the CLI reference at docs/mcp-host-agent/CLI_REFERENCE.md.

Development

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

License

Apache-2.0