MCP server hot reload

Why hot reload matters for MCP development

MCP servers are tested interactively: you write a tool handler, call it from the Inspector or Claude Desktop, see the output, and adjust. The iteration speed depends entirely on how fast you can get from "saved file" to "tool call returned updated result." With tsc compilation, a cold restart takes 8–20 seconds for a typical project. With tsx --watch, it takes 0.5–1.5 seconds.

The other advantage of a fast restart is that it reveals stateful bugs early. If your server accumulates state during development (a module-level array, a database connection that fails to reconnect, a cache that isn't cleared), a slow restart tempts you to keep the same process running across many edits. Fast restart makes process isolation the default, which matches production behavior.

tsx --watch — the recommended setup

tsx is a TypeScript executor built on esbuild. Unlike ts-node, it strips types rather than type-checking, so it starts in milliseconds. --watch restarts the process on any .ts, .tsx, .js, or .json change in the project.

npm install --save-dev tsx

Add the dev script to package.json:

{
  "scripts": {
    "dev":   "tsx --watch src/index.ts",
    "build": "tsc --noEmit && tsc --outDir dist",
    "start": "node dist/index.js"
  }
}

Run npm run dev. The MCP server starts on stdio. In MCP Inspector, configure it to run npm run dev as the server command — it keeps the process connected and reconnects automatically after each restart.

The tradeoff with tsx: type errors are invisible during development. Run tsc --noEmit in a separate terminal or as a pre-commit hook to catch type errors before pushing. Do not skip type checking entirely — it catches real bugs, especially in tool handler dispatch code where the wrong type can cause a silent wrong-tool call.

Configuring MCP Inspector for auto-reconnect

The MCP Inspector connects to a server over stdio by spawning a subprocess. When the subprocess exits (on reload), the Inspector detects the exit and shows a "Disconnected" state. To reconnect automatically:

1. In Inspector → Settings → Server, set Command to npm and Args to run dev (not the path to the compiled file). When the watcher restarts the server process, Inspector respawns its subprocess.
2. Alternatively, use Inspector's --watch flag: npx @modelcontextprotocol/inspector --watch npm run dev — Inspector polls for reconnection every 500ms after a disconnect.
3. For SSE/HTTP MCP servers (not stdio), the Inspector retries the HTTP connection automatically — set Reconnect delay to 1000ms in Inspector settings.

# Terminal 1 — MCP server in watch mode
npm run dev

# Terminal 2 — Inspector (connects to the above)
npx @modelcontextprotocol/inspector npm run dev

# Or as one command (Inspector manages the server subprocess):
npx @modelcontextprotocol/inspector --command "npm run dev"

Hot reload with Claude Desktop

Claude Desktop reads the MCP server config from ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows). It spawns the server process once at startup and does not automatically reconnect on process exit — a full Claude Desktop restart is required.

Two workarounds during development:

1. Use Inspector as primary dev client, Claude Desktop for final validation. Iterate in Inspector, then do a final test in Claude Desktop before each meaningful commit.
2. Wrap the server in a persistent process manager. Configure Claude Desktop to run tsx --watch src/index.ts as the server command. Claude Desktop will restart the process on exit — but note it may take 2–5 seconds for Claude Desktop to detect the exit and restart, which is slightly slower than Inspector's reconnect.

// claude_desktop_config.json — dev config
{
  "mcpServers": {
    "my-server-dev": {
      "command": "npx",
      "args": ["tsx", "--watch", "/path/to/your/server/src/index.ts"],
      "env": {
        "NODE_ENV": "development",
        "API_BASE_URL": "http://localhost:3000"
      }
    }
  }
}

Keep a separate "my-server-prod" entry pointing at the compiled dist/index.js so you can switch between dev and production without editing the config file.

Server structure for reliable hot reload

Hot reload restarts the Node.js process — module-level singletons are re-initialized on each restart. This is almost always what you want, but two patterns cause problems:

1. Module-level database connections: if you open a SQLite or Postgres connection at module load time and the connection state is not properly closed on process exit, restarting during a write can corrupt the database file. Use a factory function (createDeps()) that opens connections after the Server is constructed, and wire a process.on('SIGTERM') / process.on('SIGINT') handler to close them cleanly.
2. In-memory state shared across tool calls: if tools share a module-level cache or accumulator for test purposes, each reload starts fresh. This is correct for production but can be frustrating during development if you are testing incremental behavior. Use an external state store (SQLite file, Redis) that survives restarts, or accept the clean-slate behavior.

// src/server.ts — structured for clean restart
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { createDeps } from './deps.js';
import { registerTools } from './tools.js';

async function main() {
  const deps = await createDeps(); // opens DB connection, HTTP client, etc.

  const server = new Server(
    { name: 'my-server', version: '1.0.0' },
    { capabilities: { tools: {} } }
  );

  registerTools(server, deps);

  const transport = new StdioServerTransport();
  await server.connect(transport);

  // Clean shutdown on SIGTERM (tsx --watch sends this before restarting)
  const shutdown = async () => { await deps.db.close(); process.exit(0); };
  process.on('SIGTERM', shutdown);
  process.on('SIGINT',  shutdown);
}

main().catch(console.error);

tsx --watch sends SIGTERM to the old process before starting the new one. If your server handles SIGTERM and closes connections cleanly, the restart is safe. If it does not, and you are writing to a SQLite file, add journal_mode=WAL in your PRAGMA setup — WAL mode is resilient to abrupt process termination.

Watching non-TypeScript files

tsx --watch watches .ts, .tsx, .js, and .json files by default. To also restart on changes to .sql migration files, .yaml config files, or .graphql schemas, use --watch with an explicit pattern:

# Watch TypeScript source and YAML config files
tsx --watch --watch-path src --watch-path config src/index.ts

# Or use nodemon for more glob control:
nodemon --watch src --watch config --ext ts,js,yaml --exec 'tsx src/index.ts'

For OpenAPI spec files: add --watch-path openapi.yaml so the server restarts when the spec changes — essential if you are doing runtime dynamic tool generation from the spec (see OpenAPI to MCP).

Debugging with hot reload

Node.js's --inspect flag opens a debugging port. Combine it with tsx --watch to get hot-reloading and a debugger:

# In package.json scripts:
"dev:debug": "tsx --watch --inspect src/index.ts"

# Attach in VS Code with .vscode/launch.json:
{
  "configurations": [{
    "name": "Attach to tsx --watch",
    "type": "node",
    "request": "attach",
    "port": 9229,
    "restart": true,    // re-attaches after each reload
    "sourceMaps": true,
    "outFiles": ["${workspaceFolder}/src/**/*.ts"]
  }]
}

"restart": true in the VS Code launch config makes the debugger automatically reattach after each hot reload. Combined with tsx --watch restarting in under a second, you get a live debugger that follows your server through every code change.

What hot reload does not replace

Hot reload speeds up the inner development loop. It does not replace:

• Unit tests with InMemoryTransport: hot reload tests manually via Inspector; unit tests verify behavior automatically and catch regressions when you change a tool that another tool depends on. See MCP server unit testing.
• Type checking: tsx strips types. Run tsc --noEmit in CI or as a pre-commit hook. A type error in hot-reload mode can look like a runtime crash with a confusing stack trace.
• Uptime monitoring after deployment: hot reload is a local development tool. Once you deploy, AliveMCP pings your endpoint every 60 seconds and alerts you if a deployment breaks the server — the same way Inspector shows you local failures, but for production.

Related questions

Further reading

• MCP server local development — full local stack setup
• MCP Inspector — interactive testing during development
• MCP server TypeScript — project setup and tsconfig
• MCP server unit testing — InMemoryTransport for automated testing
• OpenAPI to MCP — watching spec changes with hot reload
• MCP server CLI tools — scripts to automate the dev workflow
• AliveMCP — uptime monitoring for when the dev loop moves to production