# io.github.figuard/figuard-mcp (npm · figuard-mcp)

Pre-flight spend authorization for AI agents. Set a budget, enforce limits, audit every decision.

- Trust score: 67/100 (medium)
- Change this week: +24
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-03

## Components

- npm · `figuard-mcp`: 67/100 (this document), [markdown](https://verifymcp.io/servers/figuard-figuard-mcp/figuard-mcp.md), [page](https://verifymcp.io/servers/figuard-figuard-mcp/figuard-mcp)

## Channel facts

- Registry: `npm`
- Package: `figuard-mcp`
- Version: `1.2.0`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-03.

- **Supply Chain Security**: 87/100
  - No malware found by supply-chain analysis.
  - Only part of the dependency tree could be resolved (95 of 99), so this covers what we could see, not the whole tree.
  - No install/post-install scripts declared.
  - Only part of the dependency tree could be resolved (95 of 99), so this covers what we could see, not the whole tree.
- **Provenance & Transparency**: 45/100
  - Source repository is publicly reachable at the declared URL.
  - Provenance check failed: no build-provenance attestation is published.
  - Clear OSI-approved license (Apache-2.0).
  - Actively maintained (last published 47 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 64/100
  - AI-judged instruction clarity (excellent).
  - Context-footprint check failed: tool/resource definitions use about 3118 tokens (~194/item across 16 items; 16 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 27/100
  - Stability observed for 8 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### Claude

```bash
claude mcp add figuard-figuard-mcp -- npx -y figuard-mcp
```

### Codex

```bash
codex mcp add figuard-figuard-mcp -- npx -y figuard-mcp
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "figuard-figuard-mcp": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "figuard-mcp"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add figuard-figuard-mcp --command npx --arg -y --arg figuard-mcp
```

### Hermes

```yaml
mcp_servers:
  figuard-figuard-mcp:
    command: "npx"
    args: ["-y", "figuard-mcp"]
```

### Other

```json
{
  "mcpServers": {
    "figuard-figuard-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "figuard-mcp"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-03 (score 67, +4)

- [functional improvement] Stability: unverified → 0.27

### 2026-08-02 (score 63, +45)

- [security regression] Provenance: unverified → fail
- [security improvement] Install scripts: unverified → pass
- [security improvement] Known CVEs: unverified → partial
- [security improvement] Malware scan: unverified → pass
- [security] Stability: Stability not yet verified: not enough scan history yet (needs a 30-day window).
- [functional regression] Security disclosure: fail → unverified
- [functional regression] Tool coverage: 100 → unverified
- [functional improvement] MCP protocol: unverified → pass
- [functional improvement] Maintenance: unverified → pass
- [functional improvement] Dependency health: unverified → partial
- [functional improvement] License: unverified → pass
- [functional improvement] Schema quality: unverified → excellent
- [functional] First check of Schema quality: unverified
- [functional] Licence: Apache-2.0

### 2026-08-01 (score 18, −16)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-31 (score 34, −9)

- [security regression] Provenance: unverified → fail
- [security regression] Malware scan: pass → unverified
- [security improvement] Install scripts: unverified → pass
- [functional improvement] Maintenance: unverified → pass
- [functional improvement] License: unverified → pass
- [functional] Licence: Apache-2.0

### 2026-07-27 (score 43)

First indexed and scored.

## MCP tools (16)

### `figuard_create_budget` (~687 tokens)

Create a new FiGuard budget for an agent session. Returns a session_token that must be passed to figuard_authorize. The session_token is only returned once — store it for the duration of the agent session. Use currency (e.g. 'USD') for monetary budgets. Use unit (e.g. 'tokens') for resource budgets. Optionally add allocations to ring-fence spend by category (e.g. separate limits for flights and hotels). Pass external_reference to make this call idempotent: if a live budget with that reference already exists it is returned (HTTP 200) instead of creating a duplicate. If the reference exists but with a different configuration, a 409 is returned. Use this to safely handle orchestrator restarts.

Input parameters:

- `allocations` (array): Optional category-level caps. Each allocation is an independent maximum — flights capped at $300 means flights can never exceed $300, regardless of what other categories spend. Allocation limits must…
- `anomaly_detection_enabled` (boolean): When true, FiGuard monitors spend requests for statistical anomalies. Recommended for production.
- `auto_pause_on_anomaly` (boolean): Controls anomaly response mode. When true (default), an anomalous request pauses the budget — no further spend until a human resumes it. When false (advisory mode), the anomalous request is still den…
- `currency` (string): ISO 4217 currency code (e.g. 'USD', 'EUR'). Required for monetary budgets. Omit for resource budgets.
- `expires_in` (string): How long the budget is valid. Accepts '24h', '7d', '30m', or a number of seconds. Defaults to '24h'.
- `external_reference` (string): Optional stable identifier for this budget (e.g. 'run-abc-123', 'order-456'). When provided, re-calling figuard_create_budget with the same external_reference returns the existing live budget instead…
- `intent_context` (string): Optional human-readable description of what this budget is for (e.g. 'Book travel to NYC for user_123').
- `total_limit` (number, required): Maximum total amount the agent is allowed to spend. For USD budgets this is dollars, not cents.
- `unit` (string): Resource unit label (e.g. 'tokens', 'api_calls'). Required for resource budgets. Omit for monetary budgets.
- `user_id` (string, required): Identifier for the user or agent session this budget belongs to.
- `velocity_max_amount_per_hour` (number): Max total requestedQuantity per rolling 1-hour window.
- `velocity_max_per_day` (number): Max authorize attempts per rolling 24-hour window.
- `velocity_max_per_minute` (number): Max authorize attempts per rolling 1-minute window. Denied with VELOCITY_LIMIT_EXCEEDED when exceeded.

### `figuard_authorize` (~579 tokens)

Pre-flight authorization — ask FiGuard if a spend is permitted before taking any action. Returns AUTHORIZED (with event_id) or DENIED (with denial_reason). Always call this before spending. Only proceed if the result is AUTHORIZED. The idempotency_key must be unique per logical spend intent — reuse the same key on retries so the same spend is never double-authorized. After the action succeeds call figuard_confirm; if it fails call figuard_fail. IMPORTANT: When the budget has allocations, pass the exact category string from the budget's allocation_categories field — do not use synonyms or plural forms (e.g. use 'flight' not 'flights').

Input parameters:

- `action_type` (string, required): Type of action being authorized (e.g. 'PURCHASE', 'REFUND', 'LLM_CALL', 'API_CALL').
- `agent_id` (string, required): Identifier for the agent making this request (e.g. 'booking-agent', 'refund-agent').
- `claimed_category` (string): Category of this spend (e.g. 'flight', 'hotel'). Required when the budget has allocations.
- `claimed_item_type` (string): Specific item type (e.g. 'economy_ticket', 'hotel_room'). Used for STRICT enforcement mode.
- `description` (string, required): Human-readable description of what the agent is about to do (e.g. 'Book NYC to LAX flight').
- `dry_run` (boolean): When true, runs all enforcement checks and returns AUTHORIZED/DENIED but writes nothing to the ledger. Use for testing.
- `idempotency_key` (string): Optional. Unique key for this spend intent. Use a UUID or stable identifier. Reuse on retries — never generate a new key for the same logical spend. When omitted, the SDK auto-generates a UUID v4 (sa…
- `parent_event_id` (string): event_id of the parent spend if this is a sub-agent call. Used to build the causal chain. The parent event must be in AUTHORIZED or CONFIRMED state — passing a DENIED or VOIDED parent_event_id will r…
- `requested_quantity` (number, required): Amount to reserve. For USD budgets this is dollars. For token budgets this is the token count.
- `reserve` (boolean): Optional (default true). Set false for an orchestrator/coordinator spend-tree root that should hold NO capacity and have no confirmation timeout — sub-agents authorize against the budget directly. Us…
- `session_token` (string, required): The session_token returned by figuard_create_budget. Never expose this in logs.
- `trace_id` (string): Optional run ID to link all events from a single agent run together for debugging.

### `figuard_confirm` (~127 tokens)

Confirm a previously authorized spend after the action succeeds. Pass the actual amount spent — it may differ from the authorized amount (e.g. authorized $340, flight cost $337.50). This releases the difference back to the budget. Always confirm after a successful action.

Input parameters:

- `confirmed_quantity` (number, required): Actual amount consumed. May be less than the authorized amount.
- `event_id` (string, required): The event_id returned by figuard_authorize.
- `external_transaction_id` (string): Optional reference from your payment processor (e.g. Stripe charge ID) for audit purposes.

### `figuard_fail` (~116 tokens)

Mark an authorized spend as failed when the action did not succeed (e.g. payment processor declined, API error). This releases the reserved funds back to the budget so they can be used again.

Input parameters:

- `error_message` (string): Optional human-readable error detail for the audit log.
- `event_id` (string, required): The event_id returned by figuard_authorize.
- `reason` (string, required): Short reason code for the failure (e.g. 'PAYMENT_DECLINED', 'API_ERROR', 'TOOL_ERROR').

### `figuard_void` (~118 tokens)

Cancel an authorized reservation that was never used. Use this when the agent decides not to proceed with an action after authorizing it (e.g. user cancelled, better option found).

Input parameters:

- `event_id` (string, required): The event_id returned by figuard_authorize.
- `reason` (string, required): Short reason for voiding (e.g. 'USER_CANCELLED', 'BETTER_OPTION_FOUND', 'PLAN_CHANGED').
- `void_child_events` (boolean): When true, also void child events in the causal chain. Defaults to false.

### `figuard_get_budget` (~69 tokens)

Get the current state of a budget — total limit, amount spent, amount reserved, amount available, status, and per-category allocations. Use this to check remaining budget before planning an agent's actions.

Input parameters:

- `budget_id` (string, required): The budget ID (starts with 'bgt_').

### `figuard_get_ledger` (~149 tokens)

Query the authorization ledger for a budget — returns a paginated list of spend events (authorized, confirmed, denied, voided, failed). Use this to review what an agent has spent or to debug a denial.

Input parameters:

- `budget_id` (string, required): The budget ID (starts with 'bgt_').
- `decision` (string): Filter by event decision. Omit to return all events.
- `page` (number): Page number, zero-indexed. Defaults to 0.
- `size` (number): Events per page. Defaults to 20, max 100.
- `trace_id` (string): Filter by trace ID to see only events from a specific agent run.

### `figuard_resume_budget` (~159 tokens)

Resume a budget that was paused by anomaly detection or manually. A budget is paused when a spend request is statistically unusual (autoPauseOnAnomaly=true) or via PATCH /budgets/{id}. A human must review and provide an override reason before the budget can be used again. Requires override_reason explaining why the pause was reviewed and cleared.

Input parameters:

- `budget_id` (string, required): The budget ID (starts with 'bgt_').
- `override_by` (string): Optional identifier for the operator or system performing the override (e.g. 'ops-team', 'user_456').
- `override_reason` (string, required): Required explanation for why the budget is being resumed (e.g. 'Reviewed — legitimate bulk purchase approved by ops team').

### `figuard_extend_budget` (~169 tokens)

Extend a budget's expiry window. Use this to keep a long-running agent alive past its original expiry. The new expiry must be later than the current one and at most 24 hours from now. Can be called repeatedly (e.g. extend by 2 hours every 2 hours for a 6-hour task). Returns 409 if the budget is CANCELLED or EXHAUSTED. Returns 400 if the new expiry is earlier than the current one.

Input parameters:

- `budget_id` (string, required): The budget ID to extend.
- `expires_at` (string): Absolute ISO 8601 expiry timestamp. Mutually exclusive with expires_in.
- `expires_in` (string): Relative duration from now (e.g. '2h', '30m'). Mutually exclusive with expires_at.

### `figuard_create_delegation_token` (~181 tokens)

Create a scoped delegation token for a fleet budget. Each sub-agent (e.g. per-customer refund agent) gets its own token with per-category spend caps. The sub-agent calls figuard_authorize with this token exactly as it would with a normal session token — FiGuard enforces both the per-token caps and the fleet-level allocations transparently. The session_token is returned once — hand it to the sub-agent immediately and store it securely.

Input parameters:

- `budget_id` (string, required): The fleet budget ID to delegate from.
- `caps` (array, required): Per-category spend caps for this sub-agent. Only listed categories are cap-enforced at the delegation level. Categories not listed pass through to the fleet allocation only.
- `label` (string, required): Human-readable label for this token, e.g. 'refund-agent-order-123'.

### `figuard_revoke_delegation_token` (~77 tokens)

Revoke a delegation token immediately. Any subsequent figuard_authorize call using this token will be rejected with INVALID_SESSION_TOKEN. Already-authorized events are not affected. Fires DELEGATION_TOKEN_REVOKED webhook. Idempotent.

Input parameters:

- `token_id` (string, required): The delegation token ID to revoke.

### `figuard_get_delegation_token` (~56 tokens)

Get the current state of a delegation token — label, status, per-category cap usage. The raw session_token is never returned, only the prefix.

Input parameters:

- `token_id` (string, required): The delegation token ID.

### `figuard_cancel_batch` (~126 tokens)

Cancel one or more budgets. Use this to cancel a single budget (pass one ID) or up to 100 at once. This is the correct tool when the user asks to cancel, close, void, or abandon a budget — not figuard_void (which only cancels individual spend events, not budgets). Already-terminal budgets (EXPIRED, CANCELLED, EXHAUSTED) are included in the response without an error — the call is idempotent per budget.

Input parameters:

- `budget_ids` (array, required): List of budget IDs to cancel. Maximum 100.

### `figuard_fund_budget` (~191 tokens)

Adjust a budget's totalLimit in-place without creating a new session. Use CREDIT to top up a nearly-exhausted budget mid-run, DEBIT to reduce it, RESET to set a new absolute limit, or RESET_SPENT to start a fresh billing period (zeroes quantitySpent and reactivates EXHAUSTED budgets). Returns the budget state before and after the operation.

Input parameters:

- `amount` (number, required): Amount to apply. Must be positive.
- `budget_id` (string, required): ID of the budget to fund.
- `operation` (string, required): CREDIT: add amount to totalLimit. DEBIT: subtract amount (rejected if result < quantitySpent). RESET: set totalLimit to exactly amount. RESET_SPENT: zero quantitySpent, set new totalLimit, reactivate…
- `reason` (string): Optional note recorded in the response for audit purposes.

### `figuard_get_spend_tree` (~80 tokens)

Get the hierarchical spend tree for a budget — every event and its causal children (parent → child chains). Use to inspect what an agent (and its sub-agents) actually spent, including denied attempts. Returns roots and a total event count.

Input parameters:

- `budget_id` (string, required): The budget ID (starts with 'bgt_').

### `figuard_update_budget` (~234 tokens)

Update an existing budget's settings: total limit, velocity caps, expiry, trust mode, or status. Use trust_mode='FULL_ENFORCEMENT' to leave shadow mode and start blocking, or 'SHADOW' to observe without blocking. For crediting/debiting funds with audit semantics, prefer figuard_fund_budget instead.

Input parameters:

- `budget_id` (string, required): The budget ID (starts with 'bgt_').
- `expires_at` (string): New absolute ISO 8601 expiry (e.g. '2026-12-31T23:59:59Z').
- `status` (string): Budget status override (advanced).
- `total_limit` (number): New total spend limit.
- `trust_mode` (string): 'SHADOW' (run all checks, block nothing) or 'FULL_ENFORCEMENT' (block denied spends).
- `velocity_max_amount_per_hour` (number): New per-hour amount cap.
- `velocity_max_per_day` (number): New per-day authorize cap.
- `velocity_max_per_minute` (number): New per-minute authorize cap.

## Diagnostics

Captured diagnostic sections: Provenance, Dependencies. The full working is on the page: https://verifymcp.io/servers/figuard-figuard-mcp/figuard-mcp#diagnostics

## Score history

- 2026-08-03: 67
- 2026-08-02: 63
- 2026-08-01: 18
- 2026-07-31: 34
- 2026-07-29: 43
- 2026-07-28: 43
- 2026-07-27: 43

## Links

- npm package: https://www.npmjs.com/package/figuard-mcp
- Socket report: https://socket.dev/npm/package/figuard-mcp
- Repository: https://github.com/figuard/figuard-core
- Website: https://figuard.io/
- Changelog RSS feed: https://verifymcp.io/servers/figuard-figuard-mcp/figuard-mcp/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/figuard-figuard-mcp/figuard-mcp/changelog.json
- HTML version of this page: https://verifymcp.io/servers/figuard-figuard-mcp/figuard-mcp