feat(hono): add mcp() middleware to serve MCP in one call

Adds mcp(factory, options?) — a single Hono MiddlewareHandler that serves
MCP over Streamable HTTP with JSON body parsing and localhost
DNS-rebinding / origin protection applied (the same defaults as
createMcpHonoApp), so it can be mounted on a route you already own:

  app.all('/mcp', mcp(() => new McpServer({ name: '...', version: '...' })))

It builds on createMcpHandler rather than a raw transport, so the endpoint
serves the modern 2026-07-28 protocol and falls back to stateless 2025-era
serving, with a fresh server per request. The inner app is self-contained,
so only the raw request is forwarded to it — this also avoids
c.executionCtx, which throws off Cloudflare Workers.

Feature and API shape inspired by yusukebe's mcp-server-hono-middleware.

- packages/middleware/hono/src/hono.ts: mcp() + McpMiddlewareOptions
- packages/middleware/hono/test/mcp.test.ts: real-client tests over both
  the legacy (2025) and modern (2026-07-28) paths, plus protection tests
- README + docs/serving/hono.md: feature mcp() as the preferred path,
  keep createMcpHonoApp + createMcpHandler as the own-your-routing form

Author: MathurAditya724

docs/serving/hono.md

@@ -9,39 +9,71 @@ npm install @modelcontextprotocol/server @modelcontextprotocol/hono hono
 
 ## Mount the handler
 
-`createMcpHandler` turns a server factory into a web-standard HTTP handler, and `handler.fetch` takes the `Request` a Hono route already holds as `c.req.raw` — no Node adapter. `createMcpHonoApp` is `new Hono()` with JSON body parsing and DNS rebinding protection already applied.
+`mcp(factory)` is the shortest path: it returns a single Hono middleware that serves MCP over Streamable HTTP, with JSON body parsing and DNS rebinding protection already applied. It builds on `createMcpHandler`, so the endpoint serves the modern 2026-07-28 protocol and falls back to stateless 2025-era serving — a fresh `McpServer` from your factory backs every request. Mount it on a route you already own.
+
+```ts source="../../examples/guides/serving/hono.examples.ts#mcp_mount"
+import { mcp } from '@modelcontextprotocol/hono';
+import { McpServer } from '@modelcontextprotocol/server';
+import { Hono } from 'hono';
+import * as z from 'zod/v4';
+
+const app = new Hono();
+app.all(
+    '/mcp',
+    mcp(() => {
+        const server = new McpServer({ name: 'notes', version: '1.0.0' });
+        server.registerTool(
+            'add-note',
+            { description: 'Append a note', inputSchema: z.object({ text: z.string() }) },
+            async ({ text }) => ({
+                content: [{ type: 'text', text: `Saved: ${text}` }]
+            })
+        );
+        return server;
+    })
+);
+
+export default app;
+```
+
+`app` is an ordinary Hono app, and `export default app` is the `{ fetch }` object Cloudflare Workers, Deno, and Bun serve directly; on Node, pass `app` to `serve` from `@hono/node-server`.
+
+### Wire the handler and route yourself
+
+When you want to own the routing — mount multiple endpoints, add your own middleware, or pass `authInfo` per request — drop down to `createMcpHandler` + `createMcpHonoApp` (which is what `mcp()` composes for you). `createMcpHandler` turns the same factory into a web-standard HTTP handler, and `handler.fetch` takes the `Request` a Hono route already holds as `c.req.raw` — no Node adapter. `createMcpHonoApp` is `new Hono()` with the same JSON body parsing and DNS rebinding protection applied.
 
 ```ts source="../../examples/guides/serving/hono.examples.ts#createMcpHonoApp_mount"
 import { createMcpHonoApp } from '@modelcontextprotocol/hono';
-import { createMcpHandler, McpServer } from '@modelcontextprotocol/server';
+import { createMcpHandler } from '@modelcontextprotocol/server';
 import type { Context } from 'hono';
-import * as z from 'zod/v4';
 
 const handler = createMcpHandler(() => {
-    const server = new McpServer({ name: 'notes', version: '1.0.0' });
-    server.registerTool('add-note', { description: 'Append a note', inputSchema: z.object({ text: z.string() }) }, async ({ text }) => ({
-        content: [{ type: 'text', text: `Saved: ${text}` }]
-    }));
-    return server;
+    const factoryServer = new McpServer({ name: 'notes', version: '1.0.0' });
+    factoryServer.registerTool(
+        'add-note',
+        { description: 'Append a note', inputSchema: z.object({ text: z.string() }) },
+        async ({ text }) => ({
+            content: [{ type: 'text', text: `Saved: ${text}` }]
+        })
+    );
+    return factoryServer;
 });
 
-const app = createMcpHonoApp();
-app.all('/mcp', (c: Context) => handler.fetch(c.req.raw, { parsedBody: c.get('parsedBody') }));
-
-export default app;
+const factoryApp = createMcpHonoApp();
+factoryApp.all('/mcp', (c: Context) => handler.fetch(c.req.raw, { parsedBody: c.get('parsedBody') }));
 ```
 
-`app` is an ordinary Hono app, and `export default app` is the `{ fetch }` object Cloudflare Workers, Deno, and Bun serve directly; on Node, pass `app` to `serve` from `@hono/node-server`. The factory runs once per request, so a fresh `McpServer` serves every call: [Serve over HTTP](./http.md#understand-the-per-request-factory) covers that model.
+The factory runs once per request, so a fresh `McpServer` serves every call: [Serve over HTTP](./http.md#understand-the-per-request-factory) covers that model.
 
 ::: tip
 Keep the explicit `c: Context` annotation: on an inferred callback context `c.get`'s key parameter narrows to `never` and `c.get('parsedBody')` does not compile.
 :::
 
 ## Protect against DNS rebinding
 
-A malicious page can DNS-rebind its own domain to `127.0.0.1` and reach a localhost server as if it were same-origin. `createMcpHonoApp` validates the `Host` and `Origin` headers against that: with the default `127.0.0.1` bind (and `localhost` / `::1`), a request carrying a non-localhost value gets `403` before your handler runs.
+A malicious page can DNS-rebind its own domain to `127.0.0.1` and reach a localhost server as if it were same-origin. `mcp()` and `createMcpHonoApp` both validate the `Host` and `Origin` headers against that: with the default `127.0.0.1` bind (and `localhost` / `::1`), a request carrying a non-localhost value gets `403` before your handler runs.
 
-Binding to all interfaces drops that default — name the hosts you serve instead.
+Binding to all interfaces drops that default — name the hosts you serve instead. `mcp()` takes the same `host` / `allowedHosts` / `allowedOrigins` options.
 
 ```ts source="../../examples/guides/serving/hono.examples.ts#createMcpHonoApp_allowedHosts"
 const publicApp = createMcpHonoApp({ host: '0.0.0.0', allowedHosts: ['api.example.com'] });
@@ -82,8 +114,8 @@ data: {"result":{"tools":[{"name":"add-note","description":"Append a note","inpu
 
 ## Recap
 
-- One install line, one file: `createMcpHonoApp()` plus one `app.all('/mcp', …)` route over `createMcpHandler(factory).fetch`.
+- `mcp(factory)` is one Hono middleware — `app.all('/mcp', mcp(factory))` serves the whole endpoint (modern + legacy) with body parsing and Host/Origin validation applied.
+- Want to own the routing? Use `createMcpHonoApp()` plus one `app.all('/mcp', …)` route over `createMcpHandler(factory).fetch` — the same pieces `mcp()` composes.
 - Hono hands `c.req.raw` straight to `handler.fetch` — no Node adapter.
-- A fresh server instance from your factory serves every request.
 - The default `127.0.0.1` bind validates `Host` and `Origin`; pass `allowedHosts` when binding to `0.0.0.0`.
 - `authInfo` and `parsedBody` travel in `handler.fetch`'s second argument; handlers read auth as `ctx.http.authInfo`.

examples/guides/serving/hono.examples.ts

@@ -15,24 +15,50 @@
 /* eslint-disable no-console */
 import type { AuthInfo } from '@modelcontextprotocol/server';
 
+//#region mcp_mount
+import { mcp } from '@modelcontextprotocol/hono';
+import { McpServer } from '@modelcontextprotocol/server';
+import { Hono } from 'hono';
+import * as z from 'zod/v4';
+
+const app = new Hono();
+app.all(
+    '/mcp',
+    mcp(() => {
+        const server = new McpServer({ name: 'notes', version: '1.0.0' });
+        server.registerTool(
+            'add-note',
+            { description: 'Append a note', inputSchema: z.object({ text: z.string() }) },
+            async ({ text }) => ({
+                content: [{ type: 'text', text: `Saved: ${text}` }]
+            })
+        );
+        return server;
+    })
+);
+
+export default app;
+//#endregion mcp_mount
+
 //#region createMcpHonoApp_mount
 import { createMcpHonoApp } from '@modelcontextprotocol/hono';
-import { createMcpHandler, McpServer } from '@modelcontextprotocol/server';
+import { createMcpHandler } from '@modelcontextprotocol/server';
 import type { Context } from 'hono';
-import * as z from 'zod/v4';
 
 const handler = createMcpHandler(() => {
-    const server = new McpServer({ name: 'notes', version: '1.0.0' });
-    server.registerTool('add-note', { description: 'Append a note', inputSchema: z.object({ text: z.string() }) }, async ({ text }) => ({
-        content: [{ type: 'text', text: `Saved: ${text}` }]
-    }));
-    return server;
+    const factoryServer = new McpServer({ name: 'notes', version: '1.0.0' });
+    factoryServer.registerTool(
+        'add-note',
+        { description: 'Append a note', inputSchema: z.object({ text: z.string() }) },
+        async ({ text }) => ({
+            content: [{ type: 'text', text: `Saved: ${text}` }]
+        })
+    );
+    return factoryServer;
 });
 
-const app = createMcpHonoApp();
-app.all('/mcp', (c: Context) => handler.fetch(c.req.raw, { parsedBody: c.get('parsedBody') }));
-
-export default app;
+const factoryApp = createMcpHonoApp();
+factoryApp.all('/mcp', (c: Context) => handler.fetch(c.req.raw, { parsedBody: c.get('parsedBody') }));
 //#endregion createMcpHonoApp_mount
 
 //#region createMcpHonoApp_allowedHosts

packages/middleware/hono/README.md

@@ -6,6 +6,7 @@ This package is a thin Hono integration layer for [`@modelcontextprotocol/server
 
 It does **not** implement MCP itself. Instead, it helps you:
 
+- serve MCP as a single Hono middleware with `mcp(factory)`
 - create a Hono app with sensible defaults for MCP servers
 - parse JSON request bodies and expose them as `c.get('parsedBody')` for Streamable HTTP transports
 - add DNS rebinding protection via Host header validation (recommended for localhost servers)
@@ -18,17 +19,56 @@ npm install @modelcontextprotocol/server @modelcontextprotocol/hono hono
 
 ## Exports
 
+- `mcp(factory, options?)` — the one-call way to serve MCP as a Hono middleware
 - `createMcpHonoApp(options?)`
 - `hostHeaderValidation(allowedHostnames)`
 - `localhostHostValidation()`
 
 ## Usage
 
-### Streamable HTTP endpoint (Hono)
+### Serve MCP in one call (recommended)
+
+`mcp(factory)` returns a single Hono middleware that serves MCP over Streamable
+HTTP. It builds on `createMcpHandler`, so the endpoint serves the modern
+2026-07-28 protocol and falls back to stateless 2025-era serving — a fresh
+`McpServer` from your factory backs every request. JSON body parsing and
+localhost DNS-rebinding / origin protection are wired for you; mount it on a
+route you already own:
+
+```ts
+import { mcp } from '@modelcontextprotocol/hono';
+import { McpServer } from '@modelcontextprotocol/server';
+import { Hono } from 'hono';
+
+const app = new Hono();
+app.all(
+    '/mcp',
+    mcp(() => new McpServer({ name: 'my-server', version: '1.0.0' }))
+);
+```
+
+Binding to a public interface? Pass `allowedHosts` / `allowedOrigins` the same way
+as `createMcpHonoApp`, plus any `createMcpHandler` options under `handler`:
+
+```ts
+app.all(
+    '/mcp',
+    mcp(factory, {
+        host: '0.0.0.0',
+        allowedHosts: ['api.example.com'],
+        handler: { legacy: 'reject' } // modern-only strict
+    })
+);
+```
+
+### Build the app yourself (`createMcpHonoApp`)
+
+When you need full control over routing or want to wire the transport by hand,
+`createMcpHonoApp()` returns a `Hono` app with the same defaults pre-applied:
 
 ```ts
-import { McpServer, WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/server';
 import { createMcpHonoApp } from '@modelcontextprotocol/hono';
+import { McpServer, WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/server';
 
 const server = new McpServer({ name: 'my-server', version: '1.0.0' });
 const transport = new WebStandardStreamableHTTPServerTransport({ sessionIdGenerator: undefined });

packages/middleware/hono/package.json

@@ -55,6 +55,7 @@
         "hono": "catalog:runtimeServerOnly"
     },
     "devDependencies": {
+        "@modelcontextprotocol/client": "workspace:^",
         "@modelcontextprotocol/server": "workspace:^",
         "@modelcontextprotocol/tsconfig": "workspace:^",
         "@modelcontextprotocol/vitest-config": "workspace:^",

packages/middleware/hono/src/hono.ts

@@ -1,5 +1,6 @@
-import { isJsonContentType } from '@modelcontextprotocol/server';
-import type { Context } from 'hono';
+import type { CreateMcpHandlerOptions, McpServerFactory } from '@modelcontextprotocol/server';
+import { createMcpHandler, isJsonContentType } from '@modelcontextprotocol/server';
+import type { Context, MiddlewareHandler } from 'hono';
 import { Hono } from 'hono';
 
 import { hostHeaderValidation, localhostHostValidation } from './middleware/hostHeaderValidation';
@@ -113,3 +114,48 @@ export function createMcpHonoApp(options: CreateMcpHonoAppOptions = {}): Hono {
 
     return app;
 }
+
+/**
+ * Options for the {@link mcp} middleware.
+ *
+ * Extends {@link CreateMcpHonoAppOptions} (host/origin protection) with the
+ * options forwarded to {@link createMcpHandler}.
+ */
+export interface McpMiddlewareOptions extends CreateMcpHonoAppOptions {
+    /**
+     * Options forwarded to {@link createMcpHandler} — e.g. `legacy: 'reject'`
+     * for a modern-only strict endpoint.
+     */
+    handler?: CreateMcpHandlerOptions;
+}
+
+/**
+ * Serves MCP as a single Hono middleware — the one-call way to mount MCP on a
+ * route you already own.
+ *
+ * It wires the same defaults as {@link createMcpHonoApp} (JSON body parsing and
+ * localhost DNS-rebinding / origin protection) in front of a
+ * {@link createMcpHandler}, so the endpoint serves the modern 2026-07-28
+ * protocol and falls back to stateless 2025-era serving. A fresh server is
+ * built from your factory for each request.
+ *
+ * @example
+ * ```ts
+ * const app = new Hono();
+ * app.all('/mcp', mcp(() => new McpServer({ name: 'my-server', version: '1.0.0' })));
+ * ```
+ *
+ * @param factory - Builds a fresh MCP server per request.
+ * @param options - Host/origin protection and handler options.
+ * @returns A Hono `MiddlewareHandler` that serves the MCP endpoint.
+ */
+export function mcp(factory: McpServerFactory, options?: McpMiddlewareOptions): MiddlewareHandler {
+    const { handler: handlerOptions, ...appOptions } = options ?? {};
+    const handler = createMcpHandler(factory, handlerOptions);
+    const app = createMcpHonoApp(appOptions);
+    app.all('*', (c: Context<{ Variables: { parsedBody: unknown } }>) => handler.fetch(c.req.raw, { parsedBody: c.get('parsedBody') }));
+    // The inner app is self-contained (its body parser and Host/Origin guards
+    // read only the request), so forwarding just the raw request is enough —
+    // and it avoids `c.executionCtx`, which throws off Cloudflare Workers.
+    return async c => app.fetch(c.req.raw);
+}