release: 8.1.0

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "8.0.0"
+  ".": "8.1.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 46
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/finch%2Ffinch-f81c5824a9002c980fc0d66c4d52e6cbd8baf7678f5e0f2215909357cff6f82c.yml
-openapi_spec_hash: 7714062cac3bb5597b8571172775bc92
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/finch%2Ffinch-ded87cb73affcaff9cf779d9cfd119a4026cfc1757b39be95d933edea48a0328.yml
+openapi_spec_hash: 0e6394b222fc68d7607114e70b72d23e
 config_hash: 0892e2e0eeb0343a022afa62e9080dd1

CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 8.1.0 (2026-01-06)
+
+Full Changelog: [v8.0.0...v8.1.0](https://github.com/Finch-API/finch-api-node/compare/v8.0.0...v8.1.0)
+
+### Features
+
+* **api:** api update ([8e97806](https://github.com/Finch-API/finch-api-node/commit/8e97806ff9a9dc8abf9d96c6334f716375764249))
+
+
+### Bug Fixes
+
+* **mcp:** correct code tool api output types ([1a412ec](https://github.com/Finch-API/finch-api-node/commit/1a412ec1f585e4be7252c9d15d119a519986c8c1))
+
+
+### Chores
+
+* break long lines in snippets into multiline ([166f620](https://github.com/Finch-API/finch-api-node/commit/166f6206c0b0b7ee088314dd8351d69b78f87a28))
+* **internal:** codegen related update ([d9eeb4b](https://github.com/Finch-API/finch-api-node/commit/d9eeb4b1d9388efcfcefd05ce2c27b4752f374d1))
+
+
+### Documentation
+
+* prominently feature MCP server setup in root SDK readmes ([72c2bdd](https://github.com/Finch-API/finch-api-node/commit/72c2bdd4467301c754ec1c3393308468edb8fb29))
+
 ## 8.0.0 (2025-12-18)
 
 Full Changelog: [v7.0.0...v8.0.0](https://github.com/Finch-API/finch-api-node/compare/v7.0.0...v8.0.0)

LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2025 Finch
+   Copyright 2026 Finch
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

README.md

@@ -8,6 +8,15 @@ The REST API documentation can be found on [developer.tryfinch.com](https://deve
 
 It is generated with [Stainless](https://www.stainless.com/).
 
+## MCP Server
+
+Use the Finch MCP Server to enable AI assistants to interact with this API, allowing them to explore endpoints, make test requests, and use documentation to help integrate this SDK into your application.
+
+[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=%40tryfinch%2Ffinch-api-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB0cnlmaW5jaC9maW5jaC1hcGktbWNwIl19)
+[![Install in VS Code](https://img.shields.io/badge/_-Add_to_VS_Code-blue?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGZpbGw9Im5vbmUiIHZpZXdCb3g9IjAgMCA0MCA0MCI+PHBhdGggZmlsbD0iI0VFRSIgZmlsbC1ydWxlPSJldmVub2RkIiBkPSJNMzAuMjM1IDM5Ljg4NGEyLjQ5MSAyLjQ5MSAwIDAgMS0xLjc4MS0uNzNMMTIuNyAyNC43OGwtMy40NiAyLjYyNC0zLjQwNiAyLjU4MmExLjY2NSAxLjY2NSAwIDAgMS0xLjA4Mi4zMzggMS42NjQgMS42NjQgMCAwIDEtMS4wNDYtLjQzMWwtMi4yLTJhMS42NjYgMS42NjYgMCAwIDEgMC0yLjQ2M0w3LjQ1OCAyMCA0LjY3IDE3LjQ1MyAxLjUwNyAxNC41N2ExLjY2NSAxLjY2NSAwIDAgMSAwLTIuNDYzbDIuMi0yYTEuNjY1IDEuNjY1IDAgMCAxIDIuMTMtLjA5N2w2Ljg2MyA1LjIwOUwyOC40NTIuODQ0YTIuNDg4IDIuNDg4IDAgMCAxIDEuODQxLS43MjljLjM1MS4wMDkuNjk5LjA5MSAxLjAxOS4yNDVsOC4yMzYgMy45NjFhMi41IDIuNSAwIDAgMSAxLjQxNSAyLjI1M3YuMDk5LS4wNDVWMzMuMzd2LS4wNDUuMDk1YTIuNTAxIDIuNTAxIDAgMCAxLTEuNDE2IDIuMjU3bC04LjIzNSAzLjk2MWEyLjQ5MiAyLjQ5MiAwIDAgMS0xLjA3Ny4yNDZabS43MTYtMjguOTQ3LTExLjk0OCA5LjA2MiAxMS45NTIgOS4wNjUtLjAwNC0xOC4xMjdaIi8+PC9zdmc+)](https://vscode.stainless.com/mcp/%7B%22name%22%3A%22%40tryfinch%2Ffinch-api-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40tryfinch%2Ffinch-api-mcp%22%5D%7D)
+
+> Note: You may need to set environment variables in your MCP client.
+
 ## Installation
 
 ```sh
@@ -44,7 +53,8 @@ const client = new Finch({
   accessToken: 'My Access Token',
 });
 
-const [individualInDirectory]: [Finch.HRIS.IndividualInDirectory] = await client.hris.directory.list();
+const [individualInDirectory]: [Finch.HRIS.IndividualInDirectory] =
+  await client.hris.directory.list();
 ```
 
 Documentation for each method, request param, and response field are available in docstrings and will appear on hover in most modern editors.
@@ -167,7 +177,9 @@ import Finch from '@tryfinch/finch-api';
 
 const client = new Finch();
 
-const page = await client.hris.directory.list({ headers: { 'Finch-API-Version': 'My-Custom-Value' } });
+const page = await client.hris.directory.list({
+  headers: { 'Finch-API-Version': 'My-Custom-Value' },
+});
 const individualInDirectory = page.individuals[0];
 ```
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tryfinch/finch-api",
-  "version": "8.0.0",
+  "version": "8.1.0",
   "description": "The official TypeScript library for the Finch API",
   "author": "Finch <founders@tryfinch.com>",
   "types": "dist/index.d.ts",

packages/mcp-server/README.md

@@ -45,7 +45,7 @@ For clients with a configuration JSON, it might look something like this:
 If you use Cursor, you can install the MCP server by using the button below. You will need to set your environment variables
 in Cursor's `mcp.json`, which can be found in Cursor Settings > Tools & MCP > New MCP Server.
 
-[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=@tryfinch/finch-api-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB0cnlmaW5jaC9maW5jaC1hcGktbWNwIl0sImVudiI6eyJGSU5DSF9BQ0NFU1NfVE9LRU4iOiJTZXQgeW91ciBGSU5DSF9BQ0NFU1NfVE9LRU4gaGVyZS4iLCJGSU5DSF9DTElFTlRfSUQiOiJTZXQgeW91ciBGSU5DSF9DTElFTlRfSUQgaGVyZS4iLCJGSU5DSF9DTElFTlRfU0VDUkVUIjoiU2V0IHlvdXIgRklOQ0hfQ0xJRU5UX1NFQ1JFVCBoZXJlLiIsIkZJTkNIX1dFQkhPT0tfU0VDUkVUIjoiU2V0IHlvdXIgRklOQ0hfV0VCSE9PS19TRUNSRVQgaGVyZS4ifX0)
+[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=%40tryfinch%2Ffinch-api-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB0cnlmaW5jaC9maW5jaC1hcGktbWNwIl0sImVudiI6eyJGSU5DSF9BQ0NFU1NfVE9LRU4iOiJTZXQgeW91ciBGSU5DSF9BQ0NFU1NfVE9LRU4gaGVyZS4iLCJGSU5DSF9DTElFTlRfSUQiOiJTZXQgeW91ciBGSU5DSF9DTElFTlRfSUQgaGVyZS4iLCJGSU5DSF9DTElFTlRfU0VDUkVUIjoiU2V0IHlvdXIgRklOQ0hfQ0xJRU5UX1NFQ1JFVCBoZXJlLiIsIkZJTkNIX1dFQkhPT0tfU0VDUkVUIjoiU2V0IHlvdXIgRklOQ0hfV0VCSE9PS19TRUNSRVQgaGVyZS4ifX0)
 
 ### VS Code
 
@@ -60,7 +60,7 @@ If you use Claude Code, you can install the MCP server by running the command be
 environment variables in Claude Code's `.claude.json`, which can be found in your home directory.
 
 ```
-claude mcp add --transport stdio tryfinch_finch_api_api --env FINCH_ACCESS_TOKEN="Your FINCH_ACCESS_TOKEN here." FINCH_CLIENT_ID="Your FINCH_CLIENT_ID here." FINCH_CLIENT_SECRET="Your FINCH_CLIENT_SECRET here." FINCH_WEBHOOK_SECRET="Your FINCH_WEBHOOK_SECRET here." -- npx -y @tryfinch/finch-api-mcp
+claude mcp add tryfinch_finch_api_mcp_api --env FINCH_ACCESS_TOKEN="Your FINCH_ACCESS_TOKEN here." FINCH_CLIENT_ID="Your FINCH_CLIENT_ID here." FINCH_CLIENT_SECRET="Your FINCH_CLIENT_SECRET here." FINCH_WEBHOOK_SECRET="Your FINCH_WEBHOOK_SECRET here." -- npx -y @tryfinch/finch-api-mcp
 ```
 
 ## Code Mode

packages/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tryfinch/finch-api-mcp",
-  "version": "8.0.0",
+  "version": "8.1.0",
   "description": "The official MCP Server for the Finch API",
   "author": "Finch <founders@tryfinch.com>",
   "types": "dist/index.d.ts",

packages/mcp-server/src/code-tool-types.ts

@@ -3,16 +3,13 @@
 import { ClientOptions } from '@tryfinch/finch-api';
 
 export type WorkerInput = {
-  opts: ClientOptions;
+  project_name: string;
   code: string;
+  client_opts: ClientOptions;
 };
-export type WorkerSuccess = {
+export type WorkerOutput = {
+  is_error: boolean;
   result: unknown | null;
-  logLines: string[];
-  errLines: string[];
-};
-export type WorkerError = {
-  message: string | undefined;
-  logLines: string[];
-  errLines: string[];
+  log_lines: string[];
+  err_lines: string[];
 };

packages/mcp-server/src/code-tool.ts

@@ -1,9 +1,9 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { McpTool, Metadata, ToolCallResult, asTextContentResult } from './types';
+import { McpTool, Metadata, ToolCallResult, asErrorResult, asTextContentResult } from './types';
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
 import { readEnv } from './server';
-import { WorkerSuccess } from './code-tool-types';
+import { WorkerInput, WorkerOutput } from './code-tool-types';
 /**
  * A tool that runs code against a copy of the SDK.
  *
@@ -45,9 +45,9 @@ export function codeTool(): McpTool {
       },
       body: JSON.stringify({
         project_name: 'finch',
-        client_opts: { accessToken: readEnv('FINCH_ACCESS_TOKEN') },
         code,
-      }),
+        client_opts: { accessToken: readEnv('FINCH_ACCESS_TOKEN') },
+      } satisfies WorkerInput),
     });
 
     if (!res.ok) {
@@ -58,7 +58,17 @@ export function codeTool(): McpTool {
       );
     }
 
-    return asTextContentResult((await res.json()) as WorkerSuccess);
+    const { is_error, result, log_lines, err_lines } = (await res.json()) as WorkerOutput;
+    const hasLogs = log_lines.length > 0 || err_lines.length > 0;
+    const output = {
+      result,
+      ...(log_lines.length > 0 && { log_lines }),
+      ...(err_lines.length > 0 && { err_lines }),
+    };
+    if (is_error) {
+      return asErrorResult(typeof result === 'string' && !hasLogs ? result : JSON.stringify(output, null, 2));
+    }
+    return asTextContentResult(output);
   };
 
   return { metadata, tool, handler };

packages/mcp-server/src/server.ts

@@ -21,7 +21,7 @@ export const newMcpServer = () =>
   new McpServer(
     {
       name: 'tryfinch_finch_api_api',
-      version: '8.0.0',
+      version: '8.1.0',
     },
     { capabilities: { tools: {}, logging: {} } },
   );

src/resources/sandbox/connections/accounts.ts

@@ -64,6 +64,11 @@ export interface AccountCreateResponse {
    */
   connection_id: string;
 
+  /**
+   * The ID of the entity for this connection
+   */
+  entity_id: string;
+
   products: Array<string>;
 
   /**
@@ -87,17 +92,22 @@ export interface AccountUpdateResponse {
    */
   company_id: string;
 
-  products: Array<string>;
+  /**
+   * The ID of the new connection
+   */
+  connection_id: string;
 
   /**
-   * The ID of the provider associated with the `access_token`
+   * The ID of the entity whose status was updated
    */
-  provider_id: string;
+  entity_id: string;
+
+  products: Array<string>;
 
   /**
-   * The ID of the new connection
+   * The ID of the provider associated with the `access_token`
    */
-  connection_id?: string;
+  provider_id: string;
 }
 
 export interface AccountCreateParams {

src/resources/sandbox/connections/connections.ts

@@ -52,6 +52,11 @@ export interface ConnectionCreateResponse {
    */
   connection_id: string;
 
+  /**
+   * The ID of the entity for this connection
+   */
+  entity_id: string;
+
   products: Array<string>;
 
   /**

src/version.ts

@@ -1 +1 @@
-export const VERSION = '8.0.0'; // x-release-please-version
+export const VERSION = '8.1.0'; // x-release-please-version

tests/api-resources/hris/benefits/individuals.test.ts

@@ -32,7 +32,11 @@ describe('resource individuals', () => {
                 annual_contribution_limit: 'individual',
                 annual_maximum: null,
                 catch_up: true,
-                company_contribution: { amount: 0, tiers: [{ match: 0, threshold: 0 }], type: 'fixed' },
+                company_contribution: {
+                  amount: 0,
+                  tiers: [{ match: 0, threshold: 0 }],
+                  type: 'fixed',
+                },
                 effective_date: '2019-12-27',
                 employee_deduction: { amount: 10000, type: 'fixed' },
               },

tests/api-resources/hris/company/pay-statement-item/rules.test.ts

@@ -26,7 +26,13 @@ describe('resource rules', () => {
         {
           entity_ids: ['550e8400-e29b-41d4-a716-446655440000'],
           attributes: { metadata: { foo: 'bar' } },
-          conditions: [{ field: 'field', operator: 'equals', value: 'value' }],
+          conditions: [
+            {
+              field: 'field',
+              operator: 'equals',
+              value: 'value',
+            },
+          ],
           effective_end_date: 'effective_end_date',
           effective_start_date: 'effective_start_date',
           entity_type: 'pay_statement_item',
@@ -52,7 +58,10 @@ describe('resource rules', () => {
     await expect(
       client.hris.company.payStatementItem.rules.update(
         'rule_id',
-        { entity_ids: ['550e8400-e29b-41d4-a716-446655440000'], optionalProperty: {} },
+        {
+          entity_ids: ['550e8400-e29b-41d4-a716-446655440000'],
+          optionalProperty: {},
+        },
         { path: '/_stainless_unknown_path' },
       ),
     ).rejects.toThrow(Finch.NotFoundError);

tests/api-resources/hris/directory.test.ts

@@ -23,7 +23,11 @@ describe('resource directory', () => {
     // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error
     await expect(
       client.hris.directory.list(
-        { entity_ids: ['550e8400-e29b-41d4-a716-446655440000'], limit: 0, offset: 0 },
+        {
+          entity_ids: ['550e8400-e29b-41d4-a716-446655440000'],
+          limit: 0,
+          offset: 0,
+        },
         { path: '/_stainless_unknown_path' },
       ),
     ).rejects.toThrow(Finch.NotFoundError);
@@ -44,7 +48,11 @@ describe('resource directory', () => {
     // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error
     await expect(
       client.hris.directory.listIndividuals(
-        { entity_ids: ['550e8400-e29b-41d4-a716-446655440000'], limit: 0, offset: 0 },
+        {
+          entity_ids: ['550e8400-e29b-41d4-a716-446655440000'],
+          limit: 0,
+          offset: 0,
+        },
         { path: '/_stainless_unknown_path' },
       ),
     ).rejects.toThrow(Finch.NotFoundError);

tests/api-resources/hris/pay-statements.test.ts

@@ -23,7 +23,13 @@ describe('resource payStatements', () => {
 
   test('retrieveMany: required and optional params', async () => {
     const response = await client.hris.payStatements.retrieveMany({
-      requests: [{ payment_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', limit: 50, offset: 0 }],
+      requests: [
+        {
+          payment_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+          limit: 50,
+          offset: 0,
+        },
+      ],
       entity_ids: ['550e8400-e29b-41d4-a716-446655440000'],
     });
   });

tests/api-resources/sandbox/company.test.ts

@@ -48,7 +48,12 @@ describe('resource company', () => {
           routing_number: 'routing_number',
         },
       ],
-      departments: [{ name: 'name', parent: { name: 'name' } }],
+      departments: [
+        {
+          name: 'name',
+          parent: { name: 'name' },
+        },
+      ],
       ein: 'ein',
       entity: { subtype: 's_corporation', type: 'llc' },
       legal_name: 'legal_name',

tests/api-resources/sandbox/directory.test.ts

@@ -27,7 +27,12 @@ describe('resource directory', () => {
           body: [
             {
               class_code: 'class_code',
-              custom_fields: [{ name: 'name', value: {} }],
+              custom_fields: [
+                {
+                  name: 'name',
+                  value: {},
+                },
+              ],
               department: { name: 'name' },
               dob: 'dob',
               emails: [{ data: 'data', type: 'work' }],
@@ -38,9 +43,19 @@ describe('resource directory', () => {
               ethnicity: 'asian',
               first_name: 'first_name',
               gender: 'female',
-              income: { amount: 0, currency: 'currency', effective_date: '2019-12-27', unit: 'yearly' },
+              income: {
+                amount: 0,
+                currency: 'currency',
+                effective_date: '2019-12-27',
+                unit: 'yearly',
+              },
               income_history: [
-                { amount: 0, currency: 'currency', effective_date: '2019-12-27', unit: 'yearly' },
+                {
+                  amount: 0,
+                  currency: 'currency',
+                  effective_date: '2019-12-27',
+                  unit: 'yearly',
+                },
               ],
               is_active: true,
               last_name: 'last_name',