Support low-level interface for modifying the underlying Uvicorn server

[ycd]

It would be great to have an API to interact with the MCP's underlying Uvicorn server.

More specifically, It would be great to have a leaky interface, that can act as a bridge with the abstraction of the underlying Uvicorn server, a way to configure it, or maybe just allowing us to pass arguments/kwargs to the Uvicorn server.

Problem

As a start, there is no clean way to close a Uvicorn server programmatically/gracefully, there are some hacks to go around it, here are some related issues:

Uvicorn cannot be shutdown programmatically - Kludex/uvicorn#1103
Uvicorn cannot be shutdown programmatically - Kludex/uvicorn#742
Running multiple Uvicorn servers simultaneously hangs on shutdown - Kludex/uvicorn#1773
Uvicorn eats SIGINTs, does not propagate exceptions - Kludex/uvicorn#1579

And so on....

Idea

You might say that, we already have access to the server and low-level API with

from mcp.server.lowlevel.server import Server

However just to handle a graceful shutdown, not being able to handle all the out-of-box features that FastMCP class provides, feels like re-inventing the wheel.

So one of the easiest way(s) to do it is, passing the timeout_graceful_shutdown=0 to the uvicorn.Config which solves the (partially) hanging server problem.

Uvicorn is configurable via environment variables, when they are prefixed with UVICORN_, so in a similar way, when we pass values to:

FastMCP(
    "some_server",
    lifespan=app_lifespan,
    debug=True, # no prefix, for the Settings class
    uvicorn_timeout_graceful_shutdown=0, # uvicorn prefix, for UvicornConfig?
)

We can buffer this, similar to **settings then we can pass to the initialization of the server, would it be feasible?

I'm sure there will be other use cases for this, also I'm not sure if the example above is the best way to handle that, just to give you a brief idea.

[Kludex]

All the issues you pointed out were solved in Uvicorn's side, that's why they are all closed.

The UVICORN_ env var can only be passed if uvicorn is called via CLI, since it leverages click entrypoint.

As per the issue itself, I think it makes sense to provide some kind of way to interact with uvicorn, but I believe the real issue is that FastMCP is not an ASGI application. I believe it's not because MCP specified 2 transports: stdio and sse - which I also believe it was not the best decision, given that it mixes too very different ways of doing things.

[ycd]

It's nice to see you Marce!

Yes, I'm aware that we can't use ENV vars with UVICORN_ prefix with MCP, otherwise I wouldn't have requested this feature :)

You're probably right about the core problem though, but both SseServerTransport and stdio_server are leaked abstractions, so I can't really complain about them combining in the FastMCP class implementation for a simplified high-level API.

In my case, I'd just love to keep the being able to use the high-level FastMCP interface and not having to rewrite boilerplate code again and be able to modify uvicorn.Config.

[maxisbey]

The Uvicorn configuration concern raised here is already addressable — MCPServer.streamable_http_app() and sse_app() return plain Starlette ASGI applications that can be run with any server and any configuration:

app = mcp.streamable_http_app()
uvicorn.run(app, timeout_graceful_shutdown=0, ssl_keyfile="key.pem", workers=4)

See examples/snippets/servers/streamable_http_basic_mounting.py for a working example of this pattern.

The graceful shutdown concern is tracked separately in #1739 (P1).

Closing as the architectural escape hatch already exists. The run() convenience method is intentionally simple — users who need full server control should use the *_app() methods with their own server setup.

_{AI Disclaimer}