---
title: "Connect an agent with MCP"
description: "Connect Figa to an MCP client with OAuth, selected workspaces and explicit read or write access."
canonical_url: "https://getfiga.com/help/developers/mcp/"
---

# 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](https://getfiga.com/help/developers/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](https://getfiga.com/help/bill-forecasts) 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](https://getfiga.com/help/developers/api#recurring-billing-settings). 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](https://getfiga.com/help/developers/api#list-payments), separately from current binary totals.

### Save amount and mark Paid

`figa_confirm_bill` accepts the shared [bill confirmation contract](https://getfiga.com/help/developers/api#confirm-bill) 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](https://getfiga.com/help/automations). 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.

**Client implementers**

Discover OAuth metadata from the server. Use authorization code with S256 PKCE and the resource URL above; scopes are `figa:read`, optional `figa:write`, and `offline_access` for refresh. Tokens belong in the client’s credential store, not skill files. API keys are for REST and do not replace MCP OAuth.

[Get the agent skills](https://getfiga.com/help/developers/agent-skills) or follow the [monthly invoice workflow](https://getfiga.com/help/developers/invoice-workflow).