Integrations

Use Fidacy from an MCP host

@fidacy/mcp makes Fidacy operations available to a compatible MCP host. It can ask for a signed assessment, apply its local payment guardrails, and register a locally computed artifact hash. Installing an MCP server does not automatically intercept every tool the host can call. The host or workflow still has to call Fidacy before a consequential action, and an executor must redeem a grant to make a payment boundary enforceable.

SDK, local MCP, or hosted MCP?

Surface	Use it when	What it establishes
`@fidacy/sdk`	You own the application code around an action.	An application can call the assessment or authority APIs directly.
`@fidacy/mcp`	You run a local MCP-compatible host and want Fidacy tools in that host.	The host can request decisions and use the package's local payment guardrails.
`Hosted MCP`	You want OAuth rather than an API key in a local configuration file.	The hosted server exposes assessment and artifact tools under a scoped, revocable credential.

These surfaces can coexist. They reach the same engine where a server assessment is requested, but a signed assessment is not itself a downstream side effect. See Enforce the grant for the boundary that redeems a one-time grant.

Install locally

Add the stdio server to an MCP host. A key is required for server-signed assessments. Start with a test key while you build.

{
  "mcpServers": {
    "fidacy": {
      "command": "npx",
      "args": ["-y", "@fidacy/mcp"],
      "env": {
        "FIDACY_ENGINE_URL": "https://api.fidacy.com",
        "FIDACY_ENGINE_API_KEY": "fky_test_…"
      }
    }
  }
}

Create a key in app.fidacy.com with assess:writefor assess_action. Artifact anchoring accepts artifact:write or assess:write. Keep separate keys per workload and give each only the scopes it needs.

What the local server exposes

The current package has three groups of tools. Hosts decide which of these to call. It does not observe other host tools by default.

Group	Tools	Scope
Payment guardrails	`request_payment`, `verify_mandate`, `get_audit_proof`	Local mandate decisions and local audit proof. An external executor must verify a compatible grant before a payment moves.
Operator visibility	`spend_summary`, `list_decisions`, `explain_decision`, `sentinel_alerts`	Read-only reports over the local payment history.
Engine evidence	`assess_action`, `anchor_artifact`, `check_artifact`	Server-signed action decisions and account-scoped artifact evidence. Files are hashed locally when a path is supplied.

The package also includes upgrade and the consent-based register_email onboarding tools. They are not decision or execution controls.

Ask for a signed assessment

assess_actionmaps to the engine's assessment route. The agent submits a proposed action and receives an approve, review, or deny decision with a signed payload.

POST/v1/assess

{
  "decision": "approve",
  "assessmentId": "…",
  "riskPayloadJws": "eyJ…",
  "signingKeyId": "…"
}

·approve is a decision that your integration may honor. It is not a one-time execution grant.
·review is not an approval. Pause and obtain the required step-up.
·deny means the integration should not execute the proposed action.

Choose a safe failure policy in the caller. A network, authentication, rate-limit, or server error has no approval semantics. For a consequential action, fail closed or route to human review. Do not reinterpret an unavailable assessment as an approval.

Make a payment boundary real

request_payment produces a local allow or deny against a local mandate. For an authority boundary whose grant redemption is enforced server-side, create an Action Authority mandate and redeem its one-time grant in the protected executor. That executor must refuse an absent, expired, mismatched, or replayed grant.

Follow the Action Authority and Enforce the grant guides when an action has to be impossible without the authorization.

Verify signed evidence

Server assessment payloads are JWS records that can be checked against Fidacy's public JWKS. Artifact and audit evidence have their own status and anchoring lifecycle. A Bitcoin checkpoint makes a confirmed checkpoint tamper-evident after the fact; it does not prove that an MCP host observed every action it could have taken.

GET/.well-known/jwks.json

See Verify signed evidence for the verification path and Control Coverage for the current observable boundary.

← PreviousAgent Quickstart

Next →Hosted MCP (OAuth)