Dead Letter Oracle: An MCP Server That Governs AI Decisions for Production

What It Does — A Governed AI Agent for DLQ Incidents

Dead Letter Oracle is an open-source MCP server that solves a specific, painful production problem: deciding whether to replay a failed message from a dead-letter queue (DLQ). It doesn't just diagnose; it implements a governed decision loop.

The core workflow:

1. Read & Validate: Uses dlq_read_message and schema_validate tools to parse the failed event.
2. Propose & Simulate: The LLM (like Claude) proposes a fix. A deterministic replay_simulate tool scores its confidence.
3. Revise & Govern: If confidence is low, the LLM revises. A Gatekeeper then issues a final ALLOW, WARN, or BLOCK decision based on confidence score, environment (prod vs. staging), and fix specificity.

The key insight is the deliberate first failure. The system is designed so the initial LLM fix is plausible but operationally weak (e.g., "align producer schema"). The simulation catches this, forcing a concrete revision (e.g., user_id="12345"). This mimics real human debugging and prevents naive pattern-matching.

Setup — How to Run It with Claude Code

You can integrate this directly as an MCP server with Claude Code to handle real or simulated DLQ incidents.

# Clone and setup
git clone https://github.com/tvprasad/dead-letter-oracle
cd dead-letter-oracle
pip install -r requirements.txt
cp .env.example .env
# Add your ANTHROPIC_API_KEY to .env

# Run the MCP server directly (for Claude Desktop/Code)
python -m mcp_server.cli

To connect it to Claude Code, you would configure it in your Claude Desktop settings (claude_desktop_config.json) as a local stdio server, giving Claude access to its four tools.

Quick Test via AgentGateway: For the fastest trial, use the included HTTP gateway:

# Install AgentGateway (if needed)
pip install agentgateway
# Run the gateway with the project config
agentgateway -f agentgateway/config.yaml

Then open http://localhost:15000/ui, connect to http://localhost:3000/, and invoke the agent_run_incident tool with {"file_path": "data/sample_dlq.json"}. You'll see the full governed pipeline execute from your browser.

When To Use It — Beyond the Demo

This MCP server is a template for building production-grade AI agents with Claude Code. Here’s how to apply its patterns:

1. For Real DLQ Management: Connect it to your actual messaging system (Kafka, SQS). The tools are contracts; swap dlq_read_message to read from your cloud queue.
2. As a Governance Blueprint: The Gatekeeper pattern is reusable. Any Claude Code agent making operational decisions (database migrations, deployment approvals) should have a similar multi-factor evaluation layer, not just an LLM's "yes/no."
3. For Audit Trails: Every run produces a structured 7-step trace (e.g., [3] PROPOSE FIX ... [7] GOVERN). Bake this into your own agents' outputs for compliance and debugging.
4. Leverage the Protocol Boundary: Because it's built on MCP, the replay_simulate confidence scorer or schema_validate tools can be used independently by other Claude Code projects or any MCP client.

The author emphasizes that "a system that always succeeds on the first try is not reasoning. It is pattern-matching." Use this project to learn how to build Claude Code agents that reason, revise, and are restrained by governance.