English Français العربية

io.github.mdfifty50-boop/agent-guard

Official registry AI and agents

Constitutional guardrails and loop detection for AI agents

Source code Documentation

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

NPM package agent-guard-mcp
Claude Code 
claude mcp add agent-guard -- npx -y agent-guard-mcp@0.1.3
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "agent-guard": {
            "command": "npx",
            "args": [
                "-y",
                "agent-guard-mcp@0.1.3"
            ]
        }
    }
}

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. agent-guard-mcp
  2. Install
  3. Tools
  4. Resources
  5. Usage Pattern
  6. Tests
  7. License

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.

ParamTypeDefaultDescription
agent_idstringrequiredUnique agent identifier
max_iterationsnumber100Max iterations before forced stop
progress_thresholdnumber0.3Min 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.

ParamTypeDefaultDescription
agent_idstringrequiredAgent identifier
tool_namestringrequiredTool being called
argsobjectrequiredArguments passed
result_previewstring""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.

ParamTypeDescription
agent_idstringAgent to check

Returns:

  • is_stuck — boolean
  • confidence — 0.0 to 1.0
  • pattern — healthy, exact_repeat, low_diversity, or exact_repeat_and_low_diversity
  • suggestion — human-readable recovery advice
  • repeated_actions — list of repeated signatures with counts
set_circuit_breaker

Configure automatic intervention when action patterns repeat.

ParamTypeDefaultDescription
agent_idstringrequiredAgent identifier
max_repeatsnumber3Trigger after N identical actions
actionstring"warn""warn", "block", or "suggest_alternative"
check_circuit_breaker

Pre-flight check before executing a tool. Call this BEFORE the actual tool call.

ParamTypeDescription
agent_idstringAgent identifier
proposed_toolstringTool about to be called
proposed_argsobjectArguments 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.

ParamTypeDescription
agent_idstringAgent 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

URIDescription
agent-guard://agentsAll 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

Frequently asked questions

What is io.github.mdfifty50-boop/agent-guard?

Constitutional guardrails and loop detection for AI agents

How do I install io.github.mdfifty50-boop/agent-guard?

It runs on your machine. In Claude Code: claude mcp add agent-guard -- npx -y agent-guard-mcp@0.1.3. For other clients, paste the JSON configuration from this page into their MCP settings.

Does io.github.mdfifty50-boop/agent-guard need an API key?

Its registry entry lists no required key or secret. Some features may still need an account with the service it connects to.

Is io.github.mdfifty50-boop/agent-guard open source?

Its code is public on GitHub, but the repository does not declare a standard license.

Who maintains io.github.mdfifty50-boop/agent-guard?

It is published by mdfifty50-boop. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.