🔥 Hot Reload Your Python mcp-use Servers!

[CNSeniorious000]

I noticed that since mcp-use v1.5, mcp-use now provides a mcp_use.MCPServer implementation which directly inherits from mcp.server.FastMCP, making it seamlessly supported by mcp-hmr.

You can build MCP servers with mcp-use and develop them with hot reload, just like you'd experience with Vite in the frontend world.

mcp-use-inspector-demo.mov

Why This Matters

Traditional reload mechanisms (like reload=True for Uvicorn) restart the entire process—interpreter, all third-party packages, everything. This means:

• ❌ Lose all application state
• ❌ Re-import expensive dependencies
• ❌ Wait for complex initialization (DL models, DB connections, etc.)

Leading to interruption of the development flow.

mcp-hmr takes a different approach. Using HMR's runtime dependency tracking, it:

• ✅ Reloads only what changed — modified modules and their exposed variables' dependents, nothing more
• ✅ Preserves application state — your server's internal state stays intact
• ✅ Maintains connections — MCP clients never get disconnected

Resulting in instant feedback — changes take effect in milliseconds, not seconds

Quick Start

Just install mcp-hmr like any other PyPI package:

uv pip install mcp-use mcp-hmr

Say you have a file main.py containing your mcp-use server:

from mcp_use.server import MCPServer

server = MCPServer(name="my-server", version="1.0.0")

@server.tool()
def echo(message: str) -> str:
    return message

Then just launch with mcp-hmr like how you would with mcp run:

mcp-hmr main:server

That's it! Now connect it with a MCP client and modify your tools, resources, or prompts, save the file, and next call to your server will reflect the changes instantly—without needing to manually restart the server.

How It Works

HMR knows what to reload and what to preserve by runtime tracking of variable-level dependencies.

1. module -> variable dependencies are tracked as your server runs
2. when a file changes, invalidate the affected module
3. this may updates some of its variables, which may be dependencies of other modules
4. invalidate those dependent modules too

The result is variable-level granularity—far more precise than traditional file-level reloading. In practice, this means modifying a single function only reruns that function and modules that depend on it, preserving expensive initialization elsewhere in your server.

Normally if your code is organized into modules, changing files often requires rerunning only one or two modules. But even if you write everything in a single file, HMR still cache 3-party imports and preserves them across reloads, so you still get significant speedups.

Learn More

• mcp-hmr on PyPI
• HMR Docs
• HMR Repository
• mcp-hmr support the official mcp sdk and fastmcp too

HMR is a reactive programming engine and hot-reload framework that brings variable-level fine-grained reactivity to Python. While mcp-hmr focuses on MCP servers, the broader HMR ecosystem also includes:

• uvicorn-hmr — Hot reload for ASGI applications (FastAPI, ...)

---

Try it with your mcp-use servers and give me feedback! Thanks for reading :)

[pietrozullo]

This is actually very cool, could you contribute this functionality to mcp-use ?