release: 9.1.1 (#645)

* chore(internal): cache fetch instruction calls in MCP server

* fix(mcp): initialize SDK lazily to avoid failing the connection on init errors

* chore: update mock server docs

* chore(mcp): correctly update version in sync with sdk

* fix(docs/contributing): correct pnpm link command

* chore(internal): upgrade @modelcontextprotocol/sdk and hono

* release: 9.1.1

---------

Co-authored-by: stainless-app[bot] <142633134+stainless-app[bot]@users.noreply.github.com>

Author: stainless-app[bot]

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "9.1.0"
+  ".": "9.1.1"
 }

CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 9.1.1 (2026-02-23)
+
+Full Changelog: [v9.1.0...v9.1.1](https://github.com/Finch-API/finch-api-node/compare/v9.1.0...v9.1.1)
+
+### Bug Fixes
+
+* **docs/contributing:** correct pnpm link command ([fbc6228](https://github.com/Finch-API/finch-api-node/commit/fbc622849196606ea0610d656d80d9906b674c50))
+* **mcp:** initialize SDK lazily to avoid failing the connection on init errors ([b8baaa7](https://github.com/Finch-API/finch-api-node/commit/b8baaa724f8ecd0f8302642f43794ebe8d8f65f0))
+
+
+### Chores
+
+* **internal:** cache fetch instruction calls in MCP server ([3949456](https://github.com/Finch-API/finch-api-node/commit/3949456cc64a6d002468cf4094726a0149361373))
+* **internal:** upgrade @modelcontextprotocol/sdk and hono ([df73805](https://github.com/Finch-API/finch-api-node/commit/df73805ff5245a55778bf67b3d19c7df3265da91))
+* **mcp:** correctly update version in sync with sdk ([d0c7741](https://github.com/Finch-API/finch-api-node/commit/d0c7741ce567161f542c2ef795ee8a7965e7b069))
+* update mock server docs ([5934a67](https://github.com/Finch-API/finch-api-node/commit/5934a6731510047f2829f0e7fa412d387f8c3fdd))
+
 ## 9.1.0 (2026-02-17)
 
 Full Changelog: [v9.0.0...v9.1.0](https://github.com/Finch-API/finch-api-node/compare/v9.0.0...v9.1.0)

CONTRIBUTING.md

@@ -60,15 +60,15 @@ $ yarn link @tryfinch/finch-api
 # With pnpm
 $ pnpm link --global
 $ cd ../my-package
-$ pnpm link -—global @tryfinch/finch-api
+$ pnpm link --global @tryfinch/finch-api
 ```
 
 ## Running tests
 
 Most tests require you to [set up a mock server](https://github.com/stoplightio/prism) against the OpenAPI spec to run the tests.
 
 ```sh
-$ npx prism mock path/to/your/openapi.yml
+$ ./scripts/mock
 ```
 
 ```sh

package.json

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

packages/mcp-server/manifest.json

@@ -1,7 +1,7 @@
 {
   "dxt_version": "0.2",
   "name": "@tryfinch/finch-api-mcp",
-  "version": "6.37.0",
+  "version": "9.1.1",
   "description": "The official MCP Server for the Finch API",
   "author": {
     "name": "Finch",
@@ -18,7 +18,9 @@
     "entry_point": "index.js",
     "mcp_config": {
       "command": "node",
-      "args": ["${__dirname}/index.js"],
+      "args": [
+        "${__dirname}/index.js"
+      ],
       "env": {
         "FINCH_ACCESS_TOKEN": "${user_config.FINCH_ACCESS_TOKEN}",
         "FINCH_CLIENT_ID": "${user_config.FINCH_CLIENT_ID}",
@@ -60,5 +62,7 @@
       "node": ">=18.0.0"
     }
   },
-  "keywords": ["api"]
+  "keywords": [
+    "api"
+  ]
 }

packages/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tryfinch/finch-api-mcp",
-  "version": "9.1.0",
+  "version": "9.1.1",
   "description": "The official MCP Server for the Finch API",
   "author": "Finch <founders@tryfinch.com>",
   "types": "dist/index.d.ts",
@@ -32,7 +32,7 @@
   "dependencies": {
     "@tryfinch/finch-api": "file:../../dist/",
     "@cloudflare/cabidela": "^0.2.4",
-    "@modelcontextprotocol/sdk": "^1.25.2",
+    "@modelcontextprotocol/sdk": "^1.26.0",
     "@valtown/deno-http-worker": "^0.0.21",
     "cookie-parser": "^1.4.6",
     "cors": "^2.8.5",

packages/mcp-server/src/http.ts

@@ -24,28 +24,17 @@ const newServer = async ({
   const stainlessApiKey = getStainlessApiKey(req, mcpOptions);
   const server = await newMcpServer(stainlessApiKey);
 
-  try {
-    const authOptions = parseClientAuthHeaders(req, false);
+  const authOptions = parseClientAuthHeaders(req, false);
 
-    await initMcpServer({
-      server: server,
-      mcpOptions: mcpOptions,
-      clientOptions: {
-        ...clientOptions,
-        ...authOptions,
-      },
-      stainlessApiKey: stainlessApiKey,
-    });
-  } catch (error) {
-    res.status(401).json({
-      jsonrpc: '2.0',
-      error: {
-        code: -32000,
-        message: `Unauthorized: ${error instanceof Error ? error.message : error}`,
-      },
-    });
-    return null;
-  }
+  await initMcpServer({
+    server: server,
+    mcpOptions: mcpOptions,
+    clientOptions: {
+      ...clientOptions,
+      ...authOptions,
+    },
+    stainlessApiKey: stainlessApiKey,
+  });
 
   return server;
 };

packages/mcp-server/src/index.ts

@@ -24,7 +24,7 @@ async function main() {
       await launchStreamableHTTPServer({
         mcpOptions: options,
         debug: options.debug,
-        port: options.port ?? options.socket,
+        port: options.socket ?? options.port,
       });
       break;
   }

packages/mcp-server/src/instructions.ts

@@ -0,0 +1,74 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { readEnv } from './util';
+
+const INSTRUCTIONS_CACHE_TTL_MS = 15 * 60 * 1000; // 15 minutes
+
+interface InstructionsCacheEntry {
+  fetchedInstructions: string;
+  fetchedAt: number;
+}
+
+const instructionsCache = new Map<string, InstructionsCacheEntry>();
+
+// Periodically evict stale entries so the cache doesn't grow unboundedly.
+const _cacheCleanupInterval = setInterval(() => {
+  const now = Date.now();
+  for (const [key, entry] of instructionsCache) {
+    if (now - entry.fetchedAt > INSTRUCTIONS_CACHE_TTL_MS) {
+      instructionsCache.delete(key);
+    }
+  }
+}, INSTRUCTIONS_CACHE_TTL_MS);
+
+// Don't keep the process alive just for cleanup.
+_cacheCleanupInterval.unref();
+
+export async function getInstructions(stainlessApiKey: string | undefined): Promise<string> {
+  const cacheKey = stainlessApiKey ?? '';
+  const cached = instructionsCache.get(cacheKey);
+
+  if (cached && Date.now() - cached.fetchedAt <= INSTRUCTIONS_CACHE_TTL_MS) {
+    return cached.fetchedInstructions;
+  }
+
+  const fetchedInstructions = await fetchLatestInstructions(stainlessApiKey);
+  instructionsCache.set(cacheKey, { fetchedInstructions, fetchedAt: Date.now() });
+  return fetchedInstructions;
+}
+
+async function fetchLatestInstructions(stainlessApiKey: string | undefined): Promise<string> {
+  // Setting the stainless API key is optional, but may be required
+  // to authenticate requests to the Stainless API.
+  const response = await fetch(
+    readEnv('CODE_MODE_INSTRUCTIONS_URL') ?? 'https://api.stainless.com/api/ai/instructions/finch',
+    {
+      method: 'GET',
+      headers: { ...(stainlessApiKey && { Authorization: stainlessApiKey }) },
+    },
+  );
+
+  let instructions: string | undefined;
+  if (!response.ok) {
+    console.warn(
+      'Warning: failed to retrieve MCP server instructions. Proceeding with default instructions...',
+    );
+
+    instructions = `
+      This is the finch MCP server. You will use Code Mode to help the user perform
+      actions. You can use search_docs tool to learn about how to take action with this server. Then,
+      you will write TypeScript code using the execute tool take action. It is CRITICAL that you be
+      thoughtful and deliberate when executing code. Always try to entirely solve the problem in code
+      block: it can be as long as you need to get the job done!
+    `;
+  }
+
+  instructions ??= ((await response.json()) as { instructions: string }).instructions;
+  instructions = `
+    If needed, you can get the current time by executing Date.now().
+
+    ${instructions}
+  `;
+
+  return instructions;
+}

packages/mcp-server/src/server.ts

@@ -11,52 +11,17 @@ import { ClientOptions } from '@tryfinch/finch-api';
 import Finch from '@tryfinch/finch-api';
 import { codeTool } from './code-tool';
 import docsSearchTool from './docs-search-tool';
+import { getInstructions } from './instructions';
 import { McpOptions } from './options';
 import { blockedMethodsForCodeTool } from './methods';
 import { HandlerFunction, McpRequestContext, ToolCallResult, McpTool } from './types';
 import { readEnv } from './util';
 
-async function getInstructions(stainlessApiKey: string | undefined): Promise<string> {
-  // Setting the stainless API key is optional, but may be required
-  // to authenticate requests to the Stainless API.
-  const response = await fetch(
-    readEnv('CODE_MODE_INSTRUCTIONS_URL') ?? 'https://api.stainless.com/api/ai/instructions/finch',
-    {
-      method: 'GET',
-      headers: { ...(stainlessApiKey && { Authorization: stainlessApiKey }) },
-    },
-  );
-
-  let instructions: string | undefined;
-  if (!response.ok) {
-    console.warn(
-      'Warning: failed to retrieve MCP server instructions. Proceeding with default instructions...',
-    );
-
-    instructions = `
-      This is the finch MCP server. You will use Code Mode to help the user perform
-      actions. You can use search_docs tool to learn about how to take action with this server. Then,
-      you will write TypeScript code using the execute tool take action. It is CRITICAL that you be
-      thoughtful and deliberate when executing code. Always try to entirely solve the problem in code
-      block: it can be as long as you need to get the job done!
-    `;
-  }
-
-  instructions ??= ((await response.json()) as { instructions: string }).instructions;
-  instructions = `
-    The current time in Unix timestamps is ${Date.now()}.
-
-    ${instructions}
-  `;
-
-  return instructions;
-}
-
 export const newMcpServer = async (stainlessApiKey: string | undefined) =>
   new McpServer(
     {
       name: 'tryfinch_finch_api_api',
-      version: '9.1.0',
+      version: '9.1.1',
     },
     {
       instructions: await getInstructions(stainlessApiKey),
@@ -91,15 +56,33 @@ export async function initMcpServer(params: {
     error: logAtLevel('error'),
   };
 
-  let client = new Finch({
-    ...{ accessToken: readEnv('FINCH_ACCESS_TOKEN') },
-    logger,
-    ...params.clientOptions,
-    defaultHeaders: {
-      ...params.clientOptions?.defaultHeaders,
-      'X-Stainless-MCP': 'true',
-    },
-  });
+  let _client: Finch | undefined;
+  let _clientError: Error | undefined;
+  let _logLevel: 'debug' | 'info' | 'warn' | 'error' | 'off' | undefined;
+
+  const getClient = (): Finch => {
+    if (_clientError) throw _clientError;
+    if (!_client) {
+      try {
+        _client = new Finch({
+          ...{ accessToken: readEnv('FINCH_ACCESS_TOKEN') },
+          logger,
+          ...params.clientOptions,
+          defaultHeaders: {
+            ...params.clientOptions?.defaultHeaders,
+            'X-Stainless-MCP': 'true',
+          },
+        });
+        if (_logLevel) {
+          _client = _client.withOptions({ logLevel: _logLevel });
+        }
+      } catch (e) {
+        _clientError = e instanceof Error ? e : new Error(String(e));
+        throw _clientError;
+      }
+    }
+    return _client;
+  };
 
   const providedTools = selectTools(params.mcpOptions);
   const toolMap = Object.fromEntries(providedTools.map((mcpTool) => [mcpTool.tool.name, mcpTool]));
@@ -117,6 +100,21 @@ export async function initMcpServer(params: {
       throw new Error(`Unknown tool: ${name}`);
     }
 
+    let client: Finch;
+    try {
+      client = getClient();
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `Failed to initialize client: ${error instanceof Error ? error.message : String(error)}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+
     return executeHandler({
       handler: mcpTool.handler,
       reqContext: {
@@ -129,24 +127,29 @@ export async function initMcpServer(params: {
 
   server.setRequestHandler(SetLevelRequestSchema, async (request) => {
     const { level } = request.params;
+    let logLevel: 'debug' | 'info' | 'warn' | 'error' | 'off';
     switch (level) {
       case 'debug':
-        client = client.withOptions({ logLevel: 'debug' });
+        logLevel = 'debug';
         break;
       case 'info':
-        client = client.withOptions({ logLevel: 'info' });
+        logLevel = 'info';
         break;
       case 'notice':
       case 'warning':
-        client = client.withOptions({ logLevel: 'warn' });
+        logLevel = 'warn';
         break;
       case 'error':
-        client = client.withOptions({ logLevel: 'error' });
+        logLevel = 'error';
         break;
       default:
-        client = client.withOptions({ logLevel: 'off' });
+        logLevel = 'off';
         break;
     }
+    _logLevel = logLevel;
+    if (_client) {
+      _client = _client.withOptions({ logLevel });
+    }
     return {};
   });
 }