Researched guidance: How should hosted MCP clients discover newly added tools after a server update?

Summary

A hosted MCP client should treat its tool registry as refreshable. In the current 2026-07-28 protocol, discover the server/version as needed, fetch tools with tools/list, opt into a toolsListChanged subscription, and refresh the complete listing when a change signal arrives. Re-establish the subscription and do a fresh listing after reconnect because delivery is not guaranteed across transport reconnects. Legacy 2025-11-25 sessions use initialize/initialized and direct notifications/tools/list_changed instead.

Candidate action

For protocol 2026-07-28, on initial connect or reconnect select the modern protocol version (optionally with server/discover), send tools/list to build the host registry, and open a long-lived subscriptions/listen stream requesting notifications.toolsListChanged=true; wait for notifications/subscriptions/acknowledged and verify the acknowledged filter. When notifications/tools/list_changed arrives, treat the cached registry as stale, issue a new tools/list starting a fresh enumeration, follow nextCursor until the listing is complete, and atomically replace the registry before exposing the new tools to the model. Re-open subscriptions/listen after a transport reconnect and repeat the full tools/list refresh, since the subscription ends with the transport and the architecture guidance warns that notifications may be missed across reconnects; use the advertised freshness hints and a conservative polling/revalidation policy as a backstop. For 2025-11-25 or earlier, perform initialize, wait for the server response, send notifications/initialized, inspect tools.listChanged, handle notifications/tools/list_changed, and then refresh tools/list. Do not mix the modern subscription flow with a legacy session.

Applicability

• Hosted MCP clients that keep a unified tool registry for one or more servers and need newly added or modified tools to become available without a manual restart.
• Modern MCP protocol 2026-07-28 clients using per-request protocol metadata and the subscriptions/listen change stream.
• Legacy MCP protocol 2025-11-25 and earlier clients using the initialize/initialized lifecycle and direct list-change notifications.
• Servers whose tool catalog can change at runtime and that advertise the tools capability with listChanged support.

Key findings

• In 2026-07-28, servers expose tools through tools/list and advertise listChanged; clients opt in to notifications with subscriptions/listen using toolsListChanged=true, then a notification is followed by a tools/list refresh in the documented flow. (S1, S2, S4)
• The modern architecture guidance says notification delivery is best effort across transport reconnects and advises clients to rely on polling as well as subscriptions for freshness. (S2)
• The modern lifecycle differs from legacy sessions: 2026-07-28 uses per-request metadata and server/discover, while 2025-11-25 and earlier use initialize/initialized; the legacy tools page uses direct notifications/tools/list_changed without subscriptions/listen. (S3, S5)
• tools/list supports pagination; the reviewed pages do not specify cursor invalidation or a normative restart rule after a changed-list signal, so a fresh complete enumeration is a conservative client policy. (S1, S5)

Known limitations

• The current specification describes the post-notification tools/list refresh in the message flow and architecture guidance but does not assign the client refresh a separate MUST or SHOULD; the immediate refresh and atomic replacement above are robust implementation guidance.
• The specification supports tools/list pagination but does not say whether a changed list invalidates an existing cursor or explicitly require restarting from the first page; restarting is the safe cache-invalidation policy, not a quoted protocol requirement.
• The current architecture guidance says notifications are best effort and may be missed across transport reconnects. It recommends polling for freshness but does not prescribe an interval.
• The meaning and enforcement of ttlMs and cacheScope are described as freshness and reuse hints, but the reviewed pages do not fully define expiry handling or whether a notification always invalidates every cached page.
• The modern lifecycle page explicitly leaves detailed HTTP reconnection behavior open beyond allowing a client to use an unexpected transport close as a reconnect trigger.

Obsolete approaches

• Do not assume a tools/list result obtained only at startup remains current for the lifetime of a hosted process.
• Do not treat notifications/tools/list_changed as carrying an added-tool diff; refresh the authoritative listing instead.
• Do not assume a subscriptions/listen stream survives a closed transport; re-establish it after reconnect.
• Do not use the 2026-07-28 subscriptions/listen flow inside a 2025-11-25 legacy initialize session.

Negative results

• The reviewed current and legacy tool pages do not define a notification replay protocol, a revision number, or a changed-tool delta.
• The reviewed specifications do not define a mandatory client polling cadence or a normative cursor-reset rule after a list change.
• The reviewed pages do not provide hosted-platform-specific behavior or guarantee that a server update will preserve an existing Streamable HTTP session.

Evidence boundary

• basis=researched_guidance; executed=false; independent_reproduction=false
• This is documentation-based proposed guidance only. No hosted client, MCP server update, reconnect, notification delivery, or tool-list refresh was executed or independently reproduced.

What remains unknown

• Whether a modern Streamable HTTP client must re-open subscriptions/listen after every reconnect is not stated as a general HTTP MUST; the safe implementation should do so because the subscription is tied to the transport, but the exact HTTP reconnection procedure remains unspecified.
• The protocol does not say how a client should recover if a change occurs between pages, how long a nextCursor remains valid, or whether servers must provide a stable snapshot while pagination is in progress.
• The reviewed pages do not specify how a hosted client should merge or deduplicate tools across multiple servers, nor how its model/tool prompt cache should be invalidated beyond refreshing the registry.
• SDK or host-specific defaults for subscriptions, TTL handling, polling, and atomic registry replacement remain implementation-dependent.

Evidence status

• basis: researched_guidance
• executed: false
• independent reproduction: false

Sources

• S1 Tools — MCP Specification 2026-07-28 · standard · accessed 2026-09-22
• S2 Architecture overview — MCP Documentation 2026-07-28 · official_documentation · accessed 2026-09-22
• S3 Lifecycle — MCP Specification 2026-07-28 · standard · accessed 2026-09-22
• S4 Subscriptions — MCP Specification 2026-07-28 · standard · accessed 2026-09-22
• S5 Tools — MCP Specification 2025-11-25 · standard · accessed 2026-09-22