Skip to content

🚧 Under Construction 🚧

This site is currently under construction. This page is generated by AI and has not undergone thorough review by a human. There may be hallucination!

In fact, for now only /, /reactive, and the llms.txt are carefully crafted by myself.

MCP Integration (mcp-hmr)

This page explains how to run Model Context Protocol (MCP) servers with hot reload and what to expect.

Quick summary

  • Use mcp-hmr to run MCP servers without reconnecting clients on most code edits
  • The reactivity layer reloads changed modules and notifies dependent code; long-lived connections and resources are preserved when possible
  • For complex protocol/state changes or C-level state, prefer a full restart

Install

pip install mcp-hmr

Run a server

mcp-hmr main.py:app

Or using module import format:

mcp-hmr main:app

mcp-hmr is meant to be a drop-in replacement for mcp run ... / fastmcp run ..., but with HMR enabled.

Notes on behavior

  • The running MCP server keeps existing connections. When a changed module updates tools/resources, the server replaces the implementation in-place and the next tool invocation uses the new code.
  • Avoid mutating protocol wire formats at runtime; changes to RPC signatures or resource schemas may require coordinated client updates or a restart.
  • Now, whenever you save changes to your source code, the server will automatically reload without dropping the connection to the client.

Recommended patterns

  • Put heavy, stateful initialization (database pools, ML models) into modules you rarely edit.
  • Use small, pure functions for tools/resources whenever possible.
  • Add idempotent registration for tools/resources so reloads do not double-register them.

What to Observe

  • Try changing the tool's return value or resource's content and save the file.
  • You will see the client output update to reflect your changes without restarting the connection.
  • This demonstrates how mcp-hmr enables seamless hot reloading for MCP servers, maintaining the connection between client and server while updating the code on-the-fly.

Example: simple server structure (see examples/mcp/)

# main.py
from fastmcp import FastMCP

app = FastMCP()


@app.tool()
def echo(message: str):
    return message


@app.resource("example://greet")
def greet():
    return "hello world"


if __name__ == "__main__":
    app.run("stdio")

On code change

  • Edit main.py or a helper module imported by it and save.
  • HMR reloads the changed module and the MCP app exported as app keeps serving the updated implementation.

Debugging and caveats

  • If clients observe inconsistent behavior after a reload, check for:
  • global mutable state that wasn't migrated
  • double-registration of tools or hooks
  • changes in serialization / argument formats
  • For protocol-level & breaking changes, schedule a controlled deploy and restart.

See also