docs: restart the AI client after upgrading (MCP servers don't hot-reload)#76
Merged
Merged
Conversation
MCP servers are launched once by the AI client and are not hot-reloaded, so after 'uv tool upgrade' (or pulling new code) the running server keeps executing the old version until the client is restarted. This surfaced in testing: after upgrading, use_remote calls on HPC-only paths failed with 'file not found' because the old local-only tool was still loaded. - README: new 'Upgrading' section with a restart warning - getting-started: restart-after-upgrade note + a troubleshooting entry mapping the exact symptom to the fix
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds guidance telling users to restart their AI client after upgrading the
package. This was the one real gap found during a full local + remote validation
of the tool surface.
Why
MCP servers are launched once when the AI client (Claude Desktop, Claude Code,
Cursor, …) starts and are not hot-reloaded. After
uv tool upgrade(orpulling new code in a checkout), the running server keeps executing the old
version until the client is restarted.
This was reproduced live: after merging the remote-execution PRs,
use_remotecalls for
zonal_anomaly/remap_to_rectilinearfailed through the MCP serverwith "Grid file not found" on an HPC path — because the still-running server
had the old, local-only versions of those tools. Restarting the client resolved
it completely (verified: all remote ops then returned
execution_venue: hpc:chrysalis, and the curl vector-component guardrail warning appeared).What changed
restart warning, including the exact confusing symptom to watch for.
plus a Troubleshooting entry mapping "I upgraded but new tools/fixes are
missing, or a
use_remotecall fails with file-not-found" straight to the fix.Testing
uv run pre-commit run— all hooks pass (docs-only change).