agent-guard-mcp
MCP server that detects and prevents infinite agent loops — the #1 reliability problem in agentic systems.
Provides circuit breakers, pattern detection, stuck-agent analysis, and recovery recommendations via the Model Context Protocol.
Install
npx agent-guard-mcp
Claude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"agent-guard": {
"command": "npx",
"args": ["agent-guard-mcp"]
}
}
}
From source
git clone https://github.com/mdfifty50-boop/agent-guard-mcp.git
cd agent-guard-mcp
npm install
node src/index.js
Tools
register_agent
Register an agent for monitoring.
| Param | Type | Default | Description |
|---|---|---|---|
agent_id | string | required | Unique agent identifier |
max_iterations | number | 100 | Max iterations before forced stop |
progress_threshold | number | 0.3 | Min unique/total action ratio to be "making progress" |
log_action
Log an agent action for loop detection. Maintains a rolling window of the last 50 actions.
| Param | Type | Default | Description |
|---|---|---|---|
agent_id | string | required | Agent identifier |
tool_name | string | required | Tool being called |
args | object | required | Arguments passed |
result_preview | string | "" | Brief result preview (max 200 chars) |
Returns early warnings when repeated patterns are detected.
detect_loop
Check if an agent is stuck in an infinite loop.
| Param | Type | Description |
|---|---|---|
agent_id | string | Agent to check |
Returns:
is_stuck— booleanconfidence— 0.0 to 1.0pattern—healthy,exact_repeat,low_diversity, orexact_repeat_and_low_diversitysuggestion— human-readable recovery advicerepeated_actions— list of repeated signatures with counts
set_circuit_breaker
Configure automatic intervention when action patterns repeat.
| Param | Type | Default | Description |
|---|---|---|---|
agent_id | string | required | Agent identifier |
max_repeats | number | 3 | Trigger after N identical actions |
action | string | "warn" | "warn", "block", or "suggest_alternative" |
check_circuit_breaker
Pre-flight check before executing a tool. Call this BEFORE the actual tool call.
| Param | Type | Description |
|---|---|---|
agent_id | string | Agent identifier |
proposed_tool | string | Tool about to be called |
proposed_args | object | Arguments about to be passed |
Returns proceed: false when the circuit breaker fires (block mode only).
get_stuck_report
Detailed analysis of why an agent is stuck.
| Param | Type | Description |
|---|---|---|
agent_id | string | Agent to analyze |
Returns: action history, pattern analysis, token waste estimate, diversity ratio, top repeated patterns, and recovery recommendations.
get_health_dashboard
Overview of all monitored agents. No parameters.
Returns all agents sorted by risk score with their status (STUCK/HEALTHY), action counts, and circuit breaker config.
Resources
| URI | Description |
|---|---|
agent-guard://agents | All monitored agents with current status |
Usage Pattern
1. register_agent — at agent startup
2. Before each tool call:
a. check_circuit_breaker — should this action proceed?
b. Execute the tool
c. log_action — record what happened
3. Periodically:
- detect_loop — am I stuck?
- get_health_dashboard — how are all agents doing?
4. On stuck detection:
- get_stuck_report — what went wrong and how to recover
Tests
npm test
License
MIT