Middleware Support in MCP

[dsp-ant]

Description

We need a proper middleware mechanic in the server code. This must support adding custom Starlette middlware and have a pre-defined order of middleware when auth is enabled. See FastMCP 2.0 for inspiration.

References

No response

[felixweinberger]

Linking related middleware issues here:

#593

[donald-ada]

A concrete data point for this decision, scoped to what already exists rather than a new framework:
On current main, the lowlevel Server.middleware list is a first-class, documented seam, and OpenTelemetry tracing (on by default since #2995) already answers the common “which tool / how long / did it fail” observability ask with zero code. The one gap I hit as an MCPServer user: there is no public way to attach a ServerMiddleware to MCPServer — docs/advanced/middleware.md currently says the seam is lowlevel-only, and even the SDK’s own OTel opt-out recipe reaches into the private _lowlevel_server attribute. That private reach-in is effectively the monkeypatching this issue wants to eliminate.
The minimal resolution — no new hooks framework, no new types — seems to be a keyword-only MCPServer(middleware=...) that extends the existing lowlevel chain at a pinned position: inside OpenTelemetry and the request-state boundary, outside extension interceptors (so user middleware sees plaintext params and still observes calls an extension short-circuits). Provisional, same as the lowlevel list.
I have a working implementation of exactly that shape sitting on today’s main: +361/−11 across 6 files, including tests that pin the position contract structurally, a tested docs snippet, and the docs pages updated to stop claiming the seam is lowlevel-only. Full suite passes (5435), pyright strict and coverage rules clean. Happy to open it as a PR if the decision here lands that way — or discard it if the middleware rework is heading somewhere else; it’s small enough to redo.
Disclosure: this change was developed with AI assistance (Claude Code); I’ve reviewed it and can speak to the design.

[HouMinXi]

A concrete use-case for tool-call-level middleware (not just HTTP/Starlette):

Problem: MCP clients may send null for optional string parameters (e.g. {"project_dir": null} instead of omitting the key). Pydantic's str type rejects None, so tools declared with str = "" defaults crash before the handler runs. The only interception point today is monkey-patching _tool_manager.call_tool (private API).

What we need: A call-interceptor hook at the tool dispatch layer — something like on_before_tool_call(name, arguments) -> arguments that runs after argument parsing but before Pydantic validation. This would let us coerce None to "" for string params without touching private internals.

Current workaround:

_original_tc = mcp._tool_manager.call_tool  # private API

async def _null_coerce_call_tool(name, arguments, **kw):
    for k, v in list(arguments.items()):
        if v is None:
            arguments[k] = ""
    return await _original_tc(name, arguments, **kw)

mcp._tool_manager.call_tool = _null_coerce_call_tool

This works on mcp 1.27 but is fragile across versions. If the MCPServer(middleware=...) proposal from @donald-ada's comment lands at the tool-call layer (not just HTTP), it would cover this case cleanly. Otherwise, a dedicated @mcp.on_call_tool hook or add_tool_call_middleware() API would be the minimal surface needed.

The standalone fastmcp package already has this via Middleware.on_call_tool + add_middleware(), but using it introduces a dependency that mcp doesn't transitively provide, so it's not viable for packages that only declare mcp as a dependency.