feat(mcp): remote server with passthru auth

Author: stainless-app[bot]

packages/mcp-server/package.json

@@ -29,6 +29,7 @@
   "dependencies": {
     "isaacus": "file:../../dist/",
     "@modelcontextprotocol/sdk": "^1.11.5",
+    "express": "^5.1.0",
     "jq-web": "https://github.com/stainless-api/jq-web/releases/download/v0.8.2/jq-web.tar.gz",
     "yargs": "^17.7.2",
     "@cloudflare/cabidela": "^0.2.4",
@@ -40,6 +41,7 @@
   },
   "devDependencies": {
     "@types/jest": "^29.4.0",
+    "@types/express": "^5.0.3",
     "@typescript-eslint/eslint-plugin": "8.31.1",
     "@typescript-eslint/parser": "8.31.1",
     "eslint": "^8.49.0",

packages/mcp-server/src/headers.ts

@@ -0,0 +1,24 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { type ClientOptions } from 'isaacus/client';
+
+import { IncomingMessage } from 'node:http';
+
+export const parseAuthHeaders = (req: IncomingMessage): Partial<ClientOptions> => {
+  if (req.headers.authorization) {
+    const scheme = req.headers.authorization.slice(req.headers.authorization.search(' '));
+    const value = req.headers.authorization.slice(scheme.length + 1);
+    switch (scheme) {
+      case 'Bearer':
+        return { apiKey: req.headers.authorization.slice('Bearer '.length) };
+      default:
+        throw new Error(`Unsupported authorization scheme`);
+    }
+  }
+
+  const apiKey =
+    req.headers['x-isaacus-api-key'] instanceof Array ?
+      req.headers['x-isaacus-api-key'][0]
+    : req.headers['x-isaacus-api-key'];
+  return { apiKey };
+};

packages/mcp-server/src/http.ts

@@ -0,0 +1,85 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+
+import express from 'express';
+import { McpOptions } from './options';
+import { initMcpServer, newMcpServer } from './server';
+import { parseAuthHeaders } from './headers';
+import { Endpoint } from './tools';
+
+const newServer = (mcpOptions: McpOptions, req: express.Request, res: express.Response): McpServer | null => {
+  const server = newMcpServer();
+  try {
+    const authOptions = parseAuthHeaders(req);
+    initMcpServer({
+      server: server,
+      clientOptions: {
+        ...authOptions,
+        defaultHeaders: {
+          'X-Stainless-MCP': 'true',
+        },
+      },
+      mcpOptions,
+    });
+  } catch {
+    res.status(401).json({
+      jsonrpc: '2.0',
+      error: {
+        code: -32000,
+        message: 'Unauthorized',
+      },
+    });
+    return null;
+  }
+
+  return server;
+};
+
+const post = (defaultOptions: McpOptions) => async (req: express.Request, res: express.Response) => {
+  const server = newServer(defaultOptions, req, res);
+  // If we return null, we already set the authorization error.
+  if (server === null) return;
+  const transport = new StreamableHTTPServerTransport({
+    // Stateless server
+    sessionIdGenerator: undefined,
+  });
+  await server.connect(transport);
+  await transport.handleRequest(req, res, req.body);
+};
+
+const get = async (req: express.Request, res: express.Response) => {
+  res.status(405).json({
+    jsonrpc: '2.0',
+    error: {
+      code: -32000,
+      message: 'Method not supported',
+    },
+  });
+};
+
+const del = async (req: express.Request, res: express.Response) => {
+  res.status(405).json({
+    jsonrpc: '2.0',
+    error: {
+      code: -32000,
+      message: 'Method not supported',
+    },
+  });
+};
+
+export const launchStreamableHTTPServer = async (
+  options: McpOptions,
+  endpoints: Endpoint[],
+  port: number | undefined,
+) => {
+  const app = express();
+  app.use(express.json());
+
+  app.get('/', get);
+  app.post('/', post(options));
+  app.delete('/', del);
+
+  console.error(`MCP Server running on streamable HTTP on port ${port}`);
+
+  app.listen(port);
+};

packages/mcp-server/src/index.ts

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { init, selectTools, server } from './server';
+import { selectTools } from './server';
 import { Endpoint, endpoints } from './tools';
 import { McpOptions, parseOptions } from './options';
+import { launchStdioServer } from './stdio';
+import { launchStreamableHTTPServer } from './http';
 
 async function main() {
   const options = parseOptionsOrError();
@@ -13,18 +14,21 @@ async function main() {
     return;
   }
 
-  const includedTools = selectToolsOrError(endpoints, options);
+  const selectedTools = selectToolsOrError(endpoints, options);
 
   console.error(
-    `MCP Server starting with ${includedTools.length} tools:`,
-    includedTools.map((e) => e.tool.name),
+    `MCP Server starting with ${selectedTools.length} tools:`,
+    selectedTools.map((e) => e.tool.name),
   );
 
-  init({ server, endpoints: includedTools });
-
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
-  console.error('MCP Server running on stdio');
+  switch (options.transport) {
+    case 'stdio':
+      await launchStdioServer(options, selectedTools);
+      break;
+    case 'http':
+      await launchStreamableHTTPServer(options, selectedTools, options.port);
+      break;
+  }
 }
 
 if (require.main === module) {
@@ -43,7 +47,7 @@ function parseOptionsOrError() {
   }
 }
 
-function selectToolsOrError(endpoints: Endpoint[], options: McpOptions) {
+function selectToolsOrError(endpoints: Endpoint[], options: McpOptions): Endpoint[] {
   try {
     const includedTools = selectTools(endpoints, options);
     if (includedTools.length === 0) {

packages/mcp-server/src/options.ts

@@ -5,6 +5,8 @@ import { ClientCapabilities, knownClients, ClientType } from './compat';
 
 export type CLIOptions = McpOptions & {
   list: boolean;
+  transport: 'stdio' | 'http';
+  port: number | undefined;
 };
 
 export type McpOptions = {
@@ -129,6 +131,16 @@ export function parseOptions(): CLIOptions {
       type: 'boolean',
       description: 'Print detailed explanation of client capabilities and exit',
     })
+    .option('transport', {
+      type: 'string',
+      choices: ['stdio', 'http'],
+      default: 'stdio',
+      description: 'What transport to use; stdio for local servers or http for remote servers',
+    })
+    .option('port', {
+      type: 'number',
+      description: 'Port to serve on if using http transport',
+    })
     .help();
 
   for (const [command, desc] of examples()) {
@@ -238,6 +250,8 @@ export function parseOptions(): CLIOptions {
   const includeAllTools =
     explicitTools ? argv.tools?.includes('all') && !argv.noTools?.includes('all') : undefined;
 
+  const transport = argv.transport as 'stdio' | 'http';
+
   const client = argv.client as ClientType;
   return {
     client: client && knownClients[client] ? client : undefined,
@@ -246,6 +260,8 @@ export function parseOptions(): CLIOptions {
     filters,
     capabilities: clientCapabilities,
     list: argv.list || false,
+    transport,
+    port: argv.port,
   };
 }
 

packages/mcp-server/src/server.ts

@@ -22,14 +22,17 @@ export { Filter } from './tools';
 export { ClientOptions } from 'isaacus';
 export { endpoints } from './tools';
 
+export const newMcpServer = () =>
+  new McpServer(
+    {
+      name: 'isaacus_api',
+      version: '0.11.0',
+    },
+    { capabilities: { tools: {}, logging: {} } },
+  );
+
 // Create server instance
-export const server = new McpServer(
-  {
-    name: 'isaacus_api',
-    version: '0.11.0',
-  },
-  { capabilities: { tools: {}, logging: {} } },
-);
+export const server = newMcpServer();
 
 /**
  * Initializes the provided MCP Server with the given tools and handlers.
@@ -100,7 +103,7 @@ export function init(params: {
 /**
  * Selects the tools to include in the MCP Server based on the provided options.
  */
-export function selectTools(endpoints: Endpoint[], options: McpOptions) {
+export function selectTools(endpoints: Endpoint[], options: McpOptions): Endpoint[] {
   const filteredEndpoints = query(options.filters, endpoints);
 
   let includedTools = filteredEndpoints;

packages/mcp-server/src/stdio.ts

@@ -0,0 +1,14 @@
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { init, newMcpServer } from './server';
+import { Endpoint } from './tools';
+import { McpOptions } from './options';
+
+export const launchStdioServer = async (options: McpOptions, endpoints: Endpoint[]) => {
+  const server = newMcpServer();
+
+  init({ server, endpoints });
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('MCP Server running on stdio');
+};