hyperspell · stainless-app · Jan 17, 2026 · Jan 23, 2026 · Jan 24, 2026 · Jan 24, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -19,7 +19,7 @@ jobs:
     runs-on: ${{ github.repository == 'stainless-sdks/hyperspell-typescript' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
     if: github.event_name == 'push' || github.event.pull_request.head.repo.fork
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Set up Node
         uses: actions/setup-node@v4
@@ -41,7 +41,7 @@ jobs:
       contents: read
       id-token: write
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Set up Node
         uses: actions/setup-node@v4
@@ -57,7 +57,7 @@ jobs:
       - name: Get GitHub OIDC Token
         if: github.repository == 'stainless-sdks/hyperspell-typescript'
         id: github-oidc
-        uses: actions/github-script@v6
+        uses: actions/github-script@v8
         with:
           script: core.setOutput('github_token', await core.getIDToken());
 
@@ -83,7 +83,7 @@ jobs:
     runs-on: ${{ github.repository == 'stainless-sdks/hyperspell-typescript' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
     if: github.event_name == 'push' || github.event.pull_request.head.repo.fork
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Set up Node
         uses: actions/setup-node@v4

diff --git a/.github/workflows/publish-npm.yml b/.github/workflows/publish-npm.yml
@@ -20,7 +20,7 @@ jobs:
       contents: write
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Set up Node
         uses: actions/setup-node@v3

diff --git a/.github/workflows/release-doctor.yml b/.github/workflows/release-doctor.yml
@@ -12,10 +12,11 @@ jobs:
     if: github.repository == 'hyperspell/node-sdk' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch' || startsWith(github.head_ref, 'release-please') || github.head_ref == 'next')
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Check release environment
         run: |
           bash ./bin/check-release-environment
         env:
           NPM_TOKEN: ${{ secrets.HYPERSPELL_NPM_TOKEN || secrets.NPM_TOKEN }}
+
diff --git a/.release-please-manifest.json b/.release-please-manifest.json
@@ -1,3 +1,3 @@
 {
-  ".": "0.30.0"
+  ".": "0.31.0"
 }
diff --git a/.stats.yml b/.stats.yml
@@ -1,4 +1,4 @@
 configured_endpoints: 23
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/hyperspell%2Fhyperspell-a73c73c4848db6cc0b836219f2ace7bc9f6b4611d36f9daa2158f8bd5a7d0864.yml
-openapi_spec_hash: 4ef2aeca3ffe2c6e6fbca0770a69c6fb
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/hyperspell%2Fhyperspell-34d6c3c2efa9b9b88d95ff49ff64f45440720b14a046edf3fac953d6eb0d13a1.yml
+openapi_spec_hash: 80ce00b9f30af244e0a331c3430ed5e4
 config_hash: bd77d0b7029518c697756456d6854f07
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.31.0 (2026-02-05)
+
+Full Changelog: [v0.30.0...v0.31.0](https://github.com/hyperspell/node-sdk/compare/v0.30.0...v0.31.0)
+
+### Features
+
+* **api:** api update ([a0df1be](https://github.com/hyperspell/node-sdk/commit/a0df1be8d411efda7d9c06ba663e64a72e308de0))
+* **mcp:** add initial server instructions ([581fb5e](https://github.com/hyperspell/node-sdk/commit/581fb5e5aaf49b32facacc9adc28ca3797dbd117))
+
+
+### Bug Fixes
+
+* **client:** avoid memory leak with abort signals ([5b29273](https://github.com/hyperspell/node-sdk/commit/5b2927352218310b6e3a3ec4c950dc4e8d15cbf9))
+* **docs:** fix mcp installation instructions for remote servers ([d4c938b](https://github.com/hyperspell/node-sdk/commit/d4c938b9490184c9de54a36e0635b3b7b24e8aeb))
+* **mcp:** allow falling back for required env variables ([6054c99](https://github.com/hyperspell/node-sdk/commit/6054c99672bb1399b5db94931d20979394ab9f60))
+
+
+### Chores
+
+* **ci:** upgrade `actions/github-script` ([090b5c1](https://github.com/hyperspell/node-sdk/commit/090b5c1a28992d318a2904cabe73556f61e76edf))
+* **client:** do not parse responses with empty content-length ([b7dde77](https://github.com/hyperspell/node-sdk/commit/b7dde774dee58aaf475d07c08d8792753c09fc85))
+* **client:** restructure abort controller binding ([ecf2c20](https://github.com/hyperspell/node-sdk/commit/ecf2c20a9d7aa7cfb1d5734a14ba75a4f5ebe0e8))
+* **internal:** codegen related update ([1c6bacc](https://github.com/hyperspell/node-sdk/commit/1c6bacc1daa1c93198ea61ec75325cf7dc1e7950))
+* **internal:** refactor flag parsing for MCP servers and add debug flag ([051f042](https://github.com/hyperspell/node-sdk/commit/051f0428d7d30eadf1deb83214757e98e7cb86c0))
+* **internal:** support oauth authorization code flow for MCP servers ([027ce2c](https://github.com/hyperspell/node-sdk/commit/027ce2cd7d3164f49134235a10446ed1e838d17f))
+* **internal:** update `actions/checkout` version ([954ce30](https://github.com/hyperspell/node-sdk/commit/954ce3099c58efa8c5071b6830dad969401a050a))
+* **internal:** update lock file ([e192aa3](https://github.com/hyperspell/node-sdk/commit/e192aa3c9ac16fb38cad2e56f2e46498eb11f8ee))
+* **mcp:** up tsconfig lib version to es2022 ([db052dc](https://github.com/hyperspell/node-sdk/commit/db052dcd1a475b54cb7c302df23bcfaa73c969d0))
+
 ## 0.30.0 (2026-01-16)
 
 Full Changelog: [v0.29.0...v0.30.0](https://github.com/hyperspell/node-sdk/compare/v0.29.0...v0.30.0)

diff --git a/MIGRATION.md b/MIGRATION.md
@@ -234,8 +234,8 @@ The `for await` syntax **is not affected**. This still works as-is:
 
 ```ts
 // Automatically fetches more pages as needed.
-for await (const memory of client.memories.list()) {
-  console.log(memory);
+for await (const memoryListResponse of client.memories.list()) {
+  console.log(memoryListResponse);
 }
 ```
 
@@ -257,10 +257,10 @@ Page classes for individual methods are now type aliases:
 
 ```ts
 // Before
-export class MemoriesCursorPage extends CursorPage<Memory> {}
+export class MemoryListResponsesCursorPage extends CursorPage<MemoryListResponse> {}
 
 // After
-export type MemoriesCursorPage = CursorPage<Memory>;
+export type MemoryListResponsesCursorPage = CursorPage<MemoryListResponse>;
 ```
 
 If you were importing these classes at runtime, you'll need to switch to importing the base class or only import them at the type-level.

diff --git a/README.md b/README.md
@@ -12,8 +12,8 @@ It is generated with [Stainless](https://www.stainless.com/).
 
 Use the Hyperspell 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=hyperspell-mcp&config=eyJuYW1lIjoiaHlwZXJzcGVsbC1tY3AiLCJ0cmFuc3BvcnQiOiJzc2UiLCJ1cmwiOiJodHRwczovL2h5cGVyc3BlbGwuc3RsbWNwLmNvbS9zc2UifQ)
-[![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%22hyperspell-mcp%22%2C%22type%22%3A%22sse%22%2C%22url%22%3A%22https%3A%2F%2Fhyperspell.stlmcp.com%2Fsse%22%7D)
+[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=hyperspell-mcp&config=eyJuYW1lIjoiaHlwZXJzcGVsbC1tY3AiLCJ0cmFuc3BvcnQiOiJodHRwIiwidXJsIjoiaHR0cHM6Ly9oeXBlcnNwZWxsLnN0bG1jcC5jb20iLCJoZWFkZXJzIjp7IngtaHlwZXJzcGVsbC1hcGkta2V5IjoiTXkgQVBJIEtleSIsIlgtQXMtVXNlciI6Ik15IFVzZXIgSUQifX0)
+[![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%22hyperspell-mcp%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fhyperspell.stlmcp.com%22%2C%22headers%22%3A%7B%22x-hyperspell-api-key%22%3A%22My%20API%20Key%22%2C%22X-As-User%22%3A%22My%20User%20ID%22%7D%7D)
 
 > Note: You may need to set environment variables in your MCP client.
 
@@ -167,22 +167,22 @@ List methods in the Hyperspell API are paginated.
 You can use the `for await … of` syntax to iterate through items across all pages:
 
 ```ts
-async function fetchAllMemories(params) {
-  const allMemories = [];
+async function fetchAllMemoryListResponses(params) {
+  const allMemoryListResponses = [];
   // Automatically fetches more pages as needed.
-  for await (const memory of client.memories.list({ collection: 'REPLACE_ME' })) {
-    allMemories.push(memory);
+  for await (const memoryListResponse of client.memories.list({ collection: 'REPLACE_ME' })) {
+    allMemoryListResponses.push(memoryListResponse);
   }
-  return allMemories;
+  return allMemoryListResponses;
 }
 ```
 
 Alternatively, you can request a single page at a time:
 
 ```ts
 let page = await client.memories.list({ collection: 'REPLACE_ME' });
-for (const memory of page.items) {
-  console.log(memory);
+for (const memoryListResponse of page.items) {
+  console.log(memoryListResponse);
 }
 
 // Convenience methods are provided for manually paginating:

diff --git a/api.md b/api.md
@@ -62,20 +62,21 @@ Methods:
 
 Types:
 
-- <code><a href="./src/resources/memories.ts">Memory</a></code>
 - <code><a href="./src/resources/memories.ts">MemoryStatus</a></code>
+- <code><a href="./src/resources/memories.ts">MemoryListResponse</a></code>
 - <code><a href="./src/resources/memories.ts">MemoryDeleteResponse</a></code>
 - <code><a href="./src/resources/memories.ts">MemoryAddBulkResponse</a></code>
+- <code><a href="./src/resources/memories.ts">MemoryGetResponse</a></code>
 - <code><a href="./src/resources/memories.ts">MemoryStatusResponse</a></code>
 
 Methods:
 
 - <code title="post /memories/update/{source}/{resource_id}">client.memories.<a href="./src/resources/memories.ts">update</a>(resourceID, { ...params }) -> MemoryStatus</code>
-- <code title="get /memories/list">client.memories.<a href="./src/resources/memories.ts">list</a>({ ...params }) -> MemoriesCursorPage</code>
+- <code title="get /memories/list">client.memories.<a href="./src/resources/memories.ts">list</a>({ ...params }) -> MemoryListResponsesCursorPage</code>
 - <code title="delete /memories/delete/{source}/{resource_id}">client.memories.<a href="./src/resources/memories.ts">delete</a>(resourceID, { ...params }) -> MemoryDeleteResponse</code>
 - <code title="post /memories/add">client.memories.<a href="./src/resources/memories.ts">add</a>({ ...params }) -> MemoryStatus</code>
 - <code title="post /memories/add/bulk">client.memories.<a href="./src/resources/memories.ts">addBulk</a>({ ...params }) -> MemoryAddBulkResponse</code>
-- <code title="get /memories/get/{source}/{resource_id}">client.memories.<a href="./src/resources/memories.ts">get</a>(resourceID, { ...params }) -> Memory</code>
+- <code title="get /memories/get/{source}/{resource_id}">client.memories.<a href="./src/resources/memories.ts">get</a>(resourceID, { ...params }) -> MemoryGetResponse</code>
 - <code title="post /memories/query">client.memories.<a href="./src/resources/memories.ts">search</a>({ ...params }) -> QueryResult</code>
 - <code title="get /memories/status">client.memories.<a href="./src/resources/memories.ts">status</a>() -> MemoryStatusResponse</code>
 - <code title="post /memories/upload">client.memories.<a href="./src/resources/memories.ts">upload</a>({ ...params }) -> MemoryStatus</code>

diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "hyperspell",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "The official TypeScript library for the Hyperspell API",
   "author": "Hyperspell <hello@hyperspell.com>",
   "types": "dist/index.d.ts",

diff --git a/packages/mcp-server/README.md b/packages/mcp-server/README.md
@@ -41,22 +41,22 @@ 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=hyperspell-mcp&config=eyJuYW1lIjoiaHlwZXJzcGVsbC1tY3AiLCJ0cmFuc3BvcnQiOiJzc2UiLCJ1cmwiOiJodHRwczovL2h5cGVyc3BlbGwuc3RsbWNwLmNvbS9zc2UiLCJlbnYiOnsiSFlQRVJTUEVMTF9BUElfS0VZIjoiU2V0IHlvdXIgSFlQRVJTUEVMTF9BUElfS0VZIGhlcmUuIiwiSFlQRVJTUEVMTF9VU0VSX0lEIjoiU2V0IHlvdXIgSFlQRVJTUEVMTF9VU0VSX0lEIGhlcmUuIn19)
+[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=hyperspell-mcp&config=eyJuYW1lIjoiaHlwZXJzcGVsbC1tY3AiLCJ0cmFuc3BvcnQiOiJodHRwIiwidXJsIjoiaHR0cHM6Ly9oeXBlcnNwZWxsLnN0bG1jcC5jb20iLCJoZWFkZXJzIjp7IngtaHlwZXJzcGVsbC1hcGkta2V5IjoiTXkgQVBJIEtleSIsIlgtQXMtVXNlciI6Ik15IFVzZXIgSUQifX0)
 
 ### VS Code
 
 If you use MCP, you can install the MCP server by clicking the link below. You will need to set your environment variables
 in VS Code's `mcp.json`, which can be found via Command Palette > MCP: Open User Configuration.
 
-[Open VS Code](https://vscode.stainless.com/mcp/%7B%22name%22%3A%22hyperspell-mcp%22%2C%22type%22%3A%22sse%22%2C%22url%22%3A%22https%3A%2F%2Fhyperspell.stlmcp.com%2Fsse%22%2C%22env%22%3A%7B%22HYPERSPELL_API_KEY%22%3A%22Set%20your%20HYPERSPELL_API_KEY%20here.%22%2C%22HYPERSPELL_USER_ID%22%3A%22Set%20your%20HYPERSPELL_USER_ID%20here.%22%7D%7D)
+[Open VS Code](https://vscode.stainless.com/mcp/%7B%22name%22%3A%22hyperspell-mcp%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fhyperspell.stlmcp.com%22%2C%22headers%22%3A%7B%22x-hyperspell-api-key%22%3A%22My%20API%20Key%22%2C%22X-As-User%22%3A%22My%20User%20ID%22%7D%7D)
 
 ### Claude Code
 
 If you use Claude Code, you can install the MCP server by running the command below in your terminal. You will need to set your
 environment variables in Claude Code's `.claude.json`, which can be found in your home directory.
 
 ```
-claude mcp add hyperspell_mcp_api --env HYPERSPELL_API_KEY="Your HYPERSPELL_API_KEY here." HYPERSPELL_USER_ID="Your HYPERSPELL_USER_ID here." --transport sse https://hyperspell.stlmcp.com/sse
+claude mcp add hyperspell_mcp_api --header "x-hyperspell-api-key: My API Key" --header "X-As-User: My User ID" --transport http https://hyperspell.stlmcp.com
 ```
 
 ## Code Mode

diff --git a/packages/mcp-server/package.json b/packages/mcp-server/package.json
@@ -1,6 +1,6 @@
 {
   "name": "hyperspell-mcp",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "The official MCP Server for the Hyperspell API",
   "author": "Hyperspell <hello@hyperspell.com>",
   "types": "dist/index.d.ts",
@@ -34,10 +34,13 @@
     "@cloudflare/cabidela": "^0.2.4",
     "@modelcontextprotocol/sdk": "^1.25.2",
     "@valtown/deno-http-worker": "^0.0.21",
+    "cookie-parser": "^1.4.6",
     "cors": "^2.8.5",
     "express": "^5.1.0",
     "fuse.js": "^7.1.0",
     "jq-web": "https://github.com/stainless-api/jq-web/releases/download/v0.8.8/jq-web.tar.gz",
+    "morgan": "^1.10.0",
+    "morgan-body": "^2.6.9",
     "qs": "^6.14.1",
     "typescript": "5.8.3",
     "yargs": "^17.7.2",
@@ -50,9 +53,11 @@
   },
   "devDependencies": {
     "@anthropic-ai/mcpb": "^2.1.2",
+    "@types/cookie-parser": "^1.4.10",
     "@types/cors": "^2.8.19",
     "@types/express": "^5.0.3",
     "@types/jest": "^29.4.0",
+    "@types/morgan": "^1.9.10",
     "@types/qs": "^6.14.0",
     "@types/yargs": "^17.0.8",
     "@typescript-eslint/eslint-plugin": "8.31.1",

diff --git a/packages/mcp-server/src/code-tool.ts b/packages/mcp-server/src/code-tool.ts
@@ -2,8 +2,9 @@
 
 import { McpTool, Metadata, ToolCallResult, asErrorResult, asTextContentResult } from './types';
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
-import { readEnv, readEnvOrError } from './server';
+import { readEnv, requireValue } from './server';
 import { WorkerInput, WorkerOutput } from './code-tool-types';
+import { Hyperspell } from 'hyperspell';
 
 const prompt = `Runs JavaScript code to interact with the Hyperspell API.
 
@@ -54,7 +55,7 @@ export function codeTool(): McpTool {
       required: ['code'],
     },
   };
-  const handler = async (_: unknown, args: any): Promise<ToolCallResult> => {
+  const handler = async (client: Hyperspell, args: any): Promise<ToolCallResult> => {
     const code = args.code as string;
     const intent = args.intent as string | undefined;
 
@@ -70,8 +71,11 @@ export function codeTool(): McpTool {
         ...(stainlessAPIKey && { Authorization: stainlessAPIKey }),
         'Content-Type': 'application/json',
         client_envs: JSON.stringify({
-          HYPERSPELL_API_KEY: readEnvOrError('HYPERSPELL_API_KEY'),
-          HYPERSPELL_BASE_URL: readEnv('HYPERSPELL_BASE_URL'),
+          HYPERSPELL_API_KEY: requireValue(
+            readEnv('HYPERSPELL_API_KEY') ?? client.apiKey,
+            'set HYPERSPELL_API_KEY environment variable or provide apiKey client option',
+          ),
+          HYPERSPELL_BASE_URL: readEnv('HYPERSPELL_BASE_URL') ?? client.baseURL ?? undefined,
         }),
       },
       body: JSON.stringify({

diff --git a/packages/mcp-server/src/headers.ts b/packages/mcp-server/src/headers.ts
@@ -3,7 +3,7 @@
 import { IncomingMessage } from 'node:http';
 import { ClientOptions } from 'hyperspell';
 
-export const parseAuthHeaders = (req: IncomingMessage): Partial<ClientOptions> => {
+export const parseAuthHeaders = (req: IncomingMessage, required?: boolean): Partial<ClientOptions> => {
   if (req.headers.authorization) {
     const scheme = req.headers.authorization.split(' ')[0]!;
     const value = req.headers.authorization.slice(scheme.length + 1);
@@ -15,6 +15,8 @@ export const parseAuthHeaders = (req: IncomingMessage): Partial<ClientOptions> =
           'Unsupported authorization scheme. Expected the "Authorization" header to be a supported scheme (Bearer).',
         );
     }
+  } else if (required) {
+    throw new Error('Missing required Authorization header; see WWW-Authenticate header for details.');
   }
 
   const apiKey =