hyperspell · stainless-app · Dec 18, 2025 · Dec 19, 2025 · Dec 19, 2025
diff --git a/.release-please-manifest.json b/.release-please-manifest.json
@@ -1,3 +1,3 @@
 {
-  ".": "0.29.0"
+  ".": "0.30.0"
 }
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.30.0 (2025-12-19)
+
+Full Changelog: [v0.29.0...v0.30.0](https://github.com/hyperspell/node-sdk/compare/v0.29.0...v0.30.0)
+
+### ⚠ BREAKING CHANGES
+
+* **mcp:** remove deprecated tool schemes
+* **mcp:** **Migration:** To migrate, simply modify the command used to invoke the MCP server. Currently, the only supported tool scheme is code mode. Now, starting the server with just `node /path/to/mcp/server` or `npx package-name` will invoke code tools: changing your command to one of these is likely all you will need to do.
+
+### Bug Fixes
+
+* **mcp:** pass base url to code tool ([5cb1499](https://github.com/hyperspell/node-sdk/commit/5cb1499f5651f1fd65ff80c6ed9f231c160b0a62))
+
+
+### Chores
+
+* **mcp:** remove deprecated tool schemes ([5aa93e0](https://github.com/hyperspell/node-sdk/commit/5aa93e0c5b58a2023376fe6e82a91982c122fd91))
+
 ## 0.29.0 (2025-12-16)
 
 Full Changelog: [v0.27.0...v0.29.0](https://github.com/hyperspell/node-sdk/compare/v0.27.0...v0.29.0)

diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "hyperspell",
-  "version": "0.29.0",
+  "version": "0.30.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/Dockerfile b/packages/mcp-server/Dockerfile
@@ -39,9 +39,6 @@
 
     # Production stage
 
-            FROM denoland/deno:alpine
-            RUN apk add --no-cache npm
-
     # Add non-root user
     RUN addgroup -g 1001 -S nodejs && adduser -S nodejs -u 1001
 
@@ -66,10 +63,6 @@ COPY --from=builder /build/packages/mcp-server/node_modules ./node_modules
     # The MCP server uses stdio transport by default
     # No exposed ports needed for stdio communication
 
-    # This is needed for node to run on the deno:alpine image.
-    # See <https://github.com/denoland/deno_docker/issues/373>.
-    ENV LD_LIBRARY_PATH=/usr/lib:/usr/local/lib
-
     # Set the entrypoint to the MCP server
     ENTRYPOINT ["node", "index.js"]
 

diff --git a/packages/mcp-server/README.md b/packages/mcp-server/README.md
@@ -26,7 +26,7 @@ For clients with a configuration JSON, it might look something like this:
   "mcpServers": {
     "hyperspell_api": {
       "command": "npx",
-      "args": ["-y", "hyperspell-mcp", "--client=claude", "--tools=all"],
+      "args": ["-y", "hyperspell-mcp"],
       "env": {
         "HYPERSPELL_API_KEY": "My API Key",
         "HYPERSPELL_USER_ID": "My User ID"
@@ -59,110 +59,22 @@ environment variables in Claude Code's `.claude.json`, which can be found in you
 claude mcp add --transport stdio hyperspell_api --env HYPERSPELL_API_KEY="Your HYPERSPELL_API_KEY here." HYPERSPELL_USER_ID="Your HYPERSPELL_USER_ID here." -- npx -y hyperspell-mcp
 ```
 
-## Exposing endpoints to your MCP Client
+## Code Mode
 
-There are three ways to expose endpoints as tools in the MCP server:
+This MCP server is built on the "Code Mode" tool scheme. In this MCP Server,
+your agent will write code against the TypeScript SDK, which will then be executed in an
+isolated sandbox. To accomplish this, the server will expose two tools to your agent:
 
-1. Exposing one tool per endpoint, and filtering as necessary
-2. Exposing a set of tools to dynamically discover and invoke endpoints from the API
-3. Exposing a docs search tool and a code execution tool, allowing the client to write code to be executed against the TypeScript client
+- The first tool is a docs search tool, which can be used to generically query for
+  documentation about your API/SDK.
 
-### Filtering endpoints and tools
+- The second tool is a code tool, where the agent can write code against the TypeScript SDK.
+  The code will be executed in a sandbox environment without web or filesystem access. Then,
+  anything the code returns or prints will be returned to the agent as the result of the
+  tool call.
 
-You can run the package on the command line to discover and filter the set of tools that are exposed by the
-MCP Server. This can be helpful for large APIs where including all endpoints at once is too much for your AI's
-context window.
-
-You can filter by multiple aspects:
-
-- `--tool` includes a specific tool by name
-- `--resource` includes all tools under a specific resource, and can have wildcards, e.g. `my.resource*`
-- `--operation` includes just read (get/list) or just write operations
-
-### Dynamic tools
-
-If you specify `--tools=dynamic` to the MCP server, instead of exposing one tool per endpoint in the API, it will
-expose the following tools:
-
-1. `list_api_endpoints` - Discovers available endpoints, with optional filtering by search query
-2. `get_api_endpoint_schema` - Gets detailed schema information for a specific endpoint
-3. `invoke_api_endpoint` - Executes any endpoint with the appropriate parameters
-
-This allows you to have the full set of API endpoints available to your MCP Client, while not requiring that all
-of their schemas be loaded into context at once. Instead, the LLM will automatically use these tools together to
-search for, look up, and invoke endpoints dynamically. However, due to the indirect nature of the schemas, it
-can struggle to provide the correct properties a bit more than when tools are imported explicitly. Therefore,
-you can opt-in to explicit tools, the dynamic tools, or both.
-
-See more information with `--help`.
-
-All of these command-line options can be repeated, combined together, and have corresponding exclusion versions (e.g. `--no-tool`).
-
-Use `--list` to see the list of available tools, or see below.
-
-### Code execution
-
-If you specify `--tools=code` to the MCP server, it will expose just two tools:
-
-- `search_docs` - Searches the API documentation and returns a list of markdown results
-- `execute` - Runs code against the TypeScript client
-
-This allows the LLM to implement more complex logic by chaining together many API calls without loading
-intermediary results into its context window.
-
-The code execution itself happens in a Deno sandbox that has network access only to the base URL for the API.
-
-### Specifying the MCP Client
-
-Different clients have varying abilities to handle arbitrary tools and schemas.
-
-You can specify the client you are using with the `--client` argument, and the MCP server will automatically
-serve tools and schemas that are more compatible with that client.
-
-- `--client=<type>`: Set all capabilities based on a known MCP client
-
-  - Valid values: `openai-agents`, `claude`, `claude-code`, `cursor`
-  - Example: `--client=cursor`
-
-Additionally, if you have a client not on the above list, or the client has gotten better
-over time, you can manually enable or disable certain capabilities:
-
-- `--capability=<name>`: Specify individual client capabilities
-  - Available capabilities:
-    - `top-level-unions`: Enable support for top-level unions in tool schemas
-    - `valid-json`: Enable JSON string parsing for arguments
-    - `refs`: Enable support for $ref pointers in schemas
-    - `unions`: Enable support for union types (anyOf) in schemas
-    - `formats`: Enable support for format validations in schemas (e.g. date-time, email)
-    - `tool-name-length=N`: Set maximum tool name length to N characters
-  - Example: `--capability=top-level-unions --capability=tool-name-length=40`
-  - Example: `--capability=top-level-unions,tool-name-length=40`
-
-### Examples
-
-1. Filter for read operations on cards:
-
-```bash
---resource=cards --operation=read
-```
-
-2. Exclude specific tools while including others:
-
-```bash
---resource=cards --no-tool=create_cards
-```
-
-3. Configure for Cursor client with custom max tool name length:
-
-```bash
---client=cursor --capability=tool-name-length=40
-```
-
-4. Complex filtering with multiple criteria:
-
-```bash
---resource=cards,accounts --operation=read --tag=kyc --no-tool=create_cards
-```
+Using this scheme, agents are capable of performing very complex tasks deterministically
+and repeatably.
 
 ## Running remotely
 
@@ -190,76 +102,3 @@ A configuration JSON for this server might look like this, assuming the server i
   }
 }
 ```
-
-The command-line arguments for filtering tools and specifying clients can also be used as query parameters in the URL.
-For example, to exclude specific tools while including others, use the URL:
-
-```
-http://localhost:3000?resource=cards&resource=accounts&no_tool=create_cards
-```
-
-Or, to configure for the Cursor client, with a custom max tool name length, use the URL:
-
-```
-http://localhost:3000?client=cursor&capability=tool-name-length%3D40
-```
-
-## Importing the tools and server individually
-
-```js
-// Import the server, generated endpoints, or the init function
-import { server, endpoints, init } from "hyperspell-mcp/server";
-
-// import a specific tool
-import listConnections from "hyperspell-mcp/tools/connections/list-connections";
-
-// initialize the server and all endpoints
-init({ server, endpoints });
-
-// manually start server
-const transport = new StdioServerTransport();
-await server.connect(transport);
-
-// or initialize your own server with specific tools
-const myServer = new McpServer(...);
-
-// define your own endpoint
-const myCustomEndpoint = {
-  tool: {
-    name: 'my_custom_tool',
-    description: 'My custom tool',
-    inputSchema: zodToJsonSchema(z.object({ a_property: z.string() })),
-  },
-  handler: async (client: client, args: any) => {
-    return { myResponse: 'Hello world!' };
-  })
-};
-
-// initialize the server with your custom endpoints
-init({ server: myServer, endpoints: [listConnections, myCustomEndpoint] });
-```
-
-## Available Tools
-
-The following tools are available in this MCP server.
-
-### Resource `connections`:
-
-- `list_connections` (`read`): Get accounts the user has connected
-
-### Resource `integrations`:
-
-- `list_integrations` (`read`): List all available integrations
-- `connect_integration` (`read`): Get a signed url to connect to a given integration. Use the `list_integrations` tool to find the correct `integration_id` for the required provider.
-
-### Resource `memories`:
-
-- `update_memory` (`write`): This tool lets you update memory in Hyperspell.
-- `add_memory` (`write`): This tool lets you add text, markdown, or JSON to the Hyperspell index so it can be searched later. It will return the `source` and `resource_id` that can be used to later retrieve the processed memory.
-- `get_memory` (`read`): This tool lets you retrieve a memory that has been previously indexed.
-- `search` (`write`): Search all memories indexed by Hyperspell. Set 'answer' to true to directly answer the query, or to 'false' to simply get all memories related to the query.
-- `upload_file` (`write`): This tool lets you upload a file to the Hyperspell index. It will return the `source` and `resource_id` that can be used to later retrieve the processed memory.
-
-### Resource `auth`:
-
-- `user_info` (`read`): Get basic info about the current user, including which integrations are currently enabled and which ones are available.
diff --git a/packages/mcp-server/package.json b/packages/mcp-server/package.json
@@ -1,6 +1,6 @@
 {
   "name": "hyperspell-mcp",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "description": "The official MCP Server for the Hyperspell API",
   "author": "Hyperspell <hello@hyperspell.com>",
   "types": "dist/index.d.ts",

diff --git a/packages/mcp-server/src/code-tool.ts b/packages/mcp-server/src/code-tool.ts
@@ -1,6 +1,6 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { Metadata, ToolCallResult, asTextContentResult } from './tools/types';
+import { McpTool, Metadata, ToolCallResult, asTextContentResult } from './types';
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
 import { readEnv } from './server';
 import { WorkerSuccess } from './code-tool-types';
@@ -13,7 +13,7 @@ import { WorkerSuccess } from './code-tool-types';
  *
  * @param endpoints - The endpoints to include in the list.
  */
-export async function codeTool() {
+export function codeTool(): McpTool {
   const metadata: Metadata = { resource: 'all', operation: 'write', tags: [] };
   const tool: Tool = {
     name: 'execute',
@@ -38,6 +38,7 @@ export async function codeTool() {
         client_envs: JSON.stringify({
           HYPERSPELL_API_KEY: readEnv('HYPERSPELL_API_KEY'),
           HYPERSPELL_USER_ID: readEnv('HYPERSPELL_USER_ID'),
+          HYPERSPELL_BASE_URL: readEnv('HYPERSPELL_BASE_URL'),
         }),
       },
       body: JSON.stringify({