@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.

To everyone who installed Fidacy

You are one of 431 installs. Between them the firewall has taken 3,099 decisions, 98% of them blocks, counted by the engine and public at api.fidacy.com/v1/pulse if you want to check the number yourself. Thank you for being part of it. Two things worth a minute of your time:

• See and claim what YOUR install blocked. Your install carries a private, anonymous id on your machine (we never learn who you are unless you choose to). Run:

  grep anon_id ~/.fidacy/config.json
  

  then open https://fidacy.com/claim?ref=<that id>. One click turns your local history into a free account: server-signed verdicts, Bitcoin-anchored audit, nothing about your machine leaves it.

• Founding partner, 5 seats. A full year of the evidence layer at $10,800 instead of $18,000, wired into your stack by the founder, 30-day full refund: fidacy.com/partners

Lucas de Lima, founder

Quick start (2 minutes, free)

Step 1 — get your free API key at app.fidacy.com/signup (free tier, no card). The key unlocks server-signed verdicts, Bitcoin-anchored proofs, and keeps the firewall active past the anonymous trial.

Step 2 — install:

{
  "mcpServers": {
    "fidacy": {
      "command": "npx",
      "args": ["-y", "@fidacy/mcp"],
      "env": { "FIDACY_ENGINE_API_KEY": "<your fky_ key>" }
    }
  }
}

Decisions run 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.

No key yet? The install works anonymously for its first 20 firewall decisions, then fails closed (payments are denied with activation_required) until you set the free key. Already ran it anonymously? Claim your install's block history into the account: grep anon_id ~/.fidacy/config.json, then open https://fidacy.com/claim?ref=<that id>.

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

• 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.
• The agent calls request_payment. Fidacy checks it against the mandate (payee allowlist, per-tx cap, total cap, currency, time window, revocation).
• 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.
• 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

Tool	Backend	Purpose
assess_action	engine	Signed Fidacy trust verdict for a proposed action. Advisory.
request_payment	core	Authorize a payment action. ALLOW + grant, or DENY + rule.
verify_mandate	core	Read the mandate envelope + Fidacy public key.
get_audit_proof	core	Hash-chained proof for a decision id.
anchor_artifact	engine	Bitcoin-anchored integrity proof for any file (contract, invoice, prescription, claim, image, audio, video, conversation). Hashed locally; only the SHA-256 leaves. Returns a signed receipt.
check_artifact	engine	Check whether a file (or hash) was anchored, and its Bitcoin checkpoint state. A mismatch is the tampering signal.
upgrade	—	Start upgrading this local install to a real Fidacy account; preserves and migrates anonymous usage.

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:

Var	Default	Purpose
FIDACY_ENGINE_URL	https://api.fidacy.com	Base URL of the Fidacy engine.
FIDACY_ENGINE_API_KEY	(none)	An fky_live_ / fky_test_ key with scope assess:write.

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.

Telemetry

The install emits anonymous, opt-out usage telemetry so we can measure traction (installs, active agents, decision counts, deny-rate). It is best-effort and never on the decision critical path, so it can never block or slow a verdict.

• It carries an anonymous install id and counters only. It never includes payment content — no payee, amount, invoice, or mandate ever leaves your machine. Payload-carrying types are rejected by a strict schema.
• Turn it off completely with FIDACY_DISABLE_TELEMETRY=1 (or true).

Consistent with the product: you don't have to trust us, you can verify. The firewall runs fully with telemetry disabled.

Dev

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