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

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:

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

2. 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/[email protected] 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

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 (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

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

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.

Uninstall

The install writes an MCP server entry and, with install-hooks, a PreToolUse and a SessionEnd hook. The hooks run on every tool call in every project, not only the ones using Fidacy, so removing them is what stops the gate.

Every file the installer touched has a .fidacy-backup copy next to it holding the configuration from before Fidacy was added. Hooks are read when a session starts, so restart the host after editing.

Then remove the local credential and audit trail, and the package itself:

rm -rf ~/.fidacy          # account key + local audit trail; export first if you need it
npm uninstall -g @fidacy/mcp

Removing the install does not revoke your API keys or your live action mandates. Revoke keys in Settings and mandates in Authority Builder, and export any Incident Pack you want to keep before closing the account. Signed receipts stay verifiable against the public JWKS without an API key and without us.

Full offboarding guide, in order: https://fidacy.com/docs/uninstall

Connect your free account

The last step of npx -y @fidacy/mcp install --write offers to connect this machine to a free Fidacy account:

[fidacy] Connect this machine to your free Fidacy account.
[fidacy]   Your code: BCDF-GHJK
[fidacy]   Press Enter to open https://app.fidacy.com/connect?code=BCDF-GHJK

Press Enter, sign up or sign in, check that the console shows the same code, and click Connect. The terminal receives its key, stores it in ~/.fidacy/config.json with mode 0600 and wires your hosts. Press S to skip. Run it again any time with:

npx -y @fidacy/mcp login

Only an owner or admin of the company can approve a machine. A code expires after ten minutes and gives out its key once. Without a terminal the install never waits for a key press; use npx -y @fidacy/mcp connect --key-stdin with a key from the console instead.

Security locks

After a security incident, such as another installation taking over this machine, Fidacy can lock the machine or the agent. While it is locked, the hook holds every action, even one the mandate would allow, and tells the agent why. The engine refuses the same agent's key as well, so a copy of it is locked too.

A person unlocks it in one of two ways:

• an owner or admin at https://app.fidacy.com/security;
• someone at the machine, with one of the account's one-time emergency codes:

npx @fidacy/mcp unlock XXXX-XXXX-XXXX-XXXX

The API key on the machine alone never unlocks it, a code works once, and the owners are emailed when one is used. A lock on the whole organization is lifted only in the console. Keep the codes off any machine an agent runs on.

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 opt-out usage telemetry so we can measure adoption (installs, active agents, host family, 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 a random install id and counters only (install time, package version, host family, decision counts). It never includes payment content, commands, file paths or message text: no payee, amount, invoice, or mandate ever leaves your machine. Payload-carrying types are rejected by a strict schema.
• IP and country: when the Fidacy engine runs with FIDACY_INSTALL_TELEMETRY=1 (off by default), it also stores the IP address each report comes from and the country Vercel derives from it, so the report is not anonymous. Fidacy uses this to reach out to teams using the connector; see https://fidacy.com/privacy.
• If you connect an account, the account name, owner email and the machine name your hook reports are linked to this install in Fidacy's admin console. Set FIDACY_DISABLE_IDENTITY=1 to keep the machine name out of it.
• Turn telemetry off completely with FIDACY_DISABLE_TELEMETRY=1 (or true). Nothing is sent, so no IP or country is recorded either.

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