Skip to content
protomcp

Hot Reload

How it works

pmcp dev watches the directory containing your entry-point file, recursively. When any matching file changes:

  1. The tool process is killed
  2. Internal state (tools, resources, prompts) is reset
  3. A fresh process is spawned
  4. The new process performs a full handshake, registering its tools from scratch
  5. pmcp diffs the new tool list against the old one and sends notifications/tools/list_changed if anything changed
  6. Stale tools, resources, and prompts that no longer exist are automatically removed

Triggering reload

Hot reload is only active in dev mode:

Terminal window
# Python
pmcp dev tools.py


# TypeScript
pmcp dev tools.ts

It is disabled in run mode, which is intended for production.

The watcher monitors the entire directory tree rooted at the entry file’s parent directory. Changes to imported modules are detected automatically as long as they live under that directory.

File watching details

  • Debounce: there is a 100ms debounce — rapid saves (e.g. editor auto-format on write) trigger only one reload.
  • New directories: subdirectories created while dev mode is running are automatically watched.
  • Skipped directories: .git, node_modules, __pycache__, target, and venv are ignored.

In-flight calls

Calls that are in flight when a change is detected are interrupted — the process is killed immediately. If you need a call to complete before the process exits, that is not supported in dev mode.

Gotchas

State is lost on every reload: Because the process is killed and restarted, all in-memory state (caches, sessions, open connections) is lost. Re-initialize lazily if you need to survive across reloads.

Whole directory is watched: Every file under the entry file’s parent directory (filtered by extension) can trigger a reload. If your project directory contains generated or frequently-updated files, move them outside the watched tree or use a subdirectory structure where the entry file lives higher up.

Syntax errors at startup: If the tool process fails to start or crashes during the handshake, pmcp will log the error and leave the previous tool list active until the next successful reload.