io.github.figuard/figuard-mcp

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').

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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