Agents
Agents
FamilyOFX is built so an AI agent can work on your family office data while a person keeps the final say on changes. Agents connect over MCP at https://familyofx.com/api/mcp.
Ways to connect
| Agent | How it signs in |
|---|---|
| Claude, ChatGPT, Copilot, and other MCP apps | OAuth. You approve one organisation on the consent page. See MCP connections. |
| Scheduled jobs, servers, agents, and other clients with no browser | An API key. Send it as Authorization: Bearer <key>. |
Create an API key
- Open Settings → Integrations → API keys and Webhooks.
- Under API keys, choose Create key and name it after where it will run.
- Turn on Apply every change without approval if holdings, money, and every other change should apply straight away. Leave it off and every change waits.
- Copy the key. It is shown once.
The key acts as you, in this organisation only. Use it from an agent, a scheduled job, or another service. If you leave the organisation the key stops working. You can switch Apply every change without approval later on the key. There is no setting in between: a key either waits for every change or applies every change. Owners and admins can create and revoke keys, and the list shows when each key was last used.
What agents can do
| Tool | Use |
|---|---|
get_portfolio_summary | Consolidated NAV, allocation, currency exposure, and largest holdings. |
portfolio_analytics | NAV split by legal entity, custodian, asset type, or currency. Cash flows by month, quarter, or year. |
positions, transactions, costs, cashflow_plans | Search holdings, transactions, costs, and forecast rows. |
contacts, companies, legal_entities, deals | CRM and structure lookups. |
tasks, calendar_events, documents, product_docs | Tasks, meetings, files already in FamilyOFX, and product help. |
<name>_write | Proposes a change to that record type. Returns an approval id and link. |
list_pending_approvals, get_approval_status | Follow what is waiting and what was accepted. |
batch_import_from_document | Import holdings or transactions from a document already uploaded. |
Read results include structured data, and records with a page in FamilyOFX carry a url the agent can give you.
Approvals
Changes never apply silently. Each _write call creates a pending approval in AI Agents. The agent can call get_approval_status to see the result, or receive the approval.decided webhook.
An owner or admin can let one MCP connection change tasks, calendar events, or document links without approval. Holdings, money, and records with history still wait for that connection.
An API key is all or nothing. Leave Apply every change without approval off and every change waits. Turn it on and every change applies, including holdings and money.
A client that asks only for the ofx:read scope gets read tools only.
Webhooks
Webhooks tell an agent, a warehouse, or another service when something happens, so it does not need to keep checking.
- Open Settings → Integrations → API keys and Webhooks.
- Under Webhooks, choose Add webhook, enter a public https URL, and pick events.
- Copy the signing secret. It is shown once. Use Send test to check delivery.
- Open Deliveries to see recent attempts, or Replay to send stored events again from a chosen time.
| Event | Sent when |
|---|---|
approval.decided | An approval is accepted or rejected. Includes ids of created records. |
position.created / updated / deleted | A holding is created, edited, or removed. updated also fires when a transaction changes the holding. |
transaction.created / updated / deleted | A transaction is recorded, edited, or removed. |
cost.created / updated / deleted | A cost is created, edited, or removed. |
document.created / updated / deleted | A document or note is uploaded, edited, or removed. |
contact.created / updated / deleted | A contact is created, edited, or removed. |
company.created / updated / deleted | A company is created, edited, or removed. |
legal_entity.created / updated / deleted | A legal entity is created, edited, or removed. |
deal.created / updated / deleted | A deal is created, edited, or removed. |
task.created / updated / deleted | A task is created, edited, or removed. |
calendar_event.created / updated / deleted | A calendar event is created, edited, or removed. |
Each delivery is a JSON POST with a delivery id, a stable eventId, the event type, the organisation id, and record ids only. Fetch the current record with MCP tools or the SDK. The x-ofx-signature header is t=<unix time>,v1=<HMAC-SHA256 of "<t>.<body>"> using your signing secret. Check it, and reject old timestamps.
Deliveries are queued. FamilyOFX retries with exponential backoff (up to eight attempts, starting at 30 seconds) on network errors, HTTP 429, and 5xx. Other 4xx responses fail immediately. A webhook pauses after 20 failed events in a row. Delivery history is kept for 30 days. Replay keeps the same eventId and mints a new delivery id; receivers should dedupe on both.
Warehouse connectors (for example Databricks or Snowflake) live outside FamilyOFX. They subscribe to these webhooks, then upsert or delete rows through the SDK. Use an SDK list for the initial backfill; use replay only to catch up within the 30-day window.
Limits
- One organisation per connection or key.
- No payments, transfers, or deletes over MCP.
- Documents must be uploaded in FamilyOFX before an agent can read or import them.