Financier docs

Financier

Official agent and developer tooling for Financier: a personal finance plan built from a person's own bank data. Financier is API-first. Everything a person can do in the app, an agent can do over MCP, the REST API, this SDK or this CLI.

MCP server	https://financier.sh/mcp (Streamable HTTP; OAuth 2.1 or x-api-key)
Docs MCP server	https://financier.sh/mcp/docs (no credentials)
REST API	https://financier.sh/api/v1, OpenAPI, reference
TypeScript SDK	@financier-sh/sdk
CLI	@financier-sh/cli (financier)
Agent skill	skills/financier/SKILL.md
Agent plugin	plugin.json + mcp.json
MCP registry	sh.financier/financier, sh.financier/financier-docs
A2A 1.0	agent card, JSON-RPC at https://financier.sh/a2a
Ask the docs (NLWeb)	POST https://financier.sh/ask
Agent identity, no account	POST https://financier.sh/agent/identity (sandbox-only until a person claims it)
Webhooks	Standard Webhooks + Web Bot Auth (keys)
Agent index	llms.txt, auth.md

Accounts are invite-only for now. The sandbox bank (provider demo) gives any account a synthetic household to try everything on.

MCP

{
  "mcpServers": {
    "financier": { "type": "http", "url": "https://financier.sh/mcp" }
  }
}

Claude Code: claude mcp add --transport http financier https://financier.sh/mcp

SDK

npm install @financier-sh/sdk

import { createFinancier } from "@financier-sh/sdk";

const financier = createFinancier({ apiKey: process.env.FINANCIER_API_KEY });
await financier.connections.linkSandbox();
for await (const event of financier.plan.buildStream()) console.log(event.stage);
const view = await financier.plan.view();
console.log(view?.stages[view.current]?.name, view?.plan.monthly.surplus);

Webhooks

import { verifyWebhook } from "@financier-sh/sdk";

// In your handler: the raw body, the request headers, and the secret from webhooks.create.
if (!(await verifyWebhook(rawBody, request.headers, process.env.FINANCIER_WEBHOOK_SECRET!)))
  return new Response("bad signature", { status: 401 });

Events: plan.built, recurring.detected, bank.reconnect_required, webhook.test. Every delivery is also signed with Web Bot Auth, verifiable against financier.sh's key directory without a shared secret.

Agents without an account

An agent can start before any person is involved: POST /agent/identity {"type":"anonymous"} returns a sandbox-only identity and a claim token. When a person wants the agent to work on their real account, the agent starts a claim with their email, shows them the code, and the person approves it at financier.sh/claim. The full flow, with requests, is in auth.md.

CLI

npm install -g @financier-sh/cli
financier login          # paste an API key from Settings, Developer
financier sandbox        # link the synthetic household
financier build          # sync, categorise, build the plan
financier plan           # stage, monthly figures, actions
financier plan --json    # the same, for scripts and agents
financier spending --from 2026-08-01 --by merchant
financier webhooks add https://example.com/hooks/financier --events plan.built

This repository

The Financier app itself is private. This repository holds the public surface: the SDK, the CLI, the agent skill, the plugin manifest and the MCP registry entries. The SDK's types are generated from the live OpenAPI document (bun run generate).

License

MIT