io.github.lucaslubi/fidacy-mcp

@fidacy/mcp

The action firewall for AI agents. A drop-in MCP server that gates payment actions against a cryptographically signed mandate before money can move. Non-custodial: Fidacy authorizes and proves, it never holds funds.

Install once, works in any MCP-compatible agent: Claude Code, Claude Desktop, Hermes, OpenClaw, and anything else that speaks MCP.

Works with: Claude Code · Claude Desktop · OpenClaw · Hermes · Brex CrabTrap

Your agent could be paying scammers right now. Prompt-injected into the wrong payee, an inflated amount, or the same invoice twice — and your logs aren't evidence. Fidacy blocks it before money moves, and hands back a signed verdict anyone can verify against public keys. You don't trust us — you check the signature.

Quick start (free, local-first, no account)

{
  "mcpServers": {
    "fidacy": { "command": "npx", "args": ["-y", "@fidacy/mcp"] }
  }
}

Runs on your machine, offline, deny-by-default. Add trusted payees + caps in ~/.fidacy/config.json. Verify any verdict yourself against the public keys at /.well-known/jwks.json.

Why

An agent can hallucinate or be prompt-injected into a payment: wrong payee, wrong amount, fabricated invoice. Prompt-level guardrails are probabilistic and bypassable. @fidacy/mcp is a deterministic gate between the agent's intent and the executor: the action is dead on arrival unless it validates against a signed mandate, and every decision lands in an immutable hash-chained audit trail.

Enforcement model

1. Register @fidacy/mcp as the agent's only payment-capable tool. Do not give the agent a raw payment tool. Tool inventory is the runtime firewall.
2. The agent calls request_payment. Fidacy checks it against the mandate (payee allowlist, per-tx cap, total cap, currency, time window, revocation).
3. ALLOW returns a short-lived Ed25519 grant. DENY returns no grant and the violated rule. The downstream executor MUST require the grant, so a denied action cannot proceed.
4. Every decision is appended to a hash-chained log. get_audit_proof returns the portable, verifiable proof.

One install, two backends

@fidacy/mcp ships two complementary capabilities in a single install:

• Verdict layer (advisory): assess_action calls the live Fidacy engine and returns a signed trust verdict. It moves no money; it returns a judgment whose proof (riskPayloadJws + signingKeyId) is verifiable by anyone via @fidacy/verify against the engine JWKS at /.well-known/jwks.json.
• Payment firewall (enforcement): request_payment / verify_mandate / get_audit_proof gate and prove a payment against a signed mandate through the core, returning short-lived Ed25519 grants.

Mental model: assess_action -> engine (signed verdict); request_payment and friends -> core (payment firewall).

Tools

assess_action

Returns a signed Fidacy trust verdict from the live engine for a proposed action. The signed proof is riskPayloadJws + signingKeyId, verifiable by anyone via @fidacy/verify against {engineUrl}/.well-known/jwks.json.

Inputs:

• kind (optional, default ap2_payment): one of ap2_payment, message_send, voice_call, custom, claim_document.
• mandate (required): the action/mandate object for that kind.
• mandateType, spendingMandate, idempotencyKey, a2a.task_id (optional).

Environment:

The server boots without FIDACY_ENGINE_API_KEY; the tool is always registered. Only calling assess_action without the key returns a helpful error telling you to set it. The key is never logged, echoed, or attached to any error.

Install

npm install -g @fidacy/mcp   # or run via npx, no install

Claude Code

claude mcp add fidacy -- npx -y @fidacy/mcp

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "fidacy": { "command": "npx", "args": ["-y", "@fidacy/mcp"] }
  }
}

Hermes (config.yaml)

mcp_servers:
  fidacy:
    command: npx
    args: ["-y", "@fidacy/mcp"]

OpenClaw

Add the same server via the Tools panel, or the mcpServers block in your agent config. Any MCP-compatible host uses the same command.

Wiring the real core (production)

The MCP layer talks to your core through one interface (FidacyCore). Your repository stays private. Set FIDACY_MODE=http and implement three endpoints:

• POST /v1/mandate/get -> Mandate
• POST /v1/decide -> Decision (runs your Ed25519/AP2 verification + audit append)
• POST /v1/audit/proof -> AuditProof

No change to the MCP layer is needed.

Dev

npm install
npm run build
npm start      # stdio server, in-memory demo mandate