FailMemory MCP Server — pre-flight failure cache for AI agents

FailMemory is a shared negative-result cache for AI agents. Before making a potentially expensive or fragile external API call, agents can check whether that exact call pattern is already known to fail. The MCP server exposes this cache as two tools that plug into any MCP-compatible agent runtime:

• fail_memory_lookup — check a pattern before calling
• fail_memory_report — contribute a pattern after a call fails

New in v1.1.0: fail_memory_report lets your agent contribute to the shared corpus. Authenticated reports (via a FailMemory API key) count toward the 3-signer promotion threshold and earn contributor reputation. Anonymous reports are also accepted — they are recorded but do not count toward promotion. See D-066 in the FailMemory brief for the full identity model.

Installation

Install and run via npx — no local install required:

npx -y fail-memory-mcp

The canonical API endpoint (https://failmemory.dev) is baked in as the default, so no environment variables are required for normal use.

Claude Desktop

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "fail-memory": {
      "command": "npx",
      "args": ["-y", "fail-memory-mcp"]
    }
  }
}

Cursor

Add the following to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project-level):

{
  "mcpServers": {
    "fail-memory": {
      "command": "npx",
      "args": ["-y", "fail-memory-mcp"]
    }
  }
}

Cline

Add the following to your Cline MCP settings file (cline_mcp_settings.json — see the Cline extension docs for the exact path on your OS):

{
  "mcpServers": {
    "fail-memory": {
      "command": "npx",
      "args": ["-y", "fail-memory-mcp"]
    }
  }
}

Available Tools

fail_memory_lookup

Check if an API call is known to fail before making it. Call this BEFORE any paid API request, web scraping call, or external service call to see whether the target pattern is already known to fail. Returns hit: true with failure details if the pattern is cached, or hit: false if unknown. Use the confidence and top_failure_modes fields to decide whether to skip the call.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | method | string | yes | HTTP method (GET, POST, etc.) | | url | string | yes | Full URL of the API call | | payload_hash | string | no | Optional sha256 hash of the request payload |

Example request:

{
  "method": "GET",
  "url": "https://api.example.com/v1/widgets/42",
  "payload_hash": "c2a9..."
}

Example response (hit):

{
  "hit": true,
  "confidence": 0.94,
  "top_failure_modes": [
    { "status_code": 429, "count": 17 },
    { "status_code": 503, "count": 4 }
  ],
  "last_seen": "2026-04-09T18:22:11Z"
}

Example response (miss):

{
  "hit": false
}

fail_memory_report

Report an API call that just failed so future agents can skip it. Call this AFTER any external API call that returned an error (4xx, 5xx, timeout, network error, or any exception that prevented a successful response).

The report is hashed into a canonical pattern and, once three independent contributors have reported the same pattern, it becomes visible to every agent querying fail_memory_lookup. Duplicate reports from the same signer collapse to one and extend the TTL of already-promoted patterns rather than double-count, so it is safe to call on every failed call.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | method | string | yes | HTTP method of the failed call | | url | string | yes | Full URL of the failed call | | status_code | number | no | HTTP status code returned (omit if no response was received) | | error_message | string | no | Short human-readable error description | | api_key | string | no | FailMemory api key (fm_live_...). When present the report is authenticated and counts toward the 3-signer promotion threshold. Falls back to FAIL_MEMORY_API_KEY env var. Omit entirely for an anonymous report. |

Example — authenticated report:

{
  "method": "GET",
  "url": "https://api.example.com/v1/widgets/42",
  "status_code": 429,
  "error_message": "rate limited",
  "api_key": "fm_live_abc123..."
}

Example response:

{
  "accepted": true,
  "hash": "c2a9...",
  "credits_earned": 0,
  "authenticated": true
}

credits_earned is non-zero only on the call that trips the 3-signer promotion threshold (see D-028 in the brief). Anonymous reports always return credits_earned: 0 and authenticated: false.

Supplying the API key

Instead of passing api_key on every call, set it once via environment variable and let the tool default to it:

{
  "mcpServers": {
    "fail-memory": {
      "command": "npx",
      "args": ["-y", "fail-memory-mcp"],
      "env": {
        "FAIL_MEMORY_API_KEY": "fm_live_..."
      }
    }
  }
}

API keys are issued automatically when you start a FailMemory subscription. Keys can be rotated and revoked at any time — revocation is effective on the next request.

Credits

FailMemory uses a prepaid credit model for lookups. Credits are managed via the HTTP API, not via this MCP package — there is no wallet or key material handled locally.

To deposit credits, see the deposit flow documentation at https://failmemory.dev/docs/credits.

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | FAIL_MEMORY_API_URL | https://failmemory.dev | Base URL of the FailMemory API. Override only if you're running a self-hosted instance. | | FAIL_MEMORY_API_KEY | (unset) | Default api key used by fail_memory_report when the tool call does not supply one explicitly. |

Links

• Website: https://failmemory.dev
• Docs: https://failmemory.dev/docs