@ttoss/http-server-mcp 0.5.7 → 0.6.0

package/README.md

@@ -57,6 +57,84 @@ app.listen(3000, () => {
 });
 ```
 
+## `apiCall` — Generic HTTP Helper
+
+`apiCall` is a generic HTTP helper for use inside MCP tool handlers. It works with any URL — your own REST API, third-party APIs, public APIs, or services using `x-api-key` or any other header scheme.
+
+Use `getApiHeaders` in `createMcpRouter` to configure which headers from the incoming MCP request are automatically forwarded to every `apiCall`. Tool handlers stay clean and auth-agnostic.
+
+### Bearer token forwarding
+
+```typescript
+import {
+  apiCall,
+  createMcpRouter,
+  Server as McpServer,
+} from '@ttoss/http-server-mcp';
+
+const mcpServer = new McpServer({ name: 'my-server', version: '1.0.0' });
+
+mcpServer.registerTool(
+  'list-portfolios',
+  { description: 'List all portfolios', inputSchema: {} },
+  async () => {
+    // Bearer token is forwarded automatically — no manual wiring
+    const data = await apiCall('GET', '/portfolios');
+    return { content: [{ type: 'text', text: JSON.stringify(data) }] };
+  }
+);
+
+const mcpRouter = createMcpRouter(mcpServer, {
+  apiBaseUrl: `http://localhost:${process.env.PORT}/api/v1`,
+  // Extract the caller's Bearer token and inject it into every apiCall
+  getApiHeaders: (ctx) => ({ Authorization: ctx.headers.authorization ?? '' }),
+});
+```
+
+### x-api-key forwarding
+
+```typescript
+const mcpRouter = createMcpRouter(mcpServer, {
+  apiBaseUrl: 'https://internal-service/api',
+  getApiHeaders: (ctx) => ({
+    'x-api-key': ctx.headers['x-api-key'] as string,
+  }),
+});
+```
+
+### Third-party or public APIs (full URL, no context required)
+
+```typescript
+mcpServer.registerTool(
+  'get-rates',
+  { description: 'Currency rates', inputSchema: {} },
+  async () => {
+    // Full URL — works entirely outside any context
+    const rates = await apiCall('GET', 'https://api.exchangerate.host/latest');
+    return { content: [{ type: 'text', text: JSON.stringify(rates) }] };
+  }
+);
+```
+
+### POST with a body
+
+```typescript
+const result = await apiCall('POST', '/portfolios', {
+  body: { name: 'Growth Fund' },
+});
+```
+
+### Per-call header override
+
+```typescript
+// Context-injected headers are merged; per-call headers take precedence
+const data = await apiCall('GET', 'https://partner.api.com/data', {
+  headers: { Authorization: 'Bearer fixed-service-token' },
+});
+```
+
+`apiCall` throws with a clear message when called with a relative path and no `apiBaseUrl` is configured in the context.
+
 ## API Reference
 
 ### `createMcpRouter(server, options?)`
@@ -69,9 +147,24 @@ Creates a Koa router configured to handle MCP protocol requests.
 - `options` (`McpRouterOptions`) - Optional configuration
   - `path` (`string`) - HTTP path for MCP endpoint (default: `'/mcp'`)
   - `sessionIdGenerator` (`() => string`) - Session ID generator for stateful servers (default: `undefined` for stateless)
+  - `apiBaseUrl` (`string`) - Base URL prepended to relative paths in `apiCall`
+  - `getApiHeaders` (`(ctx: Context) => Record<string, string>`) - Return headers to inject into every `apiCall` for this request (auth tokens, API keys, trace headers, etc.)
 
 **Returns:** `Router` - Koa router instance
 
+### `apiCall(method, url, options?)`
+
+Generic HTTP helper for use inside MCP tool handlers.
+
+**Parameters:**
+
+- `method` (`string`) - HTTP method (`'GET'`, `'POST'`, `'PUT'`, `'DELETE'`, …)
+- `url` (`string`) - Full URL **or** a path starting with `/` (prepended with `apiBaseUrl`)
+- `options.body` (`unknown`, optional) - Request body, serialised as JSON
+- `options.headers` (`Record<string, string>`, optional) - Per-call header overrides; merged on top of context-injected headers
+
+**Returns:** `Promise<unknown>` - Parsed JSON response body
+
 ## Examples
 
 ### Basic Tool
@@ -202,6 +295,16 @@ This package implements the [Model Context Protocol](https://spec.modelcontextpr
 - `POST /mcp` - Send JSON-RPC requests/notifications
 - `DELETE /mcp` - Terminate session (optional)
 
+**Client requirements (per MCP spec):**
+
+- `Content-Type: application/json`
+- `Accept: application/json, text/event-stream`
+
+**Stateless vs stateful mode:**
+
+- **Stateless** (default, `sessionIdGenerator: undefined`) — a fresh transport is created per HTTP request. No session tracking. Suitable for serverless environments and simple integrations.
+- **Stateful** (`sessionIdGenerator` provided) — a single shared transport handles all requests and tracks sessions by ID.
+
 ## Related Packages
 
 - [@ttoss/http-server](https://ttoss.dev/docs/modules/packages/http-server) - HTTP server foundation

package/dist/esm/index.js

@@ -6,25 +6,124 @@ var __name = (target, value) => __defProp(target, "name", {
 });
 
 // src/index.ts
+import { AsyncLocalStorage } from "async_hooks";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { Router } from "@ttoss/http-server";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
+var requestContextStore = new AsyncLocalStorage();
+var apiCall = /* @__PURE__ */__name(async (method, url, options) => {
+  const context = requestContextStore.getStore();
+  let resolvedUrl = url;
+  if (url.startsWith("/")) {
+    if (!context?.apiBaseUrl) {
+      throw new Error(`apiCall received a relative path ("${url}") but no apiBaseUrl is configured. Either pass a full URL or set apiBaseUrl in createMcpRouter options.`);
+    }
+    resolvedUrl = `${context.apiBaseUrl.replace(/\/$/, "")}${url}`;
+  }
+  const hasBody = options?.body !== void 0;
+  const headers = {
+    ...(context !== void 0 ? context.apiHeaders : {}),
+    ...(options?.headers ?? {})
+  };
+  const hasExplicitContentType = Object.keys(headers).some(headerName => {
+    return headerName.toLowerCase() === "content-type";
+  });
+  if (hasBody && !hasExplicitContentType) {
+    headers["Content-Type"] = "application/json";
+  }
+  const response = await fetch(resolvedUrl, {
+    method,
+    headers,
+    body: hasBody ? JSON.stringify(options.body) : void 0
+  });
+  if (!response.ok) {
+    const err = await response.json().catch(() => {
+      return {
+        error: response.statusText
+      };
+    });
+    throw new Error(err.error || `HTTP ${response.status}`);
+  }
+  if (response.status === 204 || response.status === 205) {
+    return void 0;
+  }
+  const contentType = response.headers.get("content-type");
+  if (contentType?.includes("application/json")) {
+    return response.json();
+  }
+  return response.text();
+}, "apiCall");
 var createMcpRouter = /* @__PURE__ */__name((server, options = {}) => {
   const {
     path = "/mcp",
-    sessionIdGenerator
-  } = options;
-  const transport = new StreamableHTTPServerTransport({
     sessionIdGenerator,
-    enableJsonResponse: true
-  });
-  server.connect(transport);
+    apiBaseUrl,
+    getApiHeaders
+  } = options;
+  const isStateful = sessionIdGenerator !== void 0;
+  const needsContext = apiBaseUrl !== void 0 || getApiHeaders !== void 0;
+  let sharedTransport;
+  if (isStateful) {
+    sharedTransport = new StreamableHTTPServerTransport({
+      sessionIdGenerator,
+      enableJsonResponse: true
+    });
+    server.connect(sharedTransport);
+  }
+  let statelessQueue = Promise.resolve();
+  const enqueueStateless = /* @__PURE__ */__name(work => {
+    const result = statelessQueue.then(() => {
+      return work();
+    });
+    statelessQueue = result.catch(() => {});
+    return result;
+  }, "enqueueStateless");
   const router = new Router();
+  const handleWithContext = /* @__PURE__ */__name(async (ctx, body) => {
+    const apiHeaders = getApiHeaders ? getApiHeaders(ctx) : {};
+    const runRequest = /* @__PURE__ */__name(async transport => {
+      await transport.handleRequest(ctx.req, ctx.res, body);
+      ctx.respond = false;
+    }, "runRequest");
+    if (isStateful && sharedTransport) {
+      if (needsContext) {
+        await requestContextStore.run({
+          apiBaseUrl,
+          apiHeaders
+        }, () => {
+          return runRequest(sharedTransport);
+        });
+      } else {
+        await runRequest(sharedTransport);
+      }
+    } else {
+      await enqueueStateless(async () => {
+        const transport = new StreamableHTTPServerTransport({
+          sessionIdGenerator: void 0,
+          enableJsonResponse: true
+        });
+        try {
+          await server.connect(transport);
+          if (needsContext) {
+            await requestContextStore.run({
+              apiBaseUrl,
+              apiHeaders
+            }, () => {
+              return runRequest(transport);
+            });
+          } else {
+            await runRequest(transport);
+          }
+        } finally {
+          await transport.close();
+        }
+      });
+    }
+  }, "handleWithContext");
   router.post(path, async ctx => {
     try {
-      await transport.handleRequest(ctx.req, ctx.res, ctx.request.body);
-      ctx.respond = false;
+      await handleWithContext(ctx, ctx.request.body);
     } catch (error) {
       if (!ctx.res.headersSent) {
         ctx.status = 500;
@@ -36,8 +135,7 @@ var createMcpRouter = /* @__PURE__ */__name((server, options = {}) => {
   });
   router.delete(path, async ctx => {
     try {
-      await transport.handleRequest(ctx.req, ctx.res, void 0);
-      ctx.respond = false;
+      await handleWithContext(ctx);
     } catch (error) {
       if (!ctx.res.headersSent) {
         ctx.status = 500;
@@ -49,4 +147,4 @@ var createMcpRouter = /* @__PURE__ */__name((server, options = {}) => {
   });
   return router;
 }, "createMcpRouter");
-export { McpServer as Server, createMcpRouter, z };
+export { McpServer as Server, apiCall, createMcpRouter, z };

package/dist/index.d.cts

@@ -1,9 +1,80 @@
 import * as _koa_router from '@koa/router';
 import * as koa from 'koa';
+import { Context } from 'koa';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 export { McpServer, McpServer as Server } from '@modelcontextprotocol/sdk/server/mcp.js';
 export { z } from 'zod';
 
+/**
+ * Options for a single `apiCall` request.
+ */
+interface ApiCallOptions {
+    /**
+     * JSON-serialisable request body. Automatically serialised and sent with
+     * `Content-Type: application/json`.
+     */
+    body?: unknown;
+    /**
+     * Additional or override headers for this specific request.
+     * These are merged on top of any headers injected from the MCP request
+     * context via `getApiHeaders`, allowing per-call overrides.
+     */
+    headers?: Record<string, string>;
+}
+/**
+ * Generic HTTP helper for use inside MCP tool handlers.
+ *
+ * Accepts any full URL (third-party APIs, public APIs, etc.) or a path
+ * relative to the `apiBaseUrl` configured in `createMcpRouter`.
+ *
+ * Headers configured via `getApiHeaders` in `createMcpRouter` are injected
+ * automatically into every request, allowing transparent forwarding of auth
+ * tokens, API keys, or any other header — without coupling this helper to a
+ * specific authentication scheme. Per-call `options.headers` take precedence
+ * over context-injected headers.
+ *
+ * @param method - HTTP method (e.g. `'GET'`, `'POST'`, `'PUT'`, `'DELETE'`)
+ * @param url - Full URL **or** a path starting with `/` (appended to `apiBaseUrl`)
+ * @param options - Optional body and per-call header overrides
+ * @returns Parsed JSON response body
+ *
+ * @example Bearer token forwarding (configured once in `createMcpRouter`)
+ * ```typescript
+ * import { apiCall, createMcpRouter, Server as McpServer } from '@ttoss/http-server-mcp';
+ *
+ * // Tool handler – no manual auth wiring needed
+ * mcpServer.registerTool('list-portfolios', { description: '...', inputSchema: {} }, async () => {
+ *   const data = await apiCall('GET', '/portfolios');
+ *   return { content: [{ type: 'text', text: JSON.stringify(data) }] };
+ * });
+ *
+ * const mcpRouter = createMcpRouter(mcpServer, {
+ *   apiBaseUrl: `http://localhost:${process.env.PORT}/api/v1`,
+ *   // Forward the caller's Bearer token to every apiCall
+ *   getApiHeaders: (ctx) => ({ Authorization: ctx.headers.authorization ?? '' }),
+ * });
+ * ```
+ *
+ * @example x-api-key forwarding
+ * ```typescript
+ * const mcpRouter = createMcpRouter(mcpServer, {
+ *   apiBaseUrl: 'https://internal-service/api',
+ *   getApiHeaders: (ctx) => ({
+ *     'x-api-key': ctx.headers['x-api-key'] as string,
+ *   }),
+ * });
+ * ```
+ *
+ * @example Third-party or public API (full URL, no context required)
+ * ```typescript
+ * const weather = await apiCall('GET', 'https://api.weather.com/current?city=Berlin');
+ * const created = await apiCall('POST', 'https://api.example.com/items', {
+ *   body: { name: 'widget' },
+ *   headers: { Authorization: 'Bearer fixed-service-token' },
+ * });
+ * ```
+ */
+declare const apiCall: (method: string, url: string, options?: ApiCallOptions) => Promise<unknown>;
 /**
  * Options for configuring the MCP router
  */
@@ -14,10 +85,45 @@ interface McpRouterOptions {
      */
     path?: string;
     /**
-     * Optional session ID generator for stateful MCP servers
-     * Set to undefined for stateless servers
+     * Optional session ID generator for stateful MCP servers.
+     * When provided, a single shared transport is created and sessions are tracked.
+     * When undefined (default), the server operates in stateless mode where each
+     * HTTP request uses its own transport instance.
      */
     sessionIdGenerator?: () => string;
+    /**
+     * Base URL prepended to relative paths passed to `apiCall` (paths starting
+     * with `/`). Tool handlers can then call `apiCall('GET', '/resource')` without
+     * specifying a host.
+     *
+     * @example 'http://localhost:3000/api/v1'
+     */
+    apiBaseUrl?: string;
+    /**
+     * Called once per incoming MCP HTTP request. Return a plain object whose
+     * key-value pairs will be merged into the headers of every `apiCall` made
+     * within that request's tool handlers.
+     *
+     * Use this to forward any header from the MCP request — Bearer tokens, API
+     * keys, tenant IDs, trace headers, etc. — without coupling tool handlers to
+     * a specific authentication scheme.
+     *
+     * @example Forward a Bearer token
+     * ```typescript
+     * getApiHeaders: (ctx) => ({ Authorization: ctx.headers.authorization ?? '' })
+     * ```
+     *
+     * @example Forward an x-api-key header
+     * ```typescript
+     * getApiHeaders: (ctx) => ({ 'x-api-key': ctx.headers['x-api-key'] as string })
+     * ```
+     *
+     * @example Inject a static service-to-service key
+     * ```typescript
+     * getApiHeaders: () => ({ 'x-internal-key': process.env.INTERNAL_API_KEY! })
+     * ```
+     */
+    getApiHeaders?: (ctx: Context) => Record<string, string>;
 }
 /**
  * Creates a Koa router configured to handle MCP protocol requests
@@ -58,4 +164,4 @@ interface McpRouterOptions {
  */
 declare const createMcpRouter: (server: McpServer, options?: McpRouterOptions) => _koa_router.RouterInstance<koa.DefaultState, koa.DefaultContext>;
 
-export { type McpRouterOptions, createMcpRouter };
+export { type ApiCallOptions, type McpRouterOptions, apiCall, createMcpRouter };

package/dist/index.d.ts

@@ -1,9 +1,80 @@
 import * as _koa_router from '@koa/router';
 import * as koa from 'koa';
+import { Context } from 'koa';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 export { McpServer, McpServer as Server } from '@modelcontextprotocol/sdk/server/mcp.js';
 export { z } from 'zod';
 
+/**
+ * Options for a single `apiCall` request.
+ */
+interface ApiCallOptions {
+    /**
+     * JSON-serialisable request body. Automatically serialised and sent with
+     * `Content-Type: application/json`.
+     */
+    body?: unknown;
+    /**
+     * Additional or override headers for this specific request.
+     * These are merged on top of any headers injected from the MCP request
+     * context via `getApiHeaders`, allowing per-call overrides.
+     */
+    headers?: Record<string, string>;
+}
+/**
+ * Generic HTTP helper for use inside MCP tool handlers.
+ *
+ * Accepts any full URL (third-party APIs, public APIs, etc.) or a path
+ * relative to the `apiBaseUrl` configured in `createMcpRouter`.
+ *
+ * Headers configured via `getApiHeaders` in `createMcpRouter` are injected
+ * automatically into every request, allowing transparent forwarding of auth
+ * tokens, API keys, or any other header — without coupling this helper to a
+ * specific authentication scheme. Per-call `options.headers` take precedence
+ * over context-injected headers.
+ *
+ * @param method - HTTP method (e.g. `'GET'`, `'POST'`, `'PUT'`, `'DELETE'`)
+ * @param url - Full URL **or** a path starting with `/` (appended to `apiBaseUrl`)
+ * @param options - Optional body and per-call header overrides
+ * @returns Parsed JSON response body
+ *
+ * @example Bearer token forwarding (configured once in `createMcpRouter`)
+ * ```typescript
+ * import { apiCall, createMcpRouter, Server as McpServer } from '@ttoss/http-server-mcp';
+ *
+ * // Tool handler – no manual auth wiring needed
+ * mcpServer.registerTool('list-portfolios', { description: '...', inputSchema: {} }, async () => {
+ *   const data = await apiCall('GET', '/portfolios');
+ *   return { content: [{ type: 'text', text: JSON.stringify(data) }] };
+ * });
+ *
+ * const mcpRouter = createMcpRouter(mcpServer, {
+ *   apiBaseUrl: `http://localhost:${process.env.PORT}/api/v1`,
+ *   // Forward the caller's Bearer token to every apiCall
+ *   getApiHeaders: (ctx) => ({ Authorization: ctx.headers.authorization ?? '' }),
+ * });
+ * ```
+ *
+ * @example x-api-key forwarding
+ * ```typescript
+ * const mcpRouter = createMcpRouter(mcpServer, {
+ *   apiBaseUrl: 'https://internal-service/api',
+ *   getApiHeaders: (ctx) => ({
+ *     'x-api-key': ctx.headers['x-api-key'] as string,
+ *   }),
+ * });
+ * ```
+ *
+ * @example Third-party or public API (full URL, no context required)
+ * ```typescript
+ * const weather = await apiCall('GET', 'https://api.weather.com/current?city=Berlin');
+ * const created = await apiCall('POST', 'https://api.example.com/items', {
+ *   body: { name: 'widget' },
+ *   headers: { Authorization: 'Bearer fixed-service-token' },
+ * });
+ * ```
+ */
+declare const apiCall: (method: string, url: string, options?: ApiCallOptions) => Promise<unknown>;
 /**
  * Options for configuring the MCP router
  */
@@ -14,10 +85,45 @@ interface McpRouterOptions {
      */
     path?: string;
     /**
-     * Optional session ID generator for stateful MCP servers
-     * Set to undefined for stateless servers
+     * Optional session ID generator for stateful MCP servers.
+     * When provided, a single shared transport is created and sessions are tracked.
+     * When undefined (default), the server operates in stateless mode where each
+     * HTTP request uses its own transport instance.
      */
     sessionIdGenerator?: () => string;
+    /**
+     * Base URL prepended to relative paths passed to `apiCall` (paths starting
+     * with `/`). Tool handlers can then call `apiCall('GET', '/resource')` without
+     * specifying a host.
+     *
+     * @example 'http://localhost:3000/api/v1'
+     */
+    apiBaseUrl?: string;
+    /**
+     * Called once per incoming MCP HTTP request. Return a plain object whose
+     * key-value pairs will be merged into the headers of every `apiCall` made
+     * within that request's tool handlers.
+     *
+     * Use this to forward any header from the MCP request — Bearer tokens, API
+     * keys, tenant IDs, trace headers, etc. — without coupling tool handlers to
+     * a specific authentication scheme.
+     *
+     * @example Forward a Bearer token
+     * ```typescript
+     * getApiHeaders: (ctx) => ({ Authorization: ctx.headers.authorization ?? '' })
+     * ```
+     *
+     * @example Forward an x-api-key header
+     * ```typescript
+     * getApiHeaders: (ctx) => ({ 'x-api-key': ctx.headers['x-api-key'] as string })
+     * ```
+     *
+     * @example Inject a static service-to-service key
+     * ```typescript
+     * getApiHeaders: () => ({ 'x-internal-key': process.env.INTERNAL_API_KEY! })
+     * ```
+     */
+    getApiHeaders?: (ctx: Context) => Record<string, string>;
 }
 /**
  * Creates a Koa router configured to handle MCP protocol requests
@@ -58,4 +164,4 @@ interface McpRouterOptions {
  */
 declare const createMcpRouter: (server: McpServer, options?: McpRouterOptions) => _koa_router.RouterInstance<koa.DefaultState, koa.DefaultContext>;
 
-export { type McpRouterOptions, createMcpRouter };
+export { type ApiCallOptions, type McpRouterOptions, apiCall, createMcpRouter };

package/dist/index.js

@@ -32,29 +32,129 @@ var __toCommonJS = mod => __copyProps(__defProp({}, "__esModule", {
 var index_exports = {};
 __export(index_exports, {
   Server: () => import_mcp.McpServer,
+  apiCall: () => apiCall,
   createMcpRouter: () => createMcpRouter,
   z: () => import_zod.z
 });
 module.exports = __toCommonJS(index_exports);
+var import_node_async_hooks = require("async_hooks");
 var import_streamableHttp = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
 var import_http_server = require("@ttoss/http-server");
 var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
 var import_zod = require("zod");
+var requestContextStore = new import_node_async_hooks.AsyncLocalStorage();
+var apiCall = /* @__PURE__ */__name(async (method, url, options) => {
+  const context = requestContextStore.getStore();
+  let resolvedUrl = url;
+  if (url.startsWith("/")) {
+    if (!context?.apiBaseUrl) {
+      throw new Error(`apiCall received a relative path ("${url}") but no apiBaseUrl is configured. Either pass a full URL or set apiBaseUrl in createMcpRouter options.`);
+    }
+    resolvedUrl = `${context.apiBaseUrl.replace(/\/$/, "")}${url}`;
+  }
+  const hasBody = options?.body !== void 0;
+  const headers = {
+    ...(context !== void 0 ? context.apiHeaders : {}),
+    ...(options?.headers ?? {})
+  };
+  const hasExplicitContentType = Object.keys(headers).some(headerName => {
+    return headerName.toLowerCase() === "content-type";
+  });
+  if (hasBody && !hasExplicitContentType) {
+    headers["Content-Type"] = "application/json";
+  }
+  const response = await fetch(resolvedUrl, {
+    method,
+    headers,
+    body: hasBody ? JSON.stringify(options.body) : void 0
+  });
+  if (!response.ok) {
+    const err = await response.json().catch(() => {
+      return {
+        error: response.statusText
+      };
+    });
+    throw new Error(err.error || `HTTP ${response.status}`);
+  }
+  if (response.status === 204 || response.status === 205) {
+    return void 0;
+  }
+  const contentType = response.headers.get("content-type");
+  if (contentType?.includes("application/json")) {
+    return response.json();
+  }
+  return response.text();
+}, "apiCall");
 var createMcpRouter = /* @__PURE__ */__name((server, options = {}) => {
   const {
     path = "/mcp",
-    sessionIdGenerator
-  } = options;
-  const transport = new import_streamableHttp.StreamableHTTPServerTransport({
     sessionIdGenerator,
-    enableJsonResponse: true
-  });
-  server.connect(transport);
+    apiBaseUrl,
+    getApiHeaders
+  } = options;
+  const isStateful = sessionIdGenerator !== void 0;
+  const needsContext = apiBaseUrl !== void 0 || getApiHeaders !== void 0;
+  let sharedTransport;
+  if (isStateful) {
+    sharedTransport = new import_streamableHttp.StreamableHTTPServerTransport({
+      sessionIdGenerator,
+      enableJsonResponse: true
+    });
+    server.connect(sharedTransport);
+  }
+  let statelessQueue = Promise.resolve();
+  const enqueueStateless = /* @__PURE__ */__name(work => {
+    const result = statelessQueue.then(() => {
+      return work();
+    });
+    statelessQueue = result.catch(() => {});
+    return result;
+  }, "enqueueStateless");
   const router = new import_http_server.Router();
+  const handleWithContext = /* @__PURE__ */__name(async (ctx, body) => {
+    const apiHeaders = getApiHeaders ? getApiHeaders(ctx) : {};
+    const runRequest = /* @__PURE__ */__name(async transport => {
+      await transport.handleRequest(ctx.req, ctx.res, body);
+      ctx.respond = false;
+    }, "runRequest");
+    if (isStateful && sharedTransport) {
+      if (needsContext) {
+        await requestContextStore.run({
+          apiBaseUrl,
+          apiHeaders
+        }, () => {
+          return runRequest(sharedTransport);
+        });
+      } else {
+        await runRequest(sharedTransport);
+      }
+    } else {
+      await enqueueStateless(async () => {
+        const transport = new import_streamableHttp.StreamableHTTPServerTransport({
+          sessionIdGenerator: void 0,
+          enableJsonResponse: true
+        });
+        try {
+          await server.connect(transport);
+          if (needsContext) {
+            await requestContextStore.run({
+              apiBaseUrl,
+              apiHeaders
+            }, () => {
+              return runRequest(transport);
+            });
+          } else {
+            await runRequest(transport);
+          }
+        } finally {
+          await transport.close();
+        }
+      });
+    }
+  }, "handleWithContext");
   router.post(path, async ctx => {
     try {
-      await transport.handleRequest(ctx.req, ctx.res, ctx.request.body);
-      ctx.respond = false;
+      await handleWithContext(ctx, ctx.request.body);
     } catch (error) {
       if (!ctx.res.headersSent) {
         ctx.status = 500;
@@ -66,8 +166,7 @@ var createMcpRouter = /* @__PURE__ */__name((server, options = {}) => {
   });
   router.delete(path, async ctx => {
     try {
-      await transport.handleRequest(ctx.req, ctx.res, void 0);
-      ctx.respond = false;
+      await handleWithContext(ctx);
     } catch (error) {
       if (!ctx.res.headersSent) {
         ctx.status = 500;
@@ -82,6 +181,7 @@ var createMcpRouter = /* @__PURE__ */__name((server, options = {}) => {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Server,
+  apiCall,
   createMcpRouter,
   z
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttoss/http-server-mcp",
-  "version": "0.5.7",
+  "version": "0.6.0",
   "description": "Model Context Protocol (MCP) server integration for @ttoss/http-server",
   "license": "MIT",
   "author": "ttoss",
@@ -25,16 +25,16 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.4",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^3.25.0",
-    "@ttoss/http-server": "^0.5.7"
+    "@ttoss/http-server": "^0.5.8"
   },
   "devDependencies": {
     "@types/koa": "^3.0.1",
     "jest": "^30.3.0",
     "supertest": "^7.1.4",
     "tsup": "^8.5.1",
-    "@ttoss/config": "^1.37.7"
+    "@ttoss/config": "^1.37.8"
   },
   "keywords": [
     "ai",