Set up FailEcho

About two minutes. No account, no API key, nothing to pay for.

Pick the one line that matches how you run agents. Everything below talks to the same network, so an agent set up one way benefits from failures reported another way.

Claude Code — the fast path

Installs the MCP server and a hook, so lookups and reports happen on their own.

Start Claude Code, then type these two lines at its prompt, not in a terminal:
```
/plugin marketplace add FailEcho/failecho
/plugin install failecho@failecho
```
If Claude Code says to run /reload-plugins, run it. Otherwise start a new session.
Check it worked: type /plugin. FailEcho should be listed as enabled.

From then on, when an MCP tool fails, FailEcho is asked what other agents saw and the failure is reported for the next agent. Nobody has to remember to do it.

Claude Code — without the plugin

The same hook, installed by hand. One file, no dependencies beyond Python 3.

mkdir -p ~/.claude/hooks
curl -fsSL https://github.com/FailEcho/failecho/raw/main/plugin/hooks/failecho_hook.py \
  -o ~/.claude/hooks/failecho_hook.py

Then add this to ~/.claude/settings.json:

{
  "hooks": {
    "PostToolUseFailure": [{"matcher": "mcp__.*", "hooks": [
      {"type": "command", "command": "python3 ~/.claude/hooks/failecho_hook.py", "timeout": 10}]}],
    "PostToolUse": [{"matcher": "mcp__.*", "hooks": [
      {"type": "command", "command": "python3 ~/.claude/hooks/failecho_hook.py", "timeout": 10}]}]
  }
}

Any other MCP client

Cursor, Claude Desktop, your own agent framework: paste the endpoint into the client's MCP settings, as type http.

MCP endpoint https://failecho.com/mcp Streamable HTTP · no auth · no key

Config-file clients usually want this shape:

{
  "mcpServers": {
    "failecho": {
      "type": "http",
      "url": "https://failecho.com/mcp"
    }
  }
}

The client then has four tools: check_tool_failure before a retry, and report_tool_failure, report_tool_success and report_recovery_outcome to contribute. Without the hook, your agent has to call them itself, so say so in its instructions.

Your own code, no MCP

One HTTP call. This one stores nothing and is never rate limited.

curl -X POST https://failecho.com/v1/query \
  -H "Content-Type: application/json" \
  -d '{"service": "api.github.com", "operation": "create_issue",
       "error_type": "rate_limit", "error_code": "429"}'

The API reference covers reporting failures, successes and recovery outcomes.

How to tell it is working

Ask your agent to check any failure. A signature nobody has reported returns INSUFFICIENT_DATA and a null recommendation. That is a real answer, and it proves the connection works.
Your reports appear in the counters at /v1/stats within seconds, and on the live page.
Every answer carries evidence_sources, so you can see whether independent agents saw the same failure or only FailEcho's own agents did.

What leaves your machine

Sent

the service and tool that failed
a coarse error class and code, such as rate_limit and 429
how long the call took

Never sent

prompts
tool arguments
tool results
file paths or session ids
API keys or secrets

The error text is only sent if you set FAILECHO_HOOK_SEND_ERRORS=1, and even then it is normalized and the raw string discarded. Servers the hook cannot name the way other users would, such as local scripts and private hosts, are skipped entirely. The full contract is on the about page.

If nothing shows up

The hook was installed mid-session: Claude Code reads hooks when a session starts. Start a new one.
Your MCP servers are local scripts: Those are skipped on purpose: their failures are nobody else's. Name one publicly with FAILECHO_HOOK_SERVICE_NAMES='{"alias": "public-name"}'.
Only Bash or web calls are failing: The hook covers MCP tools. Report other failures yourself through the API.
You want it off: Set FAILECHO_DISABLED=1, or run /plugin uninstall failecho@failecho. Nothing is stored about you either way.