After upgrading icuvisor

MCP clients commonly cache a server’s tool catalog for the lifetime of a conversation. If icuvisor is upgraded while a chat is still open, the client may keep using the old tool schema until you start a new conversation.

What icuvisor sends

Every icuvisor tool response includes response metadata like this:

{
  "_meta": {
    "server_version": "v0.5.0",
    "catalog_hash": "ab12cd..."
  }
}

catalog_hash is a deterministic SHA-256 over the exposed MCP tool catalog: tool names, descriptions, input schemas, and advertised output schemas after toolset/delete-mode registration filtering.

When icuvisor can tell that the catalog hash differs from the hash first seen by the current process or session, the response also includes:

{
  "_meta": {
    "schema_changed": true,
    "schema_change_message": "icuvisor was upgraded from v0.4.1 to v0.5.0 since this conversation started; tool schemas may have changed. Open a new conversation to use the latest tools.",
    "previous_version": "v0.4.1",
    "current_version": "v0.5.0",
    "previous_catalog_hash": "9f3e22...",
    "catalog_hash": "ab12cd..."
  }
}

What you should do

If an AI client or assistant reports _meta.schema_changed: true, open a new conversation in the MCP client.

A new chat forces the client to fetch the latest tool catalog and use the current argument schemas. Reusing the old conversation can keep sending stale arguments even though the upgraded binary is running.

Limits

  • Some MCP clients do not surface _meta back to the assistant or user. icuvisor still sends the metadata, but the assistant may not relay the warning.
  • Normal binary restarts reset process memory. The schema-change fields are primarily a protocol guarantee and integration-test seam until client/session resumption plumbing is available.
  • This notification does not perform auto-update checks or release-channel polling. It only describes the schema state of responses produced by the running binary.

Check the top-level CHANGELOG for user-visible tool schema changes.