Connect an agent with MCP

MCP lets your agent discover Figa tools and work with your workspace. Use it to answer questions, organize expenses and update recurring bills. In clients that support MCP Apps, the expense tool can also display an interactive view.

Connect

1. In your client’s integrations or MCP settings, add a remote server with Streamable HTTP transport and this URL:

https://api.figa.cc/mcp

2. Choose OAuth. Sign in to Figa and review the client and redirect host shown on the consent screen.
3. Select the workspaces to connect and choose Read only or Read & write. You must own or administer those workspaces.
4. Ask: “List my Figa workspaces, then show this month’s expenses in [workspace].” Check the workspace, dates and currency in the result.

ChatGPT and Claude can connect to a custom remote MCP server. The availability and location of that setting depend on the client and plan. Other agents need remote MCP with OAuth, or can use the REST API. A public directory listing is separate from connecting by URL.

What an agent can do

• Read and analyze: workspaces, context, expenses, history, payments, summaries, period comparisons and recurring commitments.
• Organize: create, update and delete local categories; create, rename and delete tags; assign categories, recipients and tags to expenses.
• Maintain expenses: create or edit one-time and recurring expenses, confirm bill amounts, adjust estimates, and set Paid or Unpaid.
• Manage recurrence: preview and apply supported pause, resume, cancel-pause and end actions. A count-limited installment series does not support these activity actions.

The connected server’s tools/list is the current contract. Use figa_get_context for workspace permissions and plan limits; a general capability does not imply that every REST operation has an MCP tool. Shared organization categories are readable and assignable; workspace connections cannot edit them. Standalone recipient management, account administration, notifications and attachment transfer use other supported surfaces.

Categories, tags and series

Category is optional. For figa_create_expense, omit expense.categoryInput or send null to create without a category. For figa_update_expense, omit changes.categoryInput to preserve it, or send null to clear it within the selected edit scope. Existing IDs and legal drafts assign a category; invalid IDs and empty drafts remain errors. Read the expense back after saving.

{
  "name": "figa_create_expense",
  "arguments": {
    "workspaceId": "WORKSPACE_ID",
    "requestId": "NEW_UUID",
    "expense": { "name": "Hosting", "amount": 4720, "currency": "EUR" }
  }
}

To clear the category later, use figa_update_expense with the returned expenseId, a new request UUID and changes: { "categoryInput": null }. Recurring updates also need the intended edit scope.

Prefer figa_create_category, figa_update_category and figa_delete_category for category management. An expense’s categoryInput can also create a local category from a name or draft: use an existing ID when reassigning. Names are unique among siblings, not across the whole category tree. Category deletion blocks active references and children, but can permanently remove related archived records; inspect the tool description before deleting.

tagIds or tagInputs replaces the complete tag set. Omit both to preserve it; send [] to clear it. For a recurring expense, choose THIS_INSTANCE, FUTURE_INSTANCES or ALL_INSTANCES. All-series tag edits update inherited history and defaults; explicit overrides and locked tag sets remain.

Use returned IDs as-is. figa_get_series expects a template/version ID in its expenseId input: use templateId from the monthly list, seriesId from the expense view, or rootId from the series list. An occurrence ID identifies a different object.

Bill forecasts and billing methods

For ordinary variable monthly bills, choose last_confirmed, recent_average, seasonal or manual. The forecast guide explains fallbacks and reliability. Read figa_get_bill for the occurrence’s rootId, scheduledDate, settingsRevision and nested bill.

• Create: figa_create_expense accepts expense.amountMode: "variable", a monthly schedule and forecastStrategy. amount is the starting estimate, or null; manual forecasts require an amount.
• Set forecasts across the series: call figa_update_bill_forecast with expenseId: rootId and settings: { strategy, startAmount, expectedRevision }. Use the current settingsRevision; startAmount is nullable except for manual. Omitted strategy preserves existing methods.
• Save with other fields: put the same settings in figa_update_expense.changes.forecastSettings with editScope: "ALL_INSTANCES". The whole save uses that scope.
• Change fixed ↔ variable from an occurrence: use figa_update_expense with changes.recurringSettings and editScope: "FUTURE_INSTANCES". Supply canonical from, expectedRevision and amountMode, plus amount for fixed or strategy/startAmount for variable. See the shared payload and restrictions. Earlier settings, confirmed invoices and Paid expenses are preserved.

All writes also need workspaceId and a UUID requestId. Reread after saving. In bill.forecast, source is the applied basis; assessment.strategy is the selected method. Report assessment.reliability and fallbackReason when relevant, and keep estimates separate from confirmed amounts. Reliability is not a probability; old saved snapshots may omit assessment.

Set Paid or Unpaid

Read figa_get_expense, then call figa_set_payment_status with workspaceId, expenseId, a UUID requestId and status containing isPaid, expectedEditContext, expectedPaymentStatusRevision and, for confirmed bills, expectedBillRevision. Optional paymentDate applies only to a real Unpaid → Paid transition. A fresh repeated Paid preserves its date; Unpaid clears it. No amount or payment row is created. Old add/remove/clear tools return 410 LEGACY_PAYMENT_OPERATION_REMOVED. The archive remains readable, separately from current binary totals.

Save amount and mark Paid

figa_confirm_bill accepts the shared bill confirmation contract in bill. Omitting bill.markPaid preserves payment status. Sending true atomically confirms the actual amount and sets Paid; include the pre-write expectedEditContext, expectedPaymentStatusRevision, bill/settings revisions and service activity revision when applicable. Existing Paid preserves its known or unknown date. The operation creates no payment-history row.

Keep request IDs and the whole payload unchanged for retries, including the Paid intent and optional date. Ordinary confirmation retains only its last request receipt; services retain their existing durable receipts. After a later Unpaid, replay does not set Paid again. A receipt can describe an earlier result, so call figa_get_expense for current status.

Accurate answers and safe retries

Amounts use the currency and minor units stated in each response. Keep confirmed amounts, estimates and unknown valuations distinct. Monthly lists use Unix seconds; the range view uses ISO calendar dates and accepts at most 24 calendar months. Paginate results and disclose plan restrictions instead of treating missing data as zero.

Every mutation needs a UUID requestId. Keep the ID and input unchanged when retrying within 24 hours. After an uncertain result, inspect the saved state before trying a new operation. Save amount preserves status; optional markPaid saves the amount and sets Paid atomically. Status changes do not move money.

Connection lifetime and troubleshooting

• Workspace unavailable: API keys and MCP connections share the plan’s integration slots. Check existing connections and your role.
• Reauthentication required: reconnect in the client. Access tokens last five minutes; refresh requires the client to request offline_access and use refresh tokens. The underlying connection lasts up to 30 days. Repeated failures shortly after connecting need a client/OAuth check.
• 403 before sign-in: registration or discovery may be blocked by the edge firewall. Keep the timestamp and request/Ray ID for support; repeatedly changing credentials will not fix an HTTP challenge.
• Tools missing after an update: refresh the client’s tool discovery. Verify the connected server URL and environment.
• View fails but tools work: try a fresh read. MCP Apps support varies by host; text and structured results remain available. If tools also require reauthentication, restore the connection first.

Get the agent skills or follow the monthly invoice workflow.