Runvouch

What runvouch MCP server does

The runvouch MCP server gives an MCP-compatible agent access to RunVouch’s operational monitoring for unattended AI-agent work. It is intended for scheduled, headless, or otherwise unattended processes where a successful scheduler exit does not prove that the task completed correctly.

RunVouch can record run lifecycle events, report health information, and expose alerts for conditions such as missed runs, non-zero failures, missing evidence, stalled execution, retry storms, budget violations, and behavioral drift. Cost and token caps can pause an agent and refuse its next run until an operator resumes it.

The runvouch MCP server is useful alongside Claude Code routines, headless claude -p jobs, OpenClaw, n8n, cron, or other automation that can report run activity. The repository also provides a CLI, HTTP ping URLs, a Claude Code plugin, and a hosted or self-hosted service, but the MCP integration focuses on exposing RunVouch operations to an MCP client.

How it works

The MCP implementation is located at integrations/mcp/runvouch_mcp.py and communicates over stdio. It uses RunVouch credentials and the configured RunVouch service URL to access account and run data. A client starts the MCP process, then invokes the available tools rather than calling the HTTP API directly.

The run lifecycle can be opened and closed through MCP operations. A run can also be inspected after execution, while status and alert operations provide a view of current agent health. Alerts may be acknowledged through the integration. Separately, RunVouch creates a SHA-256 record for each finished run and chains daily Merkle roots, with public proof files and a verification command available outside the MCP tool list.

Setup and configuration

Install the project or its client dependencies according to the repository instructions, then register the stdio server with the MCP client. The documented Claude Code command is:

claude mcp add runvouch -e RUNVOUCH_KEY=... -- python3 integrations/mcp/runvouch_mcp.py

Set RUNVOUCH_KEY to the RunVouch API key. Set RUNVOUCH_URL when using a non-default service endpoint, such as a self-hosted instance. Self-hosting runs the application with Docker or a virtual environment and stores data in SQLite. The repository’s self-hosting guide explains the setup and differences from the hosted service.

Tools and capabilities

The runvouch MCP server exposes these operations:

• runvouch_status for current monitoring status.
• runvouch_alerts for retrieving detected alerts.
• runvouch_ack for acknowledging alerts.
• runvouch_runs for inspecting runs.
• runvouch_run_start for opening a run.
• runvouch_run_end for closing a run.

These capabilities support operational checks but do not replace the agent’s task execution system. Evidence requirements, cadence, budgets, and alert destinations are configured in RunVouch, including through the rv agent CLI and service configuration.

Limitations and notes

The integration requires an MCP client that can launch a stdio server and a valid RunVouch configuration. The README documents the server command and environment variables but does not describe client-specific behavior beyond Claude Code registration.

MCP access depends on the RunVouch service being reachable. A self-hosted deployment is available from the same repository, while the hosted service supplies the managed endpoint, dashboard, alerts, and backups. The repository is MIT licensed.