mcp-host-agent

Host-level deployment and supervision agent for the MCP Worker platform.

Installed once per host, mcp-host-agent manages the local Worker services end to end: deployment (git clone/pull + dependency install), health polling, heartbeat aggregation to the Hub, crash self-healing, and the Hub-facing control endpoints.

Installation

pip install mcp-host-agent

Requires Python 3.10+.

Quick start

# 1. Write the agent configuration (see below).
# 2. Validate it and run the control API.
mcp-host-agent run --config /etc/mavis/agent.yaml

Configuration

The agent is driven by a single agent.yaml file:

hub_url: "https://hub.example.com"
agent_id: "agent-example"
jwt_token: "<jwt>"
agent_token: "<agent-token>"   # optional; required for control endpoints

platform: linux                # linux | macos
agent_port: 9200               # control API port (default 9200)

workers:
  - name: demo-worker
    repo: "https://git.example.com/owner/demo-worker.git"
    branch: main
    port: 9101
    python: "3.11"
    auto_restart: true
    max_restart: 3

How it works

• Deployment — clones/pulls each worker repo into the working directory and manages it as a systemd (Linux) or launchd (macOS) service.
• Supervision — polls each worker's process state and /health endpoint, derives its status, and aggregates everything into an AgentHeartbeat.
• Self-healing — applies a decision tree (restart → rollback → give up) and escalates unrecoverable failures to the Hub orchestrator.
• Control plane — exposes /health, /meta, and authenticated /api/v1/agent/* endpoints for the Hub orchestrator.

Supported platforms

Windows is not supported in v1. The agent does not self-heal containers (Docker/K3s pods are managed by their own orchestrators); it manages native host processes only.

Development

pip install -e ".[dev]"
pytest

License

Apache-2.0. See LICENSE.