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

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 mcp.server.fastmcp import FastMCP
from tools import echo  # keep tools small and pure

server = FastMCP("My Server")
server.add_tool(echo)
server.run()

On code change

  • Edit my_app/tools.py and save.
  • HMR reloads the module and updates the server's tool binding if it was wired via module-level imports or registration hooks.

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