> ## Documentation Index
> Fetch the complete documentation index at: https://developer.tryfinch.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Build or audit a Finch integration with AI agents
> Finch Integration Skills guide an AI agent through building a new Finch integration or auditing an existing one — answer questions about your stack and get reviewable code, or point the agent at your repo and get a findings report.
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](#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](/how-finch-works/finch-overview) and [API reference](/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
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.
**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.
Add the server from the terminal:
```bash theme={null}
claude mcp add --transport http finch-docs https://developer.tryfinch.com/mcp
```
Confirm it connected:
```bash theme={null}
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.
1. Go to [claude.ai/settings/connectors](https://claude.ai/settings/connectors).
2. Click **Add custom connector**.
3. Enter a name (for example, `Finch docs`) and the URL `https://developer.tryfinch.com/mcp`.
4. Click **Add**.
5. 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.
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](https://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](/developer-resources/Finch-MCP-Server).** Finch has two separate MCP servers with similar names:
| | Finch documentation MCP | [Finch MCP Server](/developer-resources/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
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:
```bash theme={null}
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](#prerequisites)). 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](#audit-an-existing-integration) below.
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.
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.
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.
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](https://developer.tryfinch.com/.well-known/agent-skills/finch-integration-backend/SKILL.md) and [frontend](https://developer.tryfinch.com/.well-known/agent-skills/finch-integration-frontend/SKILL.md) 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](/implementation-guide/go-live-checklist) and [API reference](/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
How Finch Connect sessions and the embedded and redirect flows work.
Endpoint details, field definitions, and response shapes to verify generated code.
What happens when a connection breaks and how to recover it.
Test your integration end-to-end before going to Production.