Building Financial Tools on Real Data: FYN's MCP Server and Agent API

If you're building an AI agent — a coding agent, a personal assistant, or a vertical finance tool — and you need your user's real financial data, you have a painful constraint: that data lives behind bank logins, and the options are "user pastes a screenshot" or "grant your service broad read access and trust us."

FYN sits in between. Your user keeps their data in FYN (bank sync via Plaid, receipts with AI OCR, budgets, subscriptions), and your agent consumes it through two read-only interfaces: an MCP server and a REST agent API with per-user, revocable keys. You never see a bank credential; the user never pastes a secret into your prompt.

The Two Surfaces

MCP (for MCP clients). https://api.fyn.fyi/v1/mcp. Your client authenticates with OAuth 2.1 + PKCE and dynamic client registration — the same dance Claude, ChatGPT, and Cursor already do. FYN publishes standard discovery, so a conformant client can bootstrap the whole setup from:

• GET https://api.fyn.fyi/.well-known/oauth-protected-resource (RFC 9728)
• GET https://api.fyn.fyi/.well-known/oauth-authorization-server (RFC 8414)

Once authorized, tools expose the financial data plane — spending breakdowns, budgets, net worth, insights, receipt RAG — with schemas your client can use at runtime.

REST agent API (for everything else). Basehttps://api.fyn.fyi/v1/agent, Bearer key auth. The user creates a key from FYN settings (shown once, hashed at rest, revocable instantly) and you set it in your environment. 24 data endpoints plus 4 key-management endpoints, all read-only, all scoped to that one account.

Machine-Readable Front Door

Since you're probably an agent reading this: FYN publishes both a short index (fyn.fyi/llms.txt) and a full reference (fyn.fyi/llms-full.txt) covering every endpoint, its parameters, the response envelope, and rate limits. There's also an installable agent skill in the fynfyi/agent-skill repo if your harness supports Agent Skills.

The Response Envelope (Design It Once, Parse It Everywhere)

Every REST endpoint returns the same shape, which makes integration code boring — in the best way:

{
  "success": true,
  "data": { ... },
  "meta": {
    "plan": "free",
    "rateLimit": { "remaining": 49, "limit": 50 }
  }
}

Two details worth designing around: meta.plan tells you whether the user has Pro (receipt RAG and affordability endpoints are Pro-only), andmeta.rateLimit lets you back off before hitting a 429. Errors come back with the same envelope, success: false, an explanatory message in data.error, and the right HTTP status.

Working Examples

A spending breakdown — the call most finance UX reduces to:

POST /v1/agent/spending/breakdown
{ "group_by": "category", "start_date": "2026-07-01", "end_date": "2026-07-31" }

And a health score to anchor any "how's my money this month" screen:

GET /v1/agent/insights/health

Pro-tier differentiation you can build on: receipt RAG (/v1/agent/receipts/rag) answers questions like "what did I buy in that Costco trip?" down to line items, and/v1/agent/affordability converts "can I buy this $4,500 laptop?" into a grounded number.

Trust Boundaries (What Your Users Will Ask)

• Read-only, end to end. Plaid connections are read-only; FYN cannot initiate transfers, and no agent endpoint writes to the financial account.
• Per-user scoping. A key or OAuth grant for user A never leaks user B's data. Multi-user products: one key/connection per user.
• Revocability is instant. The user revokes from FYN settings and subsequent calls return 401 — treat 401 as "ask your user to reconnect," not as a bug to retry.
• Quotas: free is 50 API calls / 10 RAG queries per day; Pro is 2,000 / 500. If your tool hammers an endpoint, checkmeta.rateLimit.

What This Is Not

It's not a raw bank data stream — FYN layers categorization, receipt intelligence, and derived metrics on top of the transactions, which is where the value is for agent UX. It's not write access to move money, and we deliberately don't plan to be.

If you want the reference: the full API docs have every endpoint with request and response examples, and the /agents page has the MCP setup and quick test.