@prefecthq/fastmcp-ts 1.3.0 → 1.5.0

package/dist/cli/index.cjs

@@ -1172,7 +1172,7 @@ var init_version = __esm({
       async run({ args }) {
         if (args.json) setJsonMode(true);
         const data = {
-          fastmcp: "1.3.0",
+          fastmcp: "1.5.0",
           "mcp-sdk": "2.0.0",
           node: process.version,
           platform: `${process.platform} ${process.arch}`
@@ -33404,7 +33404,7 @@ var init_inspect = __esm({
               // only case Python's inspect supports); over --url/--command the
               // generation is unknowable from the wire.
               generation: mode.kind === "inprocess" ? 2 : null,
-              fastmcpVersion: "1.3.0",
+              fastmcpVersion: "1.5.0",
               mcpVersion: "2.0.0",
               tools: tools2,
               prompts: prompts2,
@@ -46908,7 +46908,7 @@ init_format();
 var main = defineCommand({
   meta: {
     name: "fastmcp",
-    version: "1.3.0",
+    version: "1.5.0",
     description: "FastMCP CLI \u2014 build, run, and manage MCP servers"
   },
   args: {

package/dist/server.d.ts

@@ -1,6 +1,6 @@
 import * as _modelcontextprotocol_server from '@modelcontextprotocol/server';
 import { InputResponses, Server, CacheHint, ServerContext, ServerEventBus, Transport, McpHandlerRequestOptions, CallToolResult, OAuthClientInformationFull, AuthInfo } from '@modelcontextprotocol/server';
-export { InputRequest, InputRequests, InputRequiredResult, InputRequiredSpec, InputResponse, InputResponseView, InputResponses, ServerEventBus, acceptedContent, inputRequired, inputResponse, isInputRequiredResult } from '@modelcontextprotocol/server';
+export { AuthInfo, InputRequest, InputRequests, InputRequiredResult, InputRequiredSpec, InputResponse, InputResponseView, InputResponses, McpHandlerRequestOptions, ServerEventBus, acceptedContent, inputRequired, inputResponse, isInputRequiredResult } from '@modelcontextprotocol/server';
 import { OAuthServerProvider, AuthorizationParams } from '@modelcontextprotocol/server-legacy/auth';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { Readable, Writable } from 'node:stream';
@@ -407,6 +407,35 @@ interface McpContext {
     onClose(callback: () => void): void;
 }
 
+/**
+ * Handler for a custom HTTP route served by the listener `run()` starts.
+ * Owns the whole exchange: no MCP auth, no DNS-rebinding guards, and no CORS
+ * headers run in front of it, and its Response is written back verbatim.
+ */
+type CustomRouteHandler = (request: Request) => Response | Promise<Response>;
+interface CustomRouteConfig {
+    /** Exact request path to serve; the query string is ignored for matching.
+     * Must start with `/`. No patterns, no path parameters. */
+    path: string;
+    /**
+     * HTTP methods served, compared case-insensitively. Default: `['GET']`.
+     * `OPTIONS` is rejected at registration: the global CORS preflight answers
+     * `OPTIONS` before route dispatch, so a route on it would be unreachable.
+     */
+    methods?: string[];
+}
+/** `RunOptions.health` object form. Presence implies enabled. */
+interface HealthOptions {
+    /** Force off with `false`; the object's presence already implies `true`. */
+    enabled?: boolean;
+    /** Request path of the endpoint. Default: `/healthz`. */
+    path?: string;
+    /** Response status code. Default: `200`. */
+    status?: number;
+    /** Response body, served as `text/plain`. Default: `'ok'`. */
+    body?: string;
+}
+
 interface MiddlewareContext<T = unknown> {
     readonly method: string;
     readonly request: T;
@@ -871,11 +900,14 @@ interface FastMCPOptions {
      */
     eventBus?: ServerEventBus;
     /**
-     * DNS-rebinding protection for the HTTP transport: validates the `Host` and
-     * `Origin` request headers (port-agnostic, by hostname) and rejects mismatches
-     * with `403`. Defends localhost servers against a malicious web page whose DNS
-     * rebinds to `127.0.0.1` (MCP transport security best practice). Only affects the
-     * HTTP transport — stdio is unaffected.
+     * DNS-rebinding protection for the HTTP listener started by `run()`: validates
+     * the `Host` and `Origin` request headers (port-agnostic, by hostname) and rejects
+     * mismatches with `403`. Defends localhost servers against a malicious web page
+     * whose DNS rebinds to `127.0.0.1` (MCP transport security best practice).
+     *
+     * This option does not apply to `fetch()`, which has no bind address from which
+     * to infer a trusted host. A framework embedding `fetch()` owns Host/Origin
+     * validation at its HTTP boundary. stdio is unaffected.
      *
      * Default posture (option omitted): protection auto-enables when, and only when,
      * `run()` binds the HTTP server to a loopback host (`127.0.0.1`, `::1`,
@@ -918,6 +950,18 @@ interface RunOptions {
      * is already stateless and is unaffected.
      */
     stateless?: boolean;
+    /**
+     * Health endpoint on the HTTP listener `run()` starts — for Kubernetes
+     * liveness/readiness probes and load-balancer checks. Off unless supplied:
+     * `true` (or any object) enables it with defaults `path: '/healthz'`,
+     * `status: 200`, `body: 'ok'` (`text/plain`); `enabled: false` (or `false`)
+     * forces it off. Served before MCP auth, CORS, and the DNS-rebinding
+     * guards, so probes need no credentials and may send a pod-IP Host header.
+     * Sugar over `customRoute()` — registering your own route on the same path
+     * is a startup error. Ignored on stdio (a malformed value still aborts
+     * startup, like `stateless`) and never served through `fetch()`.
+     */
+    health?: boolean | HealthOptions;
     /** Custom stdin stream for the stdio transport. Defaults to process.stdin. */
     stdin?: Readable;
     /** Custom stdout stream for the stdio transport. Defaults to process.stdout. */
@@ -928,11 +972,31 @@ interface ServerAddress {
     port: number;
     path: string;
 }
+/**
+ * Behavioral hints for a tool (MCP 2025-03-26). Advisory only — clients may use
+ * them for UI/UX and safety decisions (e.g. auto-approving a read-only call); the
+ * server does not enforce them. Per the MCP spec, annotations from an untrusted
+ * server should not be relied upon.
+ */
+interface ToolAnnotations {
+    /** Human-readable title for display. */
+    title?: string;
+    /** The tool does not modify its environment. Default: false. */
+    readOnlyHint?: boolean;
+    /** The tool may perform destructive updates. Only meaningful when readOnlyHint is false. Default: true. */
+    destructiveHint?: boolean;
+    /** Repeated calls with the same arguments have no additional effect. Only meaningful when readOnlyHint is false. Default: false. */
+    idempotentHint?: boolean;
+    /** The tool may interact with an open world of external entities. Default: true. */
+    openWorldHint?: boolean;
+}
 interface ToolConfig {
     name: string;
     /** Human-readable display name shown in UIs. Takes precedence over `name` for display purposes. */
     title?: string;
     description: string;
+    /** Behavioral hints for clients (MCP 2025-03-26). Forwarded verbatim in tools/list. */
+    annotations?: ToolAnnotations;
     /** Standard Schema validator for the tool's input arguments. Used for runtime validation. */
     input?: StandardSchemaV1;
     /**
@@ -970,6 +1034,7 @@ declare class FastMCP {
     private _staticResources;
     private _templateResources;
     private _prompts;
+    private _customRoutes;
     private _promptsPageSize;
     private _middleware;
     private _transforms;
@@ -1082,6 +1147,15 @@ declare class FastMCP {
     tool(config: ToolConfig, handler: (args: Record<string, unknown>) => unknown): void;
     prompt(config: PromptConfig, handler: (args?: Record<string, string>) => unknown): void;
     resource(config: ResourceConfig, handler: (params?: Record<string, string>) => unknown): void;
+    /**
+     * Register a custom HTTP route on the listener `run()` starts — e.g. a
+     * Kubernetes liveness/readiness probe. The handler owns the whole exchange:
+     * no MCP auth, no DNS-rebinding guards, and no CORS headers run in front of
+     * it. Matching is exact-path (query string ignored); methods default to GET.
+     * Routes never serve on stdio or through `fetch()` — a framework embedding
+     * `fetch()` owns its own routing (same posture as `dnsRebinding`).
+     */
+    customRoute(config: CustomRouteConfig, handler: CustomRouteHandler): void;
     _removeTool(name: string): boolean;
     _removeResource(uri: string): boolean;
     _removePrompt(name: string): boolean;
@@ -1249,6 +1323,19 @@ declare class FastMCP {
      */
     get isRunning(): boolean;
     connect(transport: Transport): Promise<void>;
+    /**
+     * Serve an MCP request through a web-standard, fetch-native HTTP entrypoint.
+     *
+     * This entrypoint is always stateless and does not require `run()`: legacy
+     * (2025-era) requests use a fresh server instance per request, while modern
+     * (2026-07-28) requests share the instance's modern handler and event bus.
+     * Authentication is deliberately external — `options.authInfo` is trusted and
+     * passed unchanged into the protocol handler, where it is exposed as `ctx.auth`.
+     * The embedding framework also owns Host/Origin validation and should abort its
+     * carrying requests during shutdown; stateless legacy response streams follow
+     * that request lifecycle, while `close()` terminates modern exchanges and streams.
+     */
+    fetch(request: Request, options?: McpHandlerRequestOptions): Promise<Response>;
     /**
      * Modern-era (2026-07-28) in-process fetch entrypoint — the `McpServerLike`
      * duck-type hook `fastmcp-ts/client`'s `Client` looks for when a caller pins
@@ -1265,9 +1352,9 @@ declare class FastMCP {
     /** Lazily builds the modern (2026-07-28) HTTP handler. One per FastMCP instance;
      * builds a fresh Server (via _makeServer) per request, matching createMcpHandler's
      * per-request-factory model. Modern-only (legacy: 'reject') — legacy (2025-era)
-     * traffic is routed to the existing sessionful transport by _dispatchHttp instead
-     * of createMcpHandler's own stateless legacy fallback, so session state and the
-     * legacy server-initiated-request shim keep working for 2025-era clients. */
+     * traffic is routed separately: to the existing sessionful transport by
+     * _dispatchHttp, or to the stateless fallback by fetch(). This preserves the
+     * session state and server-initiated-request shim for run()'s default HTTP path. */
     private _getModernHandler;
     /** Lazily builds the stateless legacy (2025-era) HTTP handler. One per FastMCP
      * instance, mirroring _getModernHandler's per-instance, per-request-factory model.
@@ -1276,8 +1363,9 @@ declare class FastMCP {
      * built with `sessionIdGenerator: undefined`, and answers GET and DELETE with 405
      * because both are session operations that mean nothing per request.
      *
-     * Only reachable when `_stateless` is on. The sessionful transport in
-     * _dispatchLegacyHttp is untouched and still serves every other deployment. */
+     * Used unconditionally by fetch(), and by run() only when `_stateless` is on.
+     * The sessionful transport in _dispatchLegacyHttp is untouched and remains the
+     * default for listener-based HTTP deployments. */
     private _getStatelessLegacyHandler;
     /**
      * Dual-era HTTP dispatch shared by the OAuth and non-OAuth serve paths. Assumes CORS
@@ -1753,4 +1841,4 @@ declare class FormInput {
     constructor(options: FormInputOptions);
 }
 
-export { type AccessToken, Approval, Area, type AuthCheck, AuthorizationError, type BackendToolConfig, Badge, Bar, type BrowserPermissions, Button, type CacheKeyFn, CachingMiddleware, CancellationMiddleware, type CatalogEntry, Choice, Column, type CompleteCallback, type CompletionContext, type CompletionResult, type Component, type ComponentFn, type CspPolicy, type ElicitationResult, type ElicitationSchema, type EntrypointConfig, ErrorNormalizationMiddleware, FastMCP, FastMCPApp, type FastMCPAppOptions, type FastMCPOptions, File, type FileHandle, type FileStorageAdapter, FileUpload, type FileUploadOptions, FilterTransform, ForEach, FormInput, type FormInputOptions, GenerativeUI, Grid, type HTTPRoute, type HttpMethod, type HttpRequestContext, If, type IfNode, Image, Input, Line, type LogLevel, LoggingMiddleware, type MCPType, type McpContext, type Middleware, type MiddlewareContext, NamespaceTransform, type Next, type OAuthConfig, type OAuthProviderOptions, type OAuthProxyOptions, type OpenAPIClientOptions, type OpenAPIComponent, type OpenAPIResourceComponent, type OpenAPIResourceTemplateComponent, type OpenAPIServerOptions, type OpenAPIToolComponent, type ParameterInfo, Pie, type PromptArgument, type PromptConfig, type PromptContent, type PromptMessage, PromptResult, type PromptView, PromptsAsTools, type ProxyTransport, RateLimitingMiddleware, type RequestBodyInfo, type RequestVerifier, type ResourceAnnotations, type ResourceConfig, ResourceResult, type ResourceUiMeta, type ResourceView, ResourcesAsTools, type ResponseInfo, type Root, type RouteMap, type RouteMapFn, Row, type RunOptions, Rx, type SamplingMessage, type SamplingParams, type SamplingResult, Select, type ServerAddress, SizeLimitingMiddleware, type SynthesizedTool, Table, Text, type TokenVerifier, type ToolConfig, ToolResult, type ToolView, type Transform, type UiToolMeta, VersionFilter, type Visibility, actionRef, createOpenAPIServer, createProxy, debugTokenVerifier, forwardableHeaders, introspectionVerifier, jwtVerifier, multiAuth, oauthProvider, oauthProxy, redescribeTool, renameTool, requireScopes, staticTokenVerifier };
+export { type AccessToken, Approval, Area, type AuthCheck, AuthorizationError, type BackendToolConfig, Badge, Bar, type BrowserPermissions, Button, type CacheKeyFn, CachingMiddleware, CancellationMiddleware, type CatalogEntry, Choice, Column, type CompleteCallback, type CompletionContext, type CompletionResult, type Component, type ComponentFn, type CspPolicy, type CustomRouteConfig, type CustomRouteHandler, type ElicitationResult, type ElicitationSchema, type EntrypointConfig, ErrorNormalizationMiddleware, FastMCP, FastMCPApp, type FastMCPAppOptions, type FastMCPOptions, File, type FileHandle, type FileStorageAdapter, FileUpload, type FileUploadOptions, FilterTransform, ForEach, FormInput, type FormInputOptions, GenerativeUI, Grid, type HTTPRoute, type HealthOptions, type HttpMethod, type HttpRequestContext, If, type IfNode, Image, Input, Line, type LogLevel, LoggingMiddleware, type MCPType, type McpContext, type Middleware, type MiddlewareContext, NamespaceTransform, type Next, type OAuthConfig, type OAuthProviderOptions, type OAuthProxyOptions, type OpenAPIClientOptions, type OpenAPIComponent, type OpenAPIResourceComponent, type OpenAPIResourceTemplateComponent, type OpenAPIServerOptions, type OpenAPIToolComponent, type ParameterInfo, Pie, type PromptArgument, type PromptConfig, type PromptContent, type PromptMessage, PromptResult, type PromptView, PromptsAsTools, type ProxyTransport, RateLimitingMiddleware, type RequestBodyInfo, type RequestVerifier, type ResourceAnnotations, type ResourceConfig, ResourceResult, type ResourceUiMeta, type ResourceView, ResourcesAsTools, type ResponseInfo, type Root, type RouteMap, type RouteMapFn, Row, type RunOptions, Rx, type SamplingMessage, type SamplingParams, type SamplingResult, Select, type ServerAddress, SizeLimitingMiddleware, type SynthesizedTool, Table, Text, type TokenVerifier, type ToolAnnotations, type ToolConfig, ToolResult, type ToolView, type Transform, type UiToolMeta, VersionFilter, type Visibility, actionRef, createOpenAPIServer, createProxy, debugTokenVerifier, forwardableHeaders, introspectionVerifier, jwtVerifier, multiAuth, oauthProvider, oauthProxy, redescribeTool, renameTool, requireScopes, staticTokenVerifier };

package/dist/server.js

@@ -281,6 +281,106 @@ function createContext(server, sdkCtx, auth, sessionState, requestStateCodec, st
   };
 }
 
+// src/server/customRoutes.ts
+import { Readable } from "stream";
+var CustomRouteRegistry = class {
+  _routes = /* @__PURE__ */ new Map();
+  register(config, handler) {
+    const path = config?.path;
+    if (typeof path !== "string" || !path.startsWith("/")) {
+      throw new Error(`customRoute path must be a string starting with "/", got: ${JSON.stringify(path)}`);
+    }
+    const methods = (config.methods ?? ["GET"]).map((m) => m.toUpperCase());
+    if (methods.length === 0) {
+      throw new Error(`customRoute ${path}: methods must not be empty (omit it for the GET default)`);
+    }
+    if (methods.includes("OPTIONS")) {
+      throw new Error(
+        `customRoute ${path}: OPTIONS cannot be routed \u2014 the CORS preflight handler answers OPTIONS before route dispatch`
+      );
+    }
+    if (this._routes.has(path)) {
+      throw new Error(`customRoute already registered for path ${path}`);
+    }
+    this._routes.set(path, { methods: new Set(methods), handler });
+  }
+  /** Throws when a registered route sits on the MCP endpoint path. Called at HTTP startup. */
+  assertNoMcpCollision(mcpPath) {
+    if (this._routes.has(mcpPath)) {
+      throw new Error(
+        `customRoute path ${mcpPath} collides with the MCP endpoint path; move the route or the MCP \`path\``
+      );
+    }
+  }
+  /** Match a request path + method. OPTIONS never matches (preflight owns it). */
+  match(pathname, method) {
+    const route = this._routes.get(pathname);
+    if (!route) return null;
+    const upper = method.toUpperCase();
+    if (upper === "OPTIONS") return null;
+    if (route.methods.has(upper)) return { kind: "handler", handler: route.handler };
+    return { kind: "method-mismatch", allow: [...route.methods].join(", ") };
+  }
+  paths() {
+    return [...this._routes.keys()];
+  }
+  get size() {
+    return this._routes.size;
+  }
+};
+var NULL_BODY_STATUSES = /* @__PURE__ */ new Set([101, 204, 205, 304]);
+function resolveHealth(health) {
+  if (health === void 0 || health === false) return null;
+  if (health === true) return { path: "/healthz", status: 200, body: "ok" };
+  if (typeof health !== "object" || health === null) {
+    throw new Error(`Invalid health option: expected boolean or object, got ${typeof health}`);
+  }
+  if (health.enabled === false) return null;
+  const path = health.path ?? "/healthz";
+  if (typeof path !== "string" || !path.startsWith("/")) {
+    throw new Error(`Invalid health.path: must be a string starting with "/", got: ${JSON.stringify(health.path)}`);
+  }
+  const status = health.status ?? 200;
+  if (!Number.isInteger(status) || status < 100 || status > 599) {
+    throw new Error(`Invalid health.status: must be an integer HTTP status code, got: ${JSON.stringify(health.status)}`);
+  }
+  const body = health.body ?? "ok";
+  if (typeof body !== "string") {
+    throw new Error(`Invalid health.body: must be a string, got: ${typeof health.body}`);
+  }
+  if (body !== "" && NULL_BODY_STATUSES.has(status)) {
+    throw new Error(
+      `Invalid health config: status ${status} cannot carry a response body (the fetch spec forbids one on 101/204/205/304); set body: '' or choose a different status`
+    );
+  }
+  return { path, status, body };
+}
+async function serveCustomRouteNode(handler, req, res) {
+  const { toWebRequest } = await import("@modelcontextprotocol/node");
+  let response;
+  try {
+    response = await handler(await toWebRequest(req));
+  } catch (error) {
+    console.error("[fastmcp] custom route handler failed:", error);
+    res.writeHead(500, { "Content-Type": "application/json" }).end(JSON.stringify({ error: "Internal Server Error" }));
+    return;
+  }
+  res.writeHead(response.status, Object.fromEntries(response.headers));
+  if (response.body) {
+    const stream = Readable.fromWeb(response.body);
+    stream.on("error", (error) => {
+      console.error("[fastmcp] custom route response stream failed:", error);
+      res.destroy();
+    });
+    stream.pipe(res);
+  } else {
+    res.end();
+  }
+}
+function writeMethodNotAllowed(res, allow) {
+  res.writeHead(405, { Allow: allow, "Content-Type": "application/json" }).end(JSON.stringify({ error: "Method Not Allowed" }));
+}
+
 // src/server/env.ts
 var TRUE_VALUES = /* @__PURE__ */ new Set(["1", "true", "yes", "on"]);
 var FALSE_VALUES = /* @__PURE__ */ new Set(["0", "false", "no", "off"]);
@@ -952,6 +1052,7 @@ var FastMCP = class {
   _staticResources = /* @__PURE__ */ new Map();
   _templateResources = /* @__PURE__ */ new Map();
   _prompts = /* @__PURE__ */ new Map();
+  _customRoutes = new CustomRouteRegistry();
   _promptsPageSize;
   _middleware;
   _transforms;
@@ -1135,6 +1236,7 @@ var FastMCP = class {
                 description: entry.description,
                 inputSchema,
                 ...outputSchema ? { outputSchema } : {},
+                ...t.annotations ? { annotations: t.annotations } : {},
                 ...uiMeta ? { _meta: { ui: uiMeta } } : {}
               };
             })
@@ -1748,6 +1850,17 @@ var FastMCP = class {
     this._notifyResourceListChanged();
     for (const cb of this._resourceRegisteredCallbacks) cb(registered);
   }
+  /**
+   * Register a custom HTTP route on the listener `run()` starts — e.g. a
+   * Kubernetes liveness/readiness probe. The handler owns the whole exchange:
+   * no MCP auth, no DNS-rebinding guards, and no CORS headers run in front of
+   * it. Matching is exact-path (query string ignored); methods default to GET.
+   * Routes never serve on stdio or through `fetch()` — a framework embedding
+   * `fetch()` owns its own routing (same posture as `dnsRebinding`).
+   */
+  customRoute(config, handler) {
+    this._customRoutes.register(config, handler);
+  }
   _removeTool(name) {
     if (!this._tools.has(name)) return false;
     this._tools.delete(name);
@@ -2111,6 +2224,29 @@ var FastMCP = class {
     this._primaryServer = this._makeServer();
     await this._primaryServer.connect(transport);
   }
+  /**
+   * Serve an MCP request through a web-standard, fetch-native HTTP entrypoint.
+   *
+   * This entrypoint is always stateless and does not require `run()`: legacy
+   * (2025-era) requests use a fresh server instance per request, while modern
+   * (2026-07-28) requests share the instance's modern handler and event bus.
+   * Authentication is deliberately external — `options.authInfo` is trusted and
+   * passed unchanged into the protocol handler, where it is exposed as `ctx.auth`.
+   * The embedding framework also owns Host/Origin validation and should abort its
+   * carrying requests during shutdown; stateless legacy response streams follow
+   * that request lifecycle, while `close()` terminates modern exchanges and streams.
+   */
+  async fetch(request, options) {
+    if (request.method.toUpperCase() === "POST" && !isJsonContentType(request.headers.get("content-type"))) {
+      return new Response(
+        JSON.stringify({ error: "Unsupported Media Type: expected application/json" }),
+        { status: 415, headers: { "Content-Type": "application/json" } }
+      );
+    }
+    const legacy = await isLegacyRequest(request, options?.parsedBody);
+    if (legacy) return this._getStatelessLegacyHandler()(request, options);
+    return this._getModernHandler().fetch(request, options);
+  }
   /**
    * Modern-era (2026-07-28) in-process fetch entrypoint — the `McpServerLike`
    * duck-type hook `fastmcp-ts/client`'s `Client` looks for when a caller pins
@@ -2136,6 +2272,7 @@ var FastMCP = class {
     const host = options?.host ?? process.env.MCP_HOST ?? "127.0.0.1";
     const path = options?.path ?? process.env.MCP_PATH ?? "/mcp";
     this._stateless = options?.stateless ?? envBool("FASTMCP_STATELESS_HTTP") ?? false;
+    const resolvedHealth = resolveHealth(options?.health);
     if (transport === "stdio") {
       const { StdioServerTransport, serveStdio } = await import("@modelcontextprotocol/server/stdio");
       const stdioTransport = new StdioServerTransport(options?.stdin, options?.stdout);
@@ -2148,18 +2285,36 @@ var FastMCP = class {
         },
         { transport: stdioTransport }
       );
-    } else if (this._oauth) {
-      await this._runHttpOAuth(port, host, path);
     } else {
-      await this._runHttpSimple(port, host, path);
+      if (resolvedHealth) {
+        this._customRoutes.register(
+          { path: resolvedHealth.path },
+          () => (
+            // An empty body maps to a null Response body (no Content-Type either): the
+            // fetch spec forbids any body, even '', on 101/204/205/304, and resolveHealth
+            // already rejected a non-empty body on those statuses — so branching on the
+            // body alone is enough to keep this call from throwing.
+            resolvedHealth.body === "" ? new Response(null, { status: resolvedHealth.status }) : new Response(resolvedHealth.body, {
+              status: resolvedHealth.status,
+              headers: { "Content-Type": "text/plain" }
+            })
+          )
+        );
+      }
+      this._customRoutes.assertNoMcpCollision(path);
+      if (this._oauth) {
+        await this._runHttpOAuth(port, host, path);
+      } else {
+        await this._runHttpSimple(port, host, path);
+      }
     }
   }
   /** Lazily builds the modern (2026-07-28) HTTP handler. One per FastMCP instance;
    * builds a fresh Server (via _makeServer) per request, matching createMcpHandler's
    * per-request-factory model. Modern-only (legacy: 'reject') — legacy (2025-era)
-   * traffic is routed to the existing sessionful transport by _dispatchHttp instead
-   * of createMcpHandler's own stateless legacy fallback, so session state and the
-   * legacy server-initiated-request shim keep working for 2025-era clients. */
+   * traffic is routed separately: to the existing sessionful transport by
+   * _dispatchHttp, or to the stateless fallback by fetch(). This preserves the
+   * session state and server-initiated-request shim for run()'s default HTTP path. */
   _getModernHandler() {
     if (!this._modernHandler) {
       this._modernHandler = createMcpHandler(() => this._makeServer(/* @__PURE__ */ new Map(), { modern: true }), {
@@ -2176,8 +2331,9 @@ var FastMCP = class {
    * built with `sessionIdGenerator: undefined`, and answers GET and DELETE with 405
    * because both are session operations that mean nothing per request.
    *
-   * Only reachable when `_stateless` is on. The sessionful transport in
-   * _dispatchLegacyHttp is untouched and still serves every other deployment. */
+   * Used unconditionally by fetch(), and by run() only when `_stateless` is on.
+   * The sessionful transport in _dispatchLegacyHttp is untouched and remains the
+   * default for listener-based HTTP deployments. */
   _getStatelessLegacyHandler() {
     if (!this._statelessLegacyHandler) {
       this._statelessLegacyHandler = legacyStatelessFallback(
@@ -2285,6 +2441,12 @@ var FastMCP = class {
     const { requireBearerAuth } = await import("@modelcontextprotocol/server-legacy/auth");
     const oauth = this._oauth;
     const app = express();
+    app.use((req, res, next) => {
+      const match = this._customRoutes.match(req.path, req.method ?? "");
+      if (!match) return next();
+      if (match.kind === "method-mismatch") return writeMethodNotAllowed(res, match.allow);
+      void serveCustomRouteNode(match.handler, req, res);
+    });
     const httpServer = await new Promise((resolve, reject) => {
       const srv = app.listen(port, host, () => resolve(srv));
       srv.on("error", reject);
@@ -2328,7 +2490,14 @@ var FastMCP = class {
         res.writeHead(204, corsHeaders).end();
         return;
       }
-      if (req.url?.split("?")[0] !== path) {
+      const pathname = req.url?.split("?")[0] ?? "";
+      const routeMatch = this._customRoutes.match(pathname, req.method ?? "");
+      if (routeMatch) {
+        if (routeMatch.kind === "method-mismatch") writeMethodNotAllowed(res, routeMatch.allow);
+        else await serveCustomRouteNode(routeMatch.handler, req, res);
+        return;
+      }
+      if (pathname !== path) {
         res.writeHead(404).end();
         return;
       }
@@ -2986,7 +3155,7 @@ var OPENAPI_SPECIFIC_FIELDS = [
 var RECURSIVE_MAP_FIELDS = ["properties", "$defs", "$definitions"];
 var RECURSIVE_SINGLE_FIELDS = ["items", "additionalProperties", "not"];
 var RECURSIVE_LIST_FIELDS = ["allOf", "anyOf", "oneOf"];
-function convertOpenAPISchemaToJsonSchema(schema, openapiVersion) {
+function convertOpenAPISchemaToJsonSchema(schema, openapiVersion, options = {}) {
   if (!isPlainObject(schema)) return schema;
   let result = { ...schema };
   if (openapiVersion?.startsWith("3.0")) {
@@ -3000,13 +3169,16 @@ function convertOpenAPISchemaToJsonSchema(schema, openapiVersion) {
   for (const field of OPENAPI_SPECIFIC_FIELDS) {
     delete result[field];
   }
+  if (options.removeReadOnly === true || options.removeWriteOnly === true) {
+    result = filterPropertiesByAccess(result, options);
+  }
   for (const field of RECURSIVE_MAP_FIELDS) {
     const map = result[field];
     if (isPlainObject(map)) {
       result[field] = Object.fromEntries(
         Object.entries(map).map(([name, sub]) => [
           name,
-          isPlainObject(sub) ? convertOpenAPISchemaToJsonSchema(sub, openapiVersion) : sub
+          isPlainObject(sub) ? convertOpenAPISchemaToJsonSchema(sub, openapiVersion, options) : sub
         ])
       );
     }
@@ -3014,14 +3186,14 @@ function convertOpenAPISchemaToJsonSchema(schema, openapiVersion) {
   for (const field of RECURSIVE_SINGLE_FIELDS) {
     const sub = result[field];
     if (isPlainObject(sub)) {
-      result[field] = convertOpenAPISchemaToJsonSchema(sub, openapiVersion);
+      result[field] = convertOpenAPISchemaToJsonSchema(sub, openapiVersion, options);
     }
   }
   for (const field of RECURSIVE_LIST_FIELDS) {
     const list = result[field];
     if (Array.isArray(list)) {
       result[field] = list.map(
-        (item) => isPlainObject(item) ? convertOpenAPISchemaToJsonSchema(item, openapiVersion) : item
+        (item) => isPlainObject(item) ? convertOpenAPISchemaToJsonSchema(item, openapiVersion, options) : item
       );
     }
   }
@@ -3082,6 +3254,28 @@ function requireDiscriminatorProperty(schema) {
   }
   return result;
 }
+function filterPropertiesByAccess(schema, options) {
+  const properties = schema.properties;
+  if (!isPlainObject(properties)) return schema;
+  const removed = /* @__PURE__ */ new Set();
+  for (const [name, prop] of Object.entries(properties)) {
+    if (!isPlainObject(prop)) continue;
+    if (options.removeReadOnly === true && truthy(prop.readOnly) || options.removeWriteOnly === true && truthy(prop.writeOnly)) {
+      removed.add(name);
+    }
+  }
+  if (removed.size === 0) return schema;
+  const result = { ...schema };
+  result.properties = Object.fromEntries(
+    Object.entries(properties).filter(([name]) => !removed.has(name))
+  );
+  if (Array.isArray(result.required)) {
+    result.required = result.required.filter(
+      (name) => typeof name !== "string" || !removed.has(name)
+    );
+  }
+  return result;
+}
 
 // src/server/openapi/schemas.ts
 var EXTERNAL_REF_MESSAGE = "External or non-local reference not supported";
@@ -3351,7 +3545,9 @@ function combineSchemasAndMapParams(route) {
     result.$defs = route.requestSchemas;
   }
   if (route.openapiVersion?.startsWith("3")) {
-    result = convertOpenAPISchemaToJsonSchema(result, route.openapiVersion);
+    result = convertOpenAPISchemaToJsonSchema(result, route.openapiVersion, {
+      removeReadOnly: true
+    });
   }
   return [result, parameterMap];
 }
@@ -3404,7 +3600,9 @@ function extractOutputSchemaFromResponses(responses, schemaDefinitions, openapiV
     }
   }
   if (openapiVersion?.startsWith("3")) {
-    outputSchema = convertOpenAPISchemaToJsonSchema(outputSchema, openapiVersion);
+    outputSchema = convertOpenAPISchemaToJsonSchema(outputSchema, openapiVersion, {
+      removeWriteOnly: true
+    });
   }
   if (outputSchema.type !== "object") {
     outputSchema = {
@@ -3423,7 +3621,9 @@ function extractOutputSchemaFromResponses(responses, schemaDefinitions, openapiV
     }
     if (openapiVersion?.startsWith("3")) {
       for (const name of Object.keys(processedDefs)) {
-        processedDefs[name] = convertOpenAPISchemaToJsonSchema(processedDefs[name], openapiVersion);
+        processedDefs[name] = convertOpenAPISchemaToJsonSchema(processedDefs[name], openapiVersion, {
+          removeWriteOnly: true
+        });
       }
     }
     outputSchema.$defs = processedDefs;