@ttoss/http-server-mcp 0.28.2 → 0.29.0

package/README.md

@@ -138,6 +138,20 @@ A non-2xx response throws, with the message read off the error body — `{ error
 
 Inside a tool handler the thrown message is what the MCP SDK returns to the client, so it is the whole answer the calling model acts on.
 
+### Using your own HTTP client
+
+A handler that does not use `apiCall` can still reuse its two request-scoped pieces: `getApiHeaders()` returns the headers `getApiHeaders` produced for the current MCP request, and `errorBodyMessage(body)` renders an error body exactly as `apiCall` does.
+
+```typescript
+import { errorBodyMessage, getApiHeaders } from '@ttoss/http-server-mcp';
+
+const response = await fetch(url, { headers: getApiHeaders() });
+if (!response.ok) {
+  const body = await response.json().catch(() => undefined);
+  throw new Error(errorBodyMessage(body) ?? `HTTP ${response.status}`);
+}
+```
+
 ## Authentication
 
 `createMcpRouter` supports OAuth 2.0 Bearer token authentication via the `auth` option. Incoming MCP requests must include a valid `Authorization: Bearer <token>` header — invalid or missing tokens receive a `401 Unauthorized` response. The MCP lifecycle methods `initialize` and `tools/list` are exempt by default so clients can discover the server before authenticating (see [Public methods and discovery](#public-methods-and-discovery)).
@@ -606,6 +620,18 @@ Generic HTTP helper for use inside MCP tool handlers.
 
 **Throws:** `Error` on a non-2xx response, carrying the error body's message (see [Errors](#errors))
 
+### `getApiHeaders()`
+
+Returns a copy of the headers `createMcpRouter`'s `getApiHeaders` option produced for the current MCP request — the same headers `apiCall` injects.
+
+**Returns:** `Record<string, string>` — `{}` outside a request or when `getApiHeaders` is not configured
+
+### `errorBodyMessage(body)`
+
+Reads the message off a REST error body — `{ error: 'text' }` or `{ error: { code?, message? } }` (rendered `code: message`).
+
+**Returns:** `string | undefined` — `undefined` when the body carries no message
+
 ### `getIdentity<T>()`
 
 Returns the verified JWT payload for the current MCP request. Only available inside a tool handler when `auth` is configured. Returns `undefined` when called outside an authenticated context.

package/dist/index.cjs

@@ -24,6 +24,19 @@ var requestContextStore = new node_async_hooks.AsyncLocalStorage();
 var getIdentity = () => {
   return requestContextStore.getStore()?.identity;
 };
+/**
+* Returns the headers `getApiHeaders` produced for the current MCP request —
+* the same headers `apiCall` injects. Use it inside a tool handler that runs
+* its own HTTP client instead of `apiCall`, so caller credentials still reach
+* the upstream API.
+*
+* Returns `{}` outside a request, or when `getApiHeaders` is not configured.
+*/
+var getApiHeaders = () => {
+  return {
+    ...(requestContextStore.getStore()?.apiHeaders ?? {})
+  };
+};
 
 //#endregion
 //#region src/serveMcpRequest.ts
@@ -601,6 +614,18 @@ var readText = value => {
 * The structured one is why this is read rather than taken: an object handed
 * to `new Error()` renders as `[object Object]`, and inside a tool handler
 * that string is the whole answer the calling model acts on.
+*
+* Exported so a tool handler with its own HTTP client renders error bodies
+* exactly as `apiCall` does. Returns `undefined` when the body carries no
+* message.
+*
+* @example
+* ```typescript
+* if (!response.ok) {
+*   const body = await response.json().catch(() => undefined);
+*   throw new Error(errorBodyMessage(body) ?? `HTTP ${response.status}`);
+* }
+* ```
 */
 var errorBodyMessage = body => {
   if (!isRecord(body)) return;
@@ -885,6 +910,8 @@ exports.apiCall = apiCall;
 exports.checkScopes = checkScopes;
 exports.createGatedToolRegistrar = createGatedToolRegistrar;
 exports.createMcpRouter = createMcpRouter;
+exports.errorBodyMessage = errorBodyMessage;
+exports.getApiHeaders = getApiHeaders;
 exports.getIdentity = getIdentity;
 exports.registerAppResource = registerAppResource;
 exports.registerToolFromSchema = registerToolFromSchema;

package/dist/index.d.cts

@@ -674,6 +674,15 @@ declare namespace Application {
  * Omitting the type parameter keeps the return type as `unknown | undefined`.
  */
 declare const getIdentity: <T = unknown>() => T | undefined;
+/**
+ * Returns the headers `getApiHeaders` produced for the current MCP request —
+ * the same headers `apiCall` injects. Use it inside a tool handler that runs
+ * its own HTTP client instead of `apiCall`, so caller credentials still reach
+ * the upstream API.
+ *
+ * Returns `{}` outside a request, or when `getApiHeaders` is not configured.
+ */
+declare const getApiHeaders: () => Record<string, string>;
 //#endregion
 //#region src/registerAppResource.d.ts
 /**
@@ -1191,6 +1200,27 @@ interface McpAuthOptions {
    */
   resourceIndicator?: string | string[];
 }
+/**
+ * The message an error body carries, across the two shapes REST APIs answer
+ * with: `{ error: 'text' }` and `{ error: { code?, message? } }`.
+ *
+ * The structured one is why this is read rather than taken: an object handed
+ * to `new Error()` renders as `[object Object]`, and inside a tool handler
+ * that string is the whole answer the calling model acts on.
+ *
+ * Exported so a tool handler with its own HTTP client renders error bodies
+ * exactly as `apiCall` does. Returns `undefined` when the body carries no
+ * message.
+ *
+ * @example
+ * ```typescript
+ * if (!response.ok) {
+ *   const body = await response.json().catch(() => undefined);
+ *   throw new Error(errorBodyMessage(body) ?? `HTTP ${response.status}`);
+ * }
+ * ```
+ */
+declare const errorBodyMessage: (body: unknown) => string | undefined;
 /**
  * Options for a single `apiCall` request.
  */
@@ -1444,4 +1474,4 @@ interface McpRouterOptions {
  */
 declare const createMcpRouter: (server: McpServer$1, options?: McpRouterOptions) => Router<Application.DefaultState, Application.DefaultContext>;
 //#endregion
-export { ApiCallOptions, CognitoUserPoolConfig, type CreateGatedToolRegistrarOptions, type GatedToolDef, type JsonObjectSchema, McpAuthOptions, McpRouterOptions, McpServer, type RegisterAppResourceParams, type RegisterToolFromSchemaParams, type RegisteredAppResource, type ToolCallContext, type ToolIdentity, type ToolMetaParams, UI_EXTENSION_ID, UI_RESOURCE_MIME_TYPE, type UiResourceCsp, type UiResourceMeta, type UiResourcePermissions, type UiToolVisibility, apiCall, checkScopes, createGatedToolRegistrar, createMcpRouter, getIdentity, registerAppResource, registerToolFromSchema, z };
+export { ApiCallOptions, CognitoUserPoolConfig, type CreateGatedToolRegistrarOptions, type GatedToolDef, type JsonObjectSchema, McpAuthOptions, McpRouterOptions, McpServer, type RegisterAppResourceParams, type RegisterToolFromSchemaParams, type RegisteredAppResource, type ToolCallContext, type ToolIdentity, type ToolMetaParams, UI_EXTENSION_ID, UI_RESOURCE_MIME_TYPE, type UiResourceCsp, type UiResourceMeta, type UiResourcePermissions, type UiToolVisibility, apiCall, checkScopes, createGatedToolRegistrar, createMcpRouter, errorBodyMessage, getApiHeaders, getIdentity, registerAppResource, registerToolFromSchema, z };

package/dist/index.d.mts

@@ -675,6 +675,15 @@ declare namespace Application {
  * Omitting the type parameter keeps the return type as `unknown | undefined`.
  */
 declare const getIdentity: <T = unknown>() => T | undefined;
+/**
+ * Returns the headers `getApiHeaders` produced for the current MCP request —
+ * the same headers `apiCall` injects. Use it inside a tool handler that runs
+ * its own HTTP client instead of `apiCall`, so caller credentials still reach
+ * the upstream API.
+ *
+ * Returns `{}` outside a request, or when `getApiHeaders` is not configured.
+ */
+declare const getApiHeaders: () => Record<string, string>;
 //#endregion
 //#region src/registerAppResource.d.ts
 /**
@@ -1192,6 +1201,27 @@ interface McpAuthOptions {
    */
   resourceIndicator?: string | string[];
 }
+/**
+ * The message an error body carries, across the two shapes REST APIs answer
+ * with: `{ error: 'text' }` and `{ error: { code?, message? } }`.
+ *
+ * The structured one is why this is read rather than taken: an object handed
+ * to `new Error()` renders as `[object Object]`, and inside a tool handler
+ * that string is the whole answer the calling model acts on.
+ *
+ * Exported so a tool handler with its own HTTP client renders error bodies
+ * exactly as `apiCall` does. Returns `undefined` when the body carries no
+ * message.
+ *
+ * @example
+ * ```typescript
+ * if (!response.ok) {
+ *   const body = await response.json().catch(() => undefined);
+ *   throw new Error(errorBodyMessage(body) ?? `HTTP ${response.status}`);
+ * }
+ * ```
+ */
+declare const errorBodyMessage: (body: unknown) => string | undefined;
 /**
  * Options for a single `apiCall` request.
  */
@@ -1445,4 +1475,4 @@ interface McpRouterOptions {
  */
 declare const createMcpRouter: (server: McpServer$1, options?: McpRouterOptions) => Router<Application.DefaultState, Application.DefaultContext>;
 //#endregion
-export { ApiCallOptions, CognitoUserPoolConfig, type CreateGatedToolRegistrarOptions, type GatedToolDef, type JsonObjectSchema, McpAuthOptions, McpRouterOptions, McpServer, type RegisterAppResourceParams, type RegisterToolFromSchemaParams, type RegisteredAppResource, type ToolCallContext, type ToolIdentity, type ToolMetaParams, UI_EXTENSION_ID, UI_RESOURCE_MIME_TYPE, type UiResourceCsp, type UiResourceMeta, type UiResourcePermissions, type UiToolVisibility, apiCall, checkScopes, createGatedToolRegistrar, createMcpRouter, getIdentity, registerAppResource, registerToolFromSchema, z };
+export { ApiCallOptions, CognitoUserPoolConfig, type CreateGatedToolRegistrarOptions, type GatedToolDef, type JsonObjectSchema, McpAuthOptions, McpRouterOptions, McpServer, type RegisterAppResourceParams, type RegisterToolFromSchemaParams, type RegisteredAppResource, type ToolCallContext, type ToolIdentity, type ToolMetaParams, UI_EXTENSION_ID, UI_RESOURCE_MIME_TYPE, type UiResourceCsp, type UiResourceMeta, type UiResourcePermissions, type UiToolVisibility, apiCall, checkScopes, createGatedToolRegistrar, createMcpRouter, errorBodyMessage, getApiHeaders, getIdentity, registerAppResource, registerToolFromSchema, z };

package/dist/index.mjs

@@ -21,6 +21,19 @@ var requestContextStore = new AsyncLocalStorage();
 var getIdentity = () => {
   return requestContextStore.getStore()?.identity;
 };
+/**
+* Returns the headers `getApiHeaders` produced for the current MCP request —
+* the same headers `apiCall` injects. Use it inside a tool handler that runs
+* its own HTTP client instead of `apiCall`, so caller credentials still reach
+* the upstream API.
+*
+* Returns `{}` outside a request, or when `getApiHeaders` is not configured.
+*/
+var getApiHeaders = () => {
+  return {
+    ...(requestContextStore.getStore()?.apiHeaders ?? {})
+  };
+};
 
 //#endregion
 //#region src/serveMcpRequest.ts
@@ -598,6 +611,18 @@ var readText = value => {
 * The structured one is why this is read rather than taken: an object handed
 * to `new Error()` renders as `[object Object]`, and inside a tool handler
 * that string is the whole answer the calling model acts on.
+*
+* Exported so a tool handler with its own HTTP client renders error bodies
+* exactly as `apiCall` does. Returns `undefined` when the body carries no
+* message.
+*
+* @example
+* ```typescript
+* if (!response.ok) {
+*   const body = await response.json().catch(() => undefined);
+*   throw new Error(errorBodyMessage(body) ?? `HTTP ${response.status}`);
+* }
+* ```
 */
 var errorBodyMessage = body => {
   if (!isRecord(body)) return;
@@ -870,4 +895,4 @@ var createMcpRouter = (server, options = {}) => {
 };
 
 //#endregion
-export { McpServer, UI_EXTENSION_ID, UI_RESOURCE_MIME_TYPE, apiCall, checkScopes, createGatedToolRegistrar, createMcpRouter, getIdentity, registerAppResource, registerToolFromSchema, z };
+export { McpServer, UI_EXTENSION_ID, UI_RESOURCE_MIME_TYPE, apiCall, checkScopes, createGatedToolRegistrar, createMcpRouter, errorBodyMessage, getApiHeaders, getIdentity, registerAppResource, registerToolFromSchema, z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttoss/http-server-mcp",
-  "version": "0.28.2",
+  "version": "0.29.0",
   "description": "Model Context Protocol (MCP) server integration for @ttoss/http-server",
   "keywords": [
     "ai",