```
### McpMiddlewareFnFor
A typed MCP middleware function whose `ctx` parameter is narrowed based on the pattern string `P`. When `P` is a key of [`McpMiddlewarePatternMap`](#mcpmiddlewarepatternmap) (`"tools/call"`, `"resources/read"`, or `"prompts/get"`), `ctx` is narrowed to the matching context type. For wildcard or unrecognized patterns it falls back to the base `McpMiddlewareFn` whose `ctx` is the base `MiddlewareContext`.
**Type parameters**
> The middleware pattern string used to select the narrowed context type.
**Signature**
```ts wrap theme={null}
type McpMiddlewareFnFor = P extends keyof McpMiddlewarePatternMap
? (ctx: McpMiddlewarePatternMap[P], next: () => Promise) => Promise
: McpMiddlewareFn
```
### McpMiddlewarePatternMap
Maps MCP middleware pattern strings to their narrowed context type. Used by [`McpMiddlewareFnFor`](#mcpmiddlewarefnfor) to infer the correct `ctx` parameter for a given pattern.
**Properties**
> Narrowed context for the `tools/call` method.
> Narrowed context for the `resources/read` method.
> Narrowed context for the `prompts/get` method.
**Signature**
```ts wrap theme={null}
interface McpMiddlewarePatternMap {
"tools/call": ToolsCallMiddlewareContext;
"resources/read": ResourcesReadMiddlewareContext;
"prompts/get": PromptsGetMiddlewareContext;
}
```
### ToolsCallMiddlewareContext
A [`MiddlewareContext`](#middlewarecontext) with `method` fixed to `"tools/call"` and `params` narrowed to the `tools/call` shape: `name` (the tool name), an optional `arguments` record, and an optional `_meta` record. The `params` type is intersected with `Record` so arbitrary extra keys remain accessible.
**Properties**
> Always the literal `"tools/call"`.
> The narrowed tool-call params.
**Signature**
```ts wrap theme={null}
interface ToolsCallMiddlewareContext extends MiddlewareContext {
method: "tools/call";
params: { name: string; arguments?: Record; _meta?: Record } & Record;
}
```
### ResourcesReadMiddlewareContext
A [`MiddlewareContext`](#middlewarecontext) with `method` fixed to `"resources/read"` and `params` narrowed to the `resources/read` shape: `uri` (the resource URI) and an optional `_meta` record. The `params` type is intersected with `Record` so extra keys remain accessible.
**Properties**
> Always the literal `"resources/read"`.
> The narrowed resource-read params.
**Signature**
```ts wrap theme={null}
interface ResourcesReadMiddlewareContext extends MiddlewareContext {
method: "resources/read";
params: { uri: string; _meta?: Record } & Record;
}
```
### PromptsGetMiddlewareContext
A [`MiddlewareContext`](#middlewarecontext) with `method` fixed to `"prompts/get"` and `params` narrowed to the `prompts/get` shape: `name` (the prompt name), an optional `arguments` record of strings, and an optional `_meta` record. The `params` type is intersected with `Record` so extra keys remain accessible.
**Properties**
> Always the literal `"prompts/get"`.
> The narrowed prompt-get params.
**Signature**
```ts wrap theme={null}
interface PromptsGetMiddlewareContext extends MiddlewareContext {
method: "prompts/get";
params: { name: string; arguments?: Record; _meta?: Record } & Record;
}
```
### McpMiddlewareEntry
Internal storage entry for a registered MCP middleware. The pattern is stored with the `mcp:` prefix already stripped (e.g. `"tools/call"`, `"tools/*"`, or `"*"`). This is the element type consumed by [`composeMiddleware`](#composemiddleware).
This interface is marked `@internal`. It is exported for advanced use and for typing custom middleware composition, but most servers register middleware through `server.use('mcp:...')` and never construct entries directly.
**Properties**
> Pattern after stripping `"mcp:"`, e.g. `"tools/call"`, `"tools/*"`, or `"*"`.
> The middleware function to run for matching methods.
**Signature**
```ts wrap theme={null}
interface McpMiddlewareEntry {
pattern: string;
handler: McpMiddlewareFn;
}
```
## HTTP middleware adapters
Adapters that let you register either Express/Connect middleware or native Hono middleware on the server's underlying HTTP app. `server.use(...)` uses these internally to detect the middleware style and adapt accordingly, so the same `server.use(...)` call accepts both.
```ts theme={null}
import {
adaptMiddleware,
adaptConnectMiddleware,
isExpressMiddleware,
} from "mcp-use/server";
```
The example below registers both Express middleware from npm and native Hono middleware on the same server. `server.use(...)` detects each style and adapts it for you.
```ts theme={null}
import { MCPServer, text } from "mcp-use/server";
import morgan from "morgan";
import rateLimit from "express-rate-limit";
const server = new MCPServer({
name: "express-middleware-example",
version: "1.0.0",
});
// Express middleware from npm
server.use(morgan("combined"));
server.use("/api", rateLimit({ windowMs: 15 * 60 * 1000, max: 100 }));
// Hono middleware (c, next)
server.use(async (c, next) => {
const start = Date.now();
await next();
console.log(`${c.req.method} ${c.req.path} - ${Date.now() - start}ms`);
});
await server.listen();
```
### isExpressMiddleware
Detect whether a middleware function is Express/Connect style or Hono style. Express/Connect middleware has the signature `(req, res, next)` (or `(err, req, res, next)`); Hono middleware has the signature `(c, next)`.
Detection combines function arity with body pattern matching against the stringified function:
* A non-function (or falsy) value returns `false`.
* Functions with 3 or 4 parameters are treated as Express/Connect and return `true` (the body is checked for Express patterns such as `res.send`, `res.json`, `req.body`, but it returns `true` for 3-4 parameter functions regardless).
* Functions with exactly 2 parameters are treated as Hono and return `false`, unless the body contains Express-specific patterns (then `true`). Hono-specific patterns such as `c.req` or `c.json` confirm the Hono case (`false`).
* Functions with any other parameter count (0, 1, or 5+) default to Hono and return `false`.
**Parameters**
> The middleware function to inspect.
**Returns**
> `true` if it is Express/Connect middleware, `false` if it is Hono middleware.
**Signature**
```ts wrap theme={null}
function isExpressMiddleware(middleware: any): boolean
```
### adaptMiddleware
Adapt a middleware function so it works with Hono. It calls [`isExpressMiddleware`](#isexpressmiddleware): if the input is Express/Connect style, it delegates to [`adaptConnectMiddleware`](#adaptconnectmiddleware) with the supplied path; otherwise it returns the middleware unchanged as a Hono `MiddlewareHandler`.
**Parameters**
> The middleware function (Express/Connect or Hono).
> The path pattern the middleware is mounted at. Only used when the middleware is Express/Connect. Defaults to `"*"`.
**Returns**
> A Hono middleware handler.
**Signature**
```ts wrap theme={null}
function adaptMiddleware(middleware: any, middlewarePath?: string): Promise
```
### adaptConnectMiddleware
Adapt a Connect/Express middleware handler to a Hono `MiddlewareHandler`. It dynamically imports `node-mocks-http` to build a mock `IncomingMessage`/`ServerResponse` pair, runs the Connect middleware against them, and translates the result back into a Hono response.
Behavior to note:
* The `middlewarePath` is normalized by stripping a trailing `*` and a trailing `/`, then that prefix is removed from the request pathname so the Connect middleware sees the path without its mount prefix.
* If the Connect middleware ends the response (calls `res.end`), the captured status, headers, and body become the Hono response. Status codes `204` and `304` are sent without a body.
* If the Connect middleware calls `next()` without ending the response, control passes to Hono's `next()` so the request continues down the chain.
**Parameters**
> The Connect/Express middleware handler to adapt.
> The path pattern the middleware is mounted at, e.g. `"/mcp-use/widgets/*"`.
**Returns**
> A Hono middleware handler wrapping the Connect middleware.
**Signature**
```ts wrap theme={null}
function adaptConnectMiddleware(connectMiddleware: any, middlewarePath: string): Promise
```
## CORS proxy
A CORS proxy for browser-based MCP clients that need to connect to remote MCP servers which do not support CORS or require server-side forwarding. Mount it onto a Hono app with `mountMcpProxy`.
```ts theme={null}
import { mountMcpProxy } from "mcp-use/server";
```
### mountMcpProxy
Mount the MCP proxy middleware on a Hono app. The proxy reads a target URL from the `X-Target-URL` header (or from an `__mcp_target` query parameter used for OAuth discovery, which takes precedence), forwards the request to that target with sanitized headers, and streams the response back to the client. It enables CORS (exposing all response headers, with `Authorization` allowed explicitly), handles SSE streaming, manages redirects manually to avoid `ArrayBuffer` detachment, and rewrites the `resource` field on OAuth discovery responses to match the proxy URL. Returns `void`.
The proxy registers routes under `options.path` (default `"/mcp/proxy"`): a CORS handler and an optional logger on the `path/*` glob, plus a catch-all handler for every HTTP method on that same glob.
Error and status behavior:
* Missing target URL responds `400` with an `X-Target-URL header is required` error.
* An invalid target URL format responds `400`.
* When `authenticate` returns false, responds `401` (`Unauthorized`).
* When `validateRequest` returns false, responds `403` (`Invalid target URL`).
* Upstream failures respond `500`; connection-refused errors (`ECONNREFUSED` or `fetch failed`) are logged as a warning rather than an error.
This proxy does not implement authentication by default. For production use, provide an `authenticate` function or restrict access to localhost only.
**Parameters**
> The Hono application instance to mount the proxy on.
> Proxy configuration. Defaults to an empty object.
**Returns**
>
**Signature**
```ts wrap theme={null}
function mountMcpProxy(app: Hono, options?: McpProxyOptions): void
```
```ts theme={null}
import { Hono } from "hono";
import { mountMcpProxy } from "mcp-use/server";
const app = new Hono();
// With authentication and target validation
mountMcpProxy(app, {
path: "/api/proxy",
authenticate: async (c) => {
const token = c.req.header("Authorization");
return token === `Bearer ${process.env.SECRET_TOKEN}`;
},
validateRequest: (targetUrl) => targetUrl.startsWith("https://mcp.example.com"),
});
```
### McpProxyOptions
Configuration for [`mountMcpProxy`](#mountmcpproxy). Every field is optional.
**Properties**
> Route path for the proxy endpoint, e.g. `"/inspector/api/proxy"`.
> Optional authentication function. Return `true` to allow the request, `false` to reject with `401`.
> Optional validator checking whether the target URL is allowed. Return `true` to allow, `false` to reject with `403`.
> Enable request logging. Disabled only when explicitly set to `false`.
**Signature**
```ts wrap theme={null}
interface McpProxyOptions {
path?: string;
authenticate?: (c: Context) => Promise | boolean;
validateRequest?: (targetUrl: string, c: Context) => Promise | boolean;
enableLogging?: boolean;
}
```
## See also
The server class whose `use(...)` method registers the middleware documented here.
Full middleware and proxy implementation.