Build or audit a Finch integration with AI agents

The Finch Integration Skills are a set of AI agent skills that guide an AI coding agent through building or auditing a Finch integration. Two skills — one backend, one frontend — build a new integration. You answer about ten questions about your stack and use case, and the agent generates the integration code and tests for each component: Finch Connect, token management, API calls, webhooks, and reauthentication. A third skill audits an integration you already have. Point it at your repo instead of answering setup questions, and it checks your existing backend and/or frontend code against the same rules the build skills use to generate code, then produces a severity-rated findings report — no code changes unless you ask for them afterward. See Audit an existing integration. The skills handle the integration plumbing. The application logic on top of the data — how you process, display, and act on it — remains yours to build.

Beta. The Finch Integration Skills are in active development. The Finch team continues to test and improve them. As with all AI-generated code, treat the output as a starting point, not production-ready code. Review it against the Finch docs and API reference, test it thoroughly, and revise it before you deploy.

What the skills generate

There are three skills: backend, frontend, and audit. Load the backend and frontend skills together for a fullstack build, or load only the one for the layer you own — the backend skill ends at “return the session token to the frontend”; the frontend skill starts there. Load the audit skill instead of either when you already have an integration and want it reviewed, not rebuilt. Backend skill generates:

Finch Connect session creation for the embedded and redirect flows, with reauthentication routing when a connection breaks
Authorization code exchange, access token encryption, and database persistence
A reusable Finch API client with rate limiting, pagination, and error handling
A data fetcher for each product scope you select, with upsert logic
A webhook handler with signature verification and event routing
A database schema and tests — unit tests with mocked HTTP, plus integration tests against the Finch Sandbox

Frontend skill generates:

A Connect button that fetches a session and launches Finch Connect
Embedded launch through the Finch React or JavaScript SDK, or the redirect flow with no SDK
Authorization code handoff to your backend on success
A reauthentication UI — a banner or settings-page component that re-launches Finch Connect when a connection breaks
Tests — component tests and end-to-end tests against the Finch Sandbox

Audit skill produces, instead of code:

An inventory of what’s actually implemented — Connect flow type, product scopes, entity handling, reauthentication, disconnect, webhooks, token storage, test coverage — for the backend, frontend, or both in one pass
A check of that inventory against the backend and frontend skills’ own correctness rules, plus a set of known deprecated patterns
A severity-rated findings report, with file:line evidence and a fix recommendation for each finding, cross-referenced to the relevant backend or frontend skill step
Fixes, only for findings you explicitly ask it to address afterward, implemented one at a time following the corresponding backend/frontend skill guidance

The backend and frontend skills are language- and framework-agnostic. Generated code is tailored to the stack you name.

The backend skill generates native HTTP implementations and does not use a Finch backend SDK. This keeps the generated code self-contained and consistent across languages. The frontend skill does use the Finch Connect SDK for the embedded flow.

Prerequisites

An AI coding agent that supports agent skills

You need an AI tool that can load a SKILL.md file — for example, Claude Code, Cursor, or Codex CLI. The skill drives the workflow; your agent generates the code.

The Finch documentation MCP server connected to your agent

Required. The skill provides the workflow structure; the Finch documentation MCP server supplies the specifics — current endpoint details, field names, response shapes, error codes, and SDK versions — while your agent generates code. The two are designed to work together, and the skill assumes the MCP server is connected.The server URL is https://developer.tryfinch.com/mcp. It’s public — no credentials or Finch account required to connect.

Claude Code
Claude (claude.ai / Desktop)
Other tools

Add the server from the terminal:

claude mcp add --transport http finch-docs https://developer.tryfinch.com/mcp

Confirm it connected:

claude mcp list

finch-docs should show as connected. This adds the server at the user level, so it’s available in any project — add --scope project instead if you only want it in the current one.

Go to claude.ai/settings/connectors.
Click Add custom connector.
Enter a name (for example, Finch docs) and the URL https://developer.tryfinch.com/mcp.
Click Add.
In a chat, click the attachments (plus) icon and select the connector to make it available.

Most MCP-capable tools support adding a remote server by URL — for example, Cursor and VS Code take a url entry in an mcp.json file. Check your tool’s documentation for the exact syntax; the value you need in every case is the same URL above.

A Finch developer account with a Sandbox application

You need a Sandbox application and its client_id and client_secret. The generated integration tests run against the Finch Sandbox. Sandbox and Production are separate applications with separate credentials — register redirect URIs and webhook endpoints in each. Create an account at dashboard.tryfinch.com.

If the MCP server isn’t connected, the skill still runs — but expect gaps. The skill falls back to web search or its own training data to fill in specifics it would otherwise look up live. This can produce code that references outdated field names or response shapes, an outdated SDK version or API surface, or an incomplete set of product scopes or webhook events — errors that surface as failed tests or runtime errors against the Sandbox, not as warnings during code generation. Connect the MCP server before starting the skill, not after something breaks.

This is not the same MCP as the Finch MCP Server. Finch has two separate MCP servers with similar names:

	Finch documentation MCP	Finch MCP Server
Purpose	Searches Finch’s documentation	Calls the live Finch API
Acts on	Published docs and API reference	A specific employer connection’s real data
Requires	Nothing — no credentials	A Finch `access_token` for that connection
Used for	Building this integration (this guide)	Querying employee/payroll data in natural language once connected

The Finch Integration Skills use the documentation MCP server described above. Connecting the Finch MCP Server instead won’t give the skill what it needs — it has no way to look up documentation.

Load the skills

Beta program
General availability (not yet active)

The skills are not yet published. Load the SKILL.md files your Finch contact shares with you directly into your agent — the backend and frontend files to build a new integration, or the audit file to review an existing one. Load both backend and frontend for a fullstack build.

Not yet active. The skills aren’t published at developer.tryfinch.com yet — npx skills add and the MCP resource route below won’t return them until they are. Use the Beta program tab for now.

Once published, add the skills from the Finch docs:

npx skills add https://developer.tryfinch.com

This installs all three skills — finch-integration-backend, finch-integration-frontend, and finch-integration-audit — into your agent’s context.If you’re already connected to the Finch documentation MCP server, you don’t need this separate install step — the server exposes all three SKILL.md files as MCP resources, and your agent can pull the one it needs directly from the connection:

Claude Code: in the prompt, type @ to open the resource picker and select the skill you need — backend, frontend, or audit — from the finch-docs server (whatever name you gave it in Step 2). Load backend and frontend together for a fullstack build; load audit on its own to review an existing integration.
Other MCP clients: look for a resource or attachment picker tied to the connected server — the exact UI varies by tool, but the underlying mechanism (an MCP resource, not a separate download) is the same.

Either path loads the same skill content into the agent’s context; the MCP resource route just skips the separate npx skills add install since the server connection already gives the agent access.

How it works

This section describes the backend and frontend skills’ build flow. For the audit skill, which doesn’t ask setup questions, see Audit an existing integration below.

Start the skill

Tell your agent you want to build a Finch integration and point it at the skill. The backend and frontend skills each open with a short setup questionnaire.

Answer the setup questions

Each skill runs through a short setup questionnaire before generating anything. Expect to cover:

Your stack — language, framework, database, and test framework
Your integration setup — new app or existing one, product scopes, and Connect flow
Your operational choices — how you identify each employer, reauthentication and webhook strategy, token storage, and test coverage

Answer each section before the agent continues. Your answers shape the generated code.

Review the generated code

The agent generates each component as a labeled, copy-ready section, with comments that link back to the relevant Finch documentation. Read it against the docs, adjust with follow-up prompts, and run the tests.

Test against the Sandbox

Run the generated integration tests against your Sandbox application. Complete a full Connect flow in the Sandbox before you point the integration at Production.

Audit an existing integration

Use the audit skill instead of the backend or frontend skill when you already have a Finch integration and want it checked for gaps — not built from scratch. Reach for it when the question is “is our existing integration missing anything?” rather than “help me build this.” The audit skill covers both layers in a single pass — point it at your backend, your frontend, or both, and it reports findings for whichever you include. You don’t need to run the backend and frontend skills separately to get equivalent coverage; the audit skill loads their checklists itself and evaluates your code against both.

The audit skill still depends on the backend and frontend skills — it fetches their audit criteria directly from the skill files, rather than duplicating them, via the Finch documentation MCP server or directly from the backend and frontend skill URLs. If that fetch fails, expect your agent to say so before proceeding — a report built only from general knowledge of Finch Connect is lower-confidence and shouldn’t be presented as a full audit against the current checklist.

To prompt it, tell your agent what to audit and point it at the skill — for example:

Audit my existing Finch integration for gaps using the Finch integration audit skill. It’s in src/integrations/finch on the backend and src/components/connect on the frontend — check both.

Or, if you already suspect a specific issue:

Run the Finch integration audit skill on our backend only. Reauthentication doesn’t seem to be triggering when a connection breaks — investigate that end-to-end, and check everything else too.

Even when you lead with a bug you’re confident is real and expect a quick patch, expect the same discovery pass and a written report first, not an immediate fix — the audit skill investigates and confirms every finding, including one you already suspected, before changing any code. The skill produces a written report only — findings with file:line evidence, severity, and remediation guidance. Review the report, then ask it to implement specific fixes one at a time as a separate, explicit follow-up if you want it to; it follows the corresponding backend or frontend skill’s guidance for each fix rather than improvising one.

What’s yours to build

Application logic is yours. The skills handle the integration plumbing — authentication, token management, API calls, webhooks — the high-effort work that looks similar across most Finch integrations. How your application processes, displays, and acts on the data takes additional development tailored to your use case.
Verify against the docs. Use the Implementation Guide and API reference to confirm the generated code matches current Finch API behavior. Response shapes change across API versions.
The skills work best together. A fullstack developer should load both — the backend skill ends at the session token, the frontend skill starts there.

Expect to iterate with additional prompts to fit the generated code to your application.

Time to integrate

You can answer the setup questions in under an hour and receive every component, then shift your time from writing integration code to reviewing, testing, and adapting it. Actual savings vary with your application’s complexity and how many revision cycles it takes, but most teams save several days to a few weeks compared to writing the plumbing by hand. For the audit skill, a pass is typically one agent conversation instead of a multi-day manual review.

Next steps

Finch Connect setup

How Finch Connect sessions and the embedded and redirect flows work.

API reference

Endpoint details, field definitions, and response shapes to verify generated code.

Reauthentication

What happens when a connection breaks and how to recover it.

Finch Sandbox

Test your integration end-to-end before going to Production.

​What the skills generate

​Prerequisites

​Load the skills

​How it works

​Audit an existing integration

​What’s yours to build

​Time to integrate

​Next steps

Finch Connect setup

API reference

Reauthentication

Finch Sandbox

What the skills generate

Prerequisites

Load the skills

How it works

Audit an existing integration

What’s yours to build

Time to integrate

Next steps