{
  "markdown": "# @fidacy/mcp\n\n[![fidacy-mcp MCP server](https://glama.ai/mcp/servers/lucaslubi/fidacy-mcp/badges/score.svg)](https://glama.ai/mcp/servers/lucaslubi/fidacy-mcp)\n\n![Fidacy blocks a BEC lookalike-payee payment, then allows the legit one with a signed Ed25519 grant](assets/fidacy-firewall-demo.svg)\n\nThe action firewall for AI agents. A drop-in MCP server that gates payment\nactions against a cryptographically signed mandate **before** money can move.\nNon-custodial: Fidacy authorizes and proves, it never holds funds.\n\nInstall once, works in any MCP-compatible agent: Claude Code, Claude Desktop,\nHermes, OpenClaw, and anything else that speaks MCP.\n\n[![npm](https://img.shields.io/npm/v/@fidacy/mcp)](https://www.npmjs.com/package/@fidacy/mcp)\n[![license](https://img.shields.io/npm/l/@fidacy/mcp)](https://www.npmjs.com/package/@fidacy/mcp)\n**Works with:** Claude Code · Claude Desktop · OpenClaw · Hermes · Brex CrabTrap\n\n> **Your agent could be paying scammers right now.** Prompt-injected into the wrong\n> payee, an inflated amount, or the same invoice twice — and your logs aren't\n> evidence. Fidacy blocks it *before* money moves, and hands back a signed verdict\n> **anyone can verify** against public keys. You don't trust us — you check the signature.\n\n## Quick start (free, local-first, no account)\n\n```json\n{\n  \"mcpServers\": {\n    \"fidacy\": { \"command\": \"npx\", \"args\": [\"-y\", \"@fidacy/mcp\"] }\n  }\n}\n```\n\nRuns on your machine, offline, deny-by-default. Add trusted payees + caps in\n`~/.fidacy/config.json`. Verify any verdict yourself against the public keys at\n[`/.well-known/jwks.json`](https://api.fidacy.com/.well-known/jwks.json).\n\n## Why\n\nAn agent can hallucinate or be prompt-injected into a payment: wrong payee,\nwrong amount, fabricated invoice. Prompt-level guardrails are probabilistic and\nbypassable. `@fidacy/mcp` is a deterministic gate between the agent's intent and\nthe executor: the action is dead on arrival unless it validates against a signed\nmandate, and every decision lands in an immutable hash-chained audit trail.\n\n## Enforcement model\n\n1. Register `@fidacy/mcp` as the agent's **only** payment-capable tool. Do not\n   give the agent a raw payment tool. Tool inventory is the runtime firewall.\n2. The agent calls `request_payment`. Fidacy checks it against the mandate\n   (payee allowlist, per-tx cap, total cap, currency, time window, revocation).\n3. ALLOW returns a short-lived Ed25519 **grant**. DENY returns no grant and the\n   violated rule. The downstream executor MUST require the grant, so a denied\n   action cannot proceed.\n4. Every decision is appended to a hash-chained log. `get_audit_proof` returns\n   the portable, verifiable proof.\n\n## One install, two backends\n\n`@fidacy/mcp` ships two complementary capabilities in a single install:\n\n- **Verdict layer (advisory)**: `assess_action` calls the live Fidacy engine and\n  returns a **signed trust verdict**. It moves no money; it returns a judgment\n  whose proof (`riskPayloadJws` + `signingKeyId`) is verifiable by anyone via\n  `@fidacy/verify` against the engine JWKS at `/.well-known/jwks.json`.\n- **Payment firewall (enforcement)**: `request_payment` / `verify_mandate` /\n  `get_audit_proof` gate and prove a payment against a signed mandate through the\n  core, returning short-lived Ed25519 grants.\n\nMental model: `assess_action` -> **engine** (signed verdict);\n`request_payment` and friends -> **core** (payment firewall).\n\n## Tools\n\n| Tool | Backend | Purpose |\n|---|---|---|\n| `assess_action` | engine | Signed Fidacy trust verdict for a proposed action. Advisory. |\n| `request_payment` | core | Authorize a payment action. ALLOW + grant, or DENY + rule. |\n| `verify_mandate` | core | Read the mandate envelope + Fidacy public key. |\n| `get_audit_proof` | core | Hash-chained proof for a decision id. |\n\n### `assess_action`\n\nReturns a signed Fidacy trust verdict from the live engine for a proposed\naction. The signed proof is `riskPayloadJws` + `signingKeyId`, verifiable by\nanyone via `@fidacy/verify` against `{engineUrl}/.well-known/jwks.json`.\n\nInputs:\n\n- `kind` (optional, default `ap2_payment`): one of `ap2_payment`,\n  `message_send`, `voice_call`, `custom`, `claim_document`.\n- `mandate` (required): the action/mandate object for that `kind`.\n- `mandateType`, `spendingMandate`, `idempotencyKey`, `a2a.task_id` (optional).\n\nEnvironment:\n\n| Var | Default | Purpose |\n|---|---|---|\n| `FIDACY_ENGINE_URL` | `https://api.fidacy.com` | Base URL of the Fidacy engine. |\n| `FIDACY_ENGINE_API_KEY` | (none) | An `fky_live_` / `fky_test_` key with scope `assess:write`. |\n\nThe server boots without `FIDACY_ENGINE_API_KEY`; the tool is always registered.\nOnly **calling** `assess_action` without the key returns a helpful error telling\nyou to set it. The key is never logged, echoed, or attached to any error.\n\n## Install\n\n```bash\nnpm install -g @fidacy/mcp   # or run via npx, no install\n```\n\n### Claude Code\n\n```bash\nclaude mcp add fidacy -- npx -y @fidacy/mcp\n```\n\n### Claude Desktop (`claude_desktop_config.json`)\n\n```json\n{\n  \"mcpServers\": {\n    \"fidacy\": { \"command\": \"npx\", \"args\": [\"-y\", \"@fidacy/mcp\"] }\n  }\n}\n```\n\n### Hermes (`config.yaml`)\n\n```yaml\nmcp_servers:\n  fidacy:\n    command: npx\n    args: [\"-y\", \"@fidacy/mcp\"]\n```\n\n### OpenClaw\n\nAdd the same server via the Tools panel, or the `mcpServers` block in your\nagent config. Any MCP-compatible host uses the same command.\n\n## Wiring the real core (production)\n\nThe MCP layer talks to your core through one interface (`FidacyCore`). Your\nrepository stays private. Set `FIDACY_MODE=http` and implement three endpoints:\n\n- `POST /v1/mandate/get` -> `Mandate`\n- `POST /v1/decide` -> `Decision` (runs your Ed25519/AP2 verification + audit append)\n- `POST /v1/audit/proof` -> `AuditProof`\n\nNo change to the MCP layer is needed.\n\n## Dev\n\n```bash\nnpm install\nnpm run build\nnpm start      # stdio server, in-memory demo mandate\n```\n",
  "bytes": 5892,
  "sha": "47028053305fa2c9bbf1e4bd502566c14ef9485b06a7c8d3390edb257de6b423",
  "repo_slug": "lucaslubi/fidacy-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_fidacy_ai_agent_firewall_caa84116/readme"
}