@fidacy/mcp

@fidacy/mcp

You're the one in charge of your AI agent. But it doesn't know your limits. Authorize, deny, release and record. You stay in control.

A drop-in MCP server that checks consequential actions against a cryptographically signed mandate before they run, then signs the yes and the no. Consequential means money leaving, data leaving, records being deleted, credentials being read. Non-custodial: Fidacy authorizes and proves, it never holds funds.

YOUR AI AGENT IS UNPROTECTED. GET YOUR FREE API KEY NOW. Installing the package does not activate protection. Create the key at app.fidacy.com/signup, set FIDACY_ENGINE_API_KEY where the agent runs and connect the executor that owns the downstream credential. Consequential actions remain blocked until then.

Four products come out of that one decision:

Authority	Say exactly what this agent may do, for how long, and up to how much.
Evidence	Prove what it did, to an auditor, an insurer, or opposing counsel.
Spend Guard	A ceiling on money that the agent cannot raise.
Assurance	Show the policy is getting better, with numbers instead of adjectives.

The MCP server connects MCP-compatible agents. Enforcement is agent-agnostic because it lives at the execution boundary: keep the Stripe, CRM, email, file or infrastructure credential inside a Fidacy connector and require the exact signed, single-use grant before the side effect. Native host adapters can additionally gate local tools. A plain MCP connection alone is never described as a hard gate.

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 have to trust us. You check the signature yourself.

To everyone who installed Fidacy

You are one of 588 installs. Between them the firewall has gated 4,069 actions, 89% 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

See it work in 10 seconds (no account, no agent)

Point it at any file you have:

npx -y @fidacy/mcp anchor contract.pdf

The file is hashed on your machine and never uploaded. What comes back is a signed receipt and a public link anyone can open to check that file against the record, without an account and without asking us. Change one byte and the hash stops matching.

Use it for anything a person could dispute later: a contract, an invoice, a claim, a prescription, a report your agent wrote.

Quick Start: Codex and Claude Code

Open Quick Start / Connections. Choose the host, name the connection and select permitted actions. The dashboard creates an agent, a 30-day starter mandate and a restricted key linked to both.

Run the command displayed there, then paste the connection key when prompted:

npx -y @fidacy/mcp@0.21.4 connect --host codex
# For Claude Code, use --host claude-code instead.

Restart the selected host. In the Codex CLI, open /hooks, inspect and approve the Fidacy definition. Codex skips new or changed hooks until trusted. Do not bypass this review. Test a denied and a permitted action with disposable data. No Agent ID, JWK or cnf needs to be copied for this bearer-key connection. Each host has its own selected connection. A general workspace key is different and is not bound to an individual agent.

The native hook requests signed grants for recognized actions under the linked mandate and organization policy. Expired, denied or unverifiable authorization fails closed. The starter mandate permits up to 1,000 actions and does not restrict resources within the selected action classes. Native host interception must be verified in your environment; MCP installation alone is not protection for arbitrary code or every tool. Restricted connection keys do not provide general assessment, account administration or legacy telemetry API access.

Managed connection boundary

Policy changes belong to authorized administrators in the dashboard. Chat consent does not override a denial. The local protect wizard refuses managed profiles. Missing, invalid or mismatched installed connection configuration fails closed. Managed hooks use the Fidacy production authority endpoint, not a local URL override. Local restrictions can still deny additional actions; removing them does not grant authority under the server-side mandate. Alerts do not create approval requests.

This release is not endpoint isolation. An operator who controls the host can disable its hooks. For employee deployments, administrators must separately control host configuration, credentials, network access and downstream executors. General workspace keys and legacy local evaluation are not managed deployments.

Advanced: general workspace key and local evaluation

Step 1. Get your free API key at app.fidacy.com/signup (free tier, no card). The key activates the account-owned authority boundary, server-signed verdicts and Bitcoin-anchored proofs.

Step 2. Copy the API key, then run one command:

npx -y @fidacy/mcp connect --evaluation

The installer reads the key from your clipboard without printing it, validates the account, detects the installed agent host and wires the MCP server. It automatically configures Claude, Cursor, Windsurf, VS Code, Codex and Gemini. When a native local gate is available it also proves a disposable delete was blocked before execution. Otherwise it reports the host as connected without falsely claiming its local tools are gated.

For an application-owned or custom agent runtime, use the existing public SDK. It uses the same account API key and already exposes assessments, Action Authority mandates, one-time grant decisions, decision feeds and Incident Packs:

import { Fidacy, hashActionContext } from "@fidacy/sdk";

const fidacy = new Fidacy({
  apiKey: process.env.FIDACY_ENGINE_API_KEY,
});

const contextHash = await hashActionContext(localRequest);
const decision = await fidacy.actionMandates.decide(mandateId, {
  action: "stripe.refund.create",
  resource: "stripe:payment_intent:pi_123",
  contextHash,
});

if (!decision.grant) throw new Error("Action refused");
// Give the grant only to the connector that owns the downstream credential.

If an agent retains the raw credential or another path to the protected system, that path is outside coverage. Agent-agnostic does not mean bypass-agnostic.

The MCP firewall's local decisions run on your machine, offline and 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? Your AI agent is unprotected. Fidacy refuses consequential actions with activation_required and does not create an authority verdict or grant. Get the free key, set FIDACY_ENGINE_API_KEY and connect the protected executor before retrying. An agent that still holds a raw credential has a path outside Fidacy and is not fully protected.

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 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 (decide and sign): 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, before the agent acts on someone's behalf. Holds nothing.
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	none	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

Codex desktop, CLI and IDE

npx -y @fidacy/mcp install --write

This registers the MCP server and merges a native PreToolUse hook into ~/.codex/hooks.json. Codex displays Fidacy is checking authority while the gate runs. A denied action is stopped before execution and appears inside the agent as a Fidacy security alert with the protected outcome, reason and evidence state. Existing hooks are preserved and the previous file is backed up.

Codex requires the operator to review and trust a new hook. Restart Codex and open /hooks if the trust prompt is waiting. The desktop app, CLI and IDE use the same Codex configuration.

Claude Code

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

Then run npx -y @fidacy/mcp install-hooks to enable the same visible pre-execution experience for supported Claude Code tool calls.

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