mcp-use - The fullstack MCP framework to develop MCP Apps for ChatGPT / Claude and MCP Servers for AI Agents.

Middleware runs shared logic around MCP operations and HTTP requests. Use it for logging, authorization, request shaping, rate limiting, headers, custom routes, and other cross-cutting behavior. This guide explains where each middleware layer fits and how to apply common patterns.

Choose MCP middleware or Hono middleware

Use MCP middleware when logic depends on a parsed MCP operation. Use Hono middleware when logic belongs at the HTTP layer before MCP parsing.

Need	Use
Check which tool is being called	MCP middleware
Filter tool, resource, or prompt lists	MCP middleware
Require OAuth scopes for an MCP operation	MCP middleware
Add CORS, request logging, or HTTP headers	Hono middleware
Add health checks, webhooks, or other custom routes	Hono routes

MCP middleware patterns use the mcp: prefix. Hono middleware uses normal server.use(...) calls. Both layers are request-scoped, and there is no transport session affinity between calls.

Wrap MCP tool calls

Register MCP middleware with server.use("mcp:<method>", handler). The handler receives the parsed operation context and a next() function.

import { MCPServer } from "mcp-use";
import { z } from "zod";

const server = new MCPServer({
  name: "middleware-server",
  version: "1.0.0",
});

server.use("mcp:tools/call", async (ctx, next) => {
  const startedAt = Date.now();
  const result = await next();
  console.log(`${ctx.params.name}: ${Date.now() - startedAt}ms`);
  return result;
});

server.tool(
  {
    name: "greet",
    description: "Say hello.",
    inputSchema: z.object({ name: z.string() }),
  },
  async ({ name }) => ({
    content: [{ type: "text", text: `Hello, ${name}!` }],
  }),
);

export default server;

Call next() to continue to the next middleware or the operation handler. Return its result unless you intentionally replace the response.

Match the right operation

Use the narrowest pattern that covers the behavior:

Pattern	Use it for
`mcp:tools/call`	Tool execution
`mcp:tools/list`	Tool discovery
`mcp:resources/read`	Resource reads
`mcp:resources/list`	Resource discovery
`mcp:prompts/get`	Prompt requests
`mcp:prompts/list`	Prompt discovery
`mcp:*`	Every operation wrapped by MCP middleware

Exact middleware can inspect or replace its method-specific result. The mcp:* wildcard is pass-through: call next() or throw, and do not replace the downstream result. MCP middleware does not wrap initialization, completion, log-level changes, or subscription listener requests.

Read the originating HTTP request

ctx.request is the originating Hono HonoRequest when the operation came from HTTP. Read headers with ctx.request.header(name), the path with ctx.request.path, and the underlying Web Request with ctx.request.raw.

server.use("mcp:tools/list", async (ctx, next) => {
  console.log(ctx.request?.header("user-agent"));
  return next();
});

Values set by Hono middleware with c.set() are available through ctx.get(). Client metadata and middleware state belong to the current request only.

Add an OAuth scope guard

Configure OAuth before reading ctx.auth. Middleware on an authenticated server receives verified provider identity and scopes.

import { oauthAuth0Provider } from "mcp-use/oauth/auth0";

const domain = process.env.AUTH0_DOMAIN;
if (!domain) throw new Error("AUTH0_DOMAIN is required");

const authenticatedServer = new MCPServer({
  name: "protected-server",
  version: "1.0.0",
  oauth: oauthAuth0Provider({ domain }),
});

authenticatedServer.use("mcp:tools/call", async (ctx, next) => {
  const requiredScope = `tools:call:${ctx.params.name}`;

  if (
    !ctx.auth.scopes.includes(requiredScope) &&
    !ctx.auth.scopes.includes("tools:*")
  ) {
    throw new Error(`Insufficient scope. Required: ${requiredScope}`);
  }

  return next();
});

Use server authentication to verify bearer tokens before relying on ctx.auth.

Rate-limit expensive operations

Use middleware when the limit applies to a class of operations instead of one tool. Key limits by a verified identity and store distributed counters in a shared backend.

authenticatedServer.use("mcp:tools/call", async (ctx, next) => {
  const key = `user:${ctx.auth.user.id}`;

  if (!(await rateLimiter.take(key, 30, "1m"))) {
    throw new Error("Rate limit exceeded.");
  }

  return next();
});

Use ctx.auth.clientId when the limit should apply to an OAuth client rather than an end user. Never use a transport session ID, self-reported client metadata, or an unverified header as an authorization or rate-limit key.

Filter discovery results

List middleware receives the item array rather than the protocol envelope:

server.use("mcp:tools/list", async (_ctx, next) => {
  const tools = await next();
  return tools.filter((tool) => !tool.name.startsWith("_"));
});

Keep filtering rules predictable. Hidden tools should not be required for normal user workflows.

Order middleware deliberately

Middleware runs in registration order. The first registered handler is the outermost wrapper.

server.use("mcp:*", loggingMiddleware);
server.use("mcp:tools/call", authorizationMiddleware);
server.use("mcp:tools/call", rateLimitMiddleware);

A practical order is logging, authorization, rate limiting, then operation-specific validation. Logging can observe rejected requests while the remaining middleware rejects expensive work early.

Use Hono middleware and routes

MCPServer exposes its Hono application as server.app. It also provides bound helpers such as server.use, server.get, server.post, and server.delete.

server.use("*", async (c, next) => {
  const startedAt = Date.now();
  const requestId = crypto.randomUUID();
  await next();
  c.header("x-request-id", requestId);
  console.log(`${c.req.method} ${c.req.path}: ${Date.now() - startedAt}ms`);
});

server.get("/health", (c) => c.json({ ok: true }));

server.app.post("/webhooks/orders", async (c) => {
  const payload = await c.req.json();
  await processOrderWebhook(payload);
  return c.json({ accepted: true }, 202);
});

Use Hono middleware for raw HTTP policy and custom routes. Use MCP middleware when you need ctx.method, parsed ctx.params, verified ctx.auth, or a method-specific MCP result.

Test middleware locally

Run the development server:

npx mcp-use dev

Open http://localhost:3000/mcp/inspector, then call tools, list resources, and request prompts. Verify both allowed and rejected paths, transformed list results, response headers, and custom Hono routes. The maintained middleware example includes a runnable tool-call wrapper and a protected discovery request.

Next steps

Authentication

Configure OAuth before relying on verified middleware identity.

Tools

Design the tool callbacks that MCP middleware wraps.

Notifications

Send request-scoped progress, logs, and protocol notifications.

Middleware example

Run the maintained middleware server and verification scenario.

Get Started

MCP Server

MCP Apps

MCP Client

MCP Agent

Tooling

Middleware

Choose MCP middleware or Hono middleware

Wrap MCP tool calls

Match the right operation

Read the originating HTTP request

Add an OAuth scope guard

Rate-limit expensive operations

Filter discovery results

Order middleware deliberately

Use Hono middleware and routes

Test middleware locally

Next steps

Authentication

Tools

Notifications

Middleware example

​Choose MCP middleware or Hono middleware

​Wrap MCP tool calls

​Match the right operation

​Read the originating HTTP request

​Add an OAuth scope guard

​Rate-limit expensive operations

​Filter discovery results

​Order middleware deliberately

​Use Hono middleware and routes

​Test middleware locally

​Next steps

Authentication

Tools

Notifications

Middleware example

Choose MCP middleware or Hono middleware

Wrap MCP tool calls

Match the right operation

Read the originating HTTP request

Add an OAuth scope guard

Rate-limit expensive operations

Filter discovery results

Order middleware deliberately

Use Hono middleware and routes

Test middleware locally

Next steps