Agent Chain Doctor MCP

What agent-chain-doctor-mcp does

The agent-chain-doctor-mcp MCP server exposes the diagnosis logic from the repository’s shell-based agent-chain doctor to an AI assistant. It examines the files and traces left by a scheduled agent chain, including the scheduler configuration and the session script it launches. The supported scheduler environments are cron, launchd, and systemd, with additional checks relevant to unattended Claude runs.

The result covers 30 known silent-stop conditions. Each check returns one of three states: exposed, guarded, or undecidable. Evidence is included so an operator or assistant can see why a result received its status. The checks target problems such as stale locks, missing executables in a scheduler-provided PATH, empty triggers, ineffective signal cleanup, and work windows missed while a machine was asleep.

This belongs in the Monitoring category, but it is a diagnostic tool rather than a liveness or heartbeat monitor. It cannot establish that an agent ran successfully or produced useful work.

How it works

The MCP entry point is mcp/server.py. It implements the diagnose_scheduled_agent tool using only Python’s standard library and communicates through stdio. An MCP client starts the server with Python and passes the path to the server file. The process reads local state without modifying it, contacting external services, or requiring administrator access.

Run the server on the machine that contains the chain being investigated. A containerized process can inspect only the files and scheduler state visible inside that container. An assistant can therefore ask why a scheduled agent skipped a run, then invoke the diagnostic tool against the local environment.

The agent-chain-doctor-mcp MCP server complements heartbeat products rather than replacing them. A heartbeat can show whether a run occurred; these checks investigate local causes when the scheduler did not start the job or left an unexpected trace.

Setup and configuration

Clone the repository and register the stdio server with an MCP client:

git clone https://github.com/elfovo/agent-chain-doctor
claude mcp add agent-chain-doctor -- python3 "$PWD/agent-chain-doctor/mcp/server.py"

The command requires Python 3 and the repository path. No package manager installation or environment variables are documented as necessary. The repository also provides an .mcpb bundle for Claude Desktop in the v1.0.0-mcp release. It can be downloaded and opened directly, or built locally with python3 mcp/build_mcpb.py.

Any MCP client that can launch a stdio server can use the same command pattern. Test scripts in the repository include mcp/test_server.sh and bundle-related checks.

Tools and capabilities

The agent-chain-doctor-mcp MCP server provides one MCP tool:

• diagnose_scheduled_agent — runs the 30 read-only checks and returns classifications with the evidence behind them.

The checks can help investigate scheduler startup, trigger files, locks, signal handling, executable paths, machine sleep, authentication failures, permissions and auto-mode behavior, prompts that block unattended work, hung runs, usage limits, missing MCP tools, and root-related restrictions. These are diagnosis areas supported by the repository’s documented checks; the server does not perform repairs.

Limitations and notes

A clean result means that the checks did not find an exposed condition. It does not prove that the chain is healthy, and the project does not provide a known false-negative rate. The server cannot determine whether an agent is doing good work.

The tool is intended for locally observable chains. Hosted schedules such as Claude Code Routines, Desktop scheduled tasks, or an agent gateway’s internal cron may not leave state that this process can read. The repository describes a separate missed-run check for some hosted scheduling cases, but that is not the MCP tool described here.

The agent-chain-doctor-mcp MCP server is read-only: it performs no writes, network requests, or privileged operations. Running it in a container limits its view to the container. It also does not replace a heartbeat monitor, watchdog, or remediation workflow.