Versioning: protocol, server, tools, and hub revisions

Four version axes exist; know which one you’re changing.

1. MCP protocol version (framework-handled)

nanohub-mcp negotiates from SUPPORTED_PROTOCOL_VERSIONS in the installed nanohubmcp/server.py. The repository inspected for this skill listed 2026-01-26, 2025-11-25, 2025-06-18, 2024-11-05; verify the installed environment instead of treating that list as permanent. If the client requests one of those, it wins; otherwise the server answers with the newest. You write no code for this — but don’t assume a newer-protocol feature is available just because the framework supports it: check the negotiated capabilities (Tasks, Apps, elicitation), not the version string.

2. What nanohub-mcp does NOT support: live list changes

There are no listChanged notifications. Tools and resources are whatever was registered when your module imported; if you register more at runtime (a catalog-refresh tool, like rappturemcp’s), connected clients are NOT notified — they see additions only on their next tools/list / resources/list. If you build such a refresh, return "..._list_notifications_supported": false in its result so the model knows to re-list rather than wait, and treat this as an admin affordance, not a client-facing feature.

3. Tool surface evolution (your responsibility)

Clients cache tool lists; hosts pin behavior to tool names and schemas.

  • Names are forever. A rename is a breaking change; the model-facing name is an API. Breaking change ⇒ new tool name, keep the old one delegating, mark its docstring “Deprecated: use X — kept for existing clients.”

  • Schemas grow, never shrink. Keep the small required envelope + open additionalProperties pattern (server-guide.md): adding output fields is then safe; removing or retyping a required field breaks claude.ai’s structuredContent validation immediately.

  • Defaults are behavior. Changing a default (even fixing one, like a sweep electrode) changes what every zero-argument call does — call it out in the tool description and release notes.

  • Surface your versions at runtime for debugging: MCPServer(name, version=APP_VERSION) goes out in initialize’s serverInfo, and an about/config:// resource that reports APP_VERSION plus key dependency versions lets anyone check WHAT is actually deployed through the MCP connection itself.

4. Hub tool revisions (where stale code hides)

The published nanoHUB tool revision is the deployment unit, and it has a trap: existing tool sessions keep running the old revision after you publish. The gateway happily reuses them. Symptoms: “I deployed the fix but the behavior didn’t change.”

  • After publishing, terminate the tool’s active sessions (or wait them out) before re-testing.

  • Bump APP_VERSION on every publish and check it via the about resource / serverInfo — that’s your proof of which revision answered.

  • The live hub may also lag your working tree at the platform level (gateway, OAuth components) — the verification.md prime directive applies to every axis of this file.