FailMemory MCP Server

FailMemory is a shared cache of API failures for AI agents. Before making an external call, an agent can check whether the same call pattern is already known to fail. After a call fails, the agent can report it so other agents can avoid repeating it.

This MCP server exposes two tools:

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

Get started

1. Get a free API key at https://failmemory.dev/signup. The key is shown once, so save it when it appears.
2. Add the server and key to your MCP host configuration.
3. Restart the host so it loads the new server.

During FailMemory's current Seeding stage, authenticated lookups and reports are free and unlimited. No payment method, credit balance, or deposit is required.

Claude Desktop, Cursor, or Cline

Use the following server entry in your host's MCP configuration. For Claude Desktop this is claude_desktop_config.json; for Cursor it is ~/.cursor/mcp.json or .cursor/mcp.json; for Cline, use cline_mcp_settings.json.

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

npx downloads and runs the package, so a separate global installation is not required.

Available tools

fail_memory_lookup

Call this before an external API request, scraping request, or other network call. A response with hit: true means FailMemory has a matching failure pattern; hit: false means no matching pattern is known.

Authentication is required. Pass api_key in the tool call or, preferably, set FAIL_MEMORY_API_KEY once in the MCP server configuration. Requests without a key return 401.

| Name | Type | Required | Description | | --- | --- | --- | --- | | method | string | yes | HTTP method, such as GET or POST | | url | string | yes | Full URL of the intended API call | | payload | JSON value | no | Request body used locally to derive a value-free structural fingerprint; values are never sent to FailMemory | | api_key | string | no | FailMemory API key; falls back to FAIL_MEMORY_API_KEY |

Example request:

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

Example hit:

{
  "hit": true,
  "hash": "c2a9...",
  "confidence": 1,
  "top_failure_modes": ["429", "503"],
  "fail_count": 3,
  "last_seen": "2026-09-01T18:22:11.000Z",
  "ttl_remaining_seconds": 81234,
  "match_scope": "endpoint",
  "provenance": "organic"
}

Use provenance to weigh a hit:

| Value | Meaning | Suggested treatment | | --- | --- | --- | | organic | Three or more independent signers reported the failure. | Strong signal; skipping the call is usually appropriate. | | seeded | A first-party probe observed the failure. | Treat as a warning, especially if your authentication or request shape differs from a plain probe. |

fail_memory_report

Call this after an external API call returns a 4xx or 5xx response, times out, encounters a network error, or otherwise fails.

Authentication is required. Each API key contributes at most one signer toward the three-signer promotion threshold for a pattern. Repeated reports from the same signer do not inflate that count.

MCP reports count toward promotion. The current contributor-credit mechanism is dormant during Seeding.

| 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 | Returned HTTP status; omit if no response arrived | | error_message | string | no | Short error description, such as rate limited or ECONNRESET | | payload | JSON value | no | Failed request body used locally to derive the same value-free structural fingerprint as lookup; values are never sent | | api_key | string | no | FailMemory API key; falls back to FAIL_MEMORY_API_KEY |

Example request:

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

For a request with a JSON body, pass its structure through payload on both tools. The MCP server reduces it to field names and JSON types, hashes that descriptor locally, and sends only the digest. Equal shapes match even when their values differ.

Example response:

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

Environment variables

| Variable | Default | Description | | --- | --- | --- | | FAIL_MEMORY_API_URL | https://failmemory.dev | FailMemory API base URL; override only for a self-hosted instance | | FAIL_MEMORY_API_KEY | unset | Default key used by both tools when a call does not pass api_key |

Current access model

FailMemory is in its Seeding stage. All currently available MCP functionality is free and unlimited while the failure corpus is being established. Paid checkout and prepaid credits are not part of the live MCP onboarding flow.

Links

• Sign up: https://failmemory.dev/signup
• Website: https://failmemory.dev
• Documentation: https://failmemory.dev/docs