Python: Decide recovery policy for ended MCP subscription streams

[jpalvarezl]

Summary

Track an optional resilience policy for Python MCP subscriptions/listen streams after the base MCP v2 migration in #8245 is complete.

The base migration opens one modern subscription for enabled tool/prompt list-change notifications, preserves the legacy message_handler path, and recreates the subscription when Agent Framework reconnects the whole MCP connection. If the individual listen stream ends while the client connection remains usable, refresh currently stops until a later connection reset.

This is not required for MCP 2026 protocol compliance and must not block #8245. The specification says an abrupt loss may trigger reconnect; it does not require automatic same-connection recovery. The Python SDK's application guide separately recommends that watchers which still care should back off, re-listen, and refetch because events are not replayed.

Design questions

• Should Agent Framework promise continuous catalog watching after either graceful stream completion or SubscriptionLost?
• If so, which failures are transient versus permanent (SubscriptionLost, timeout, MCPError, method-not-found, pre-2026 ListenNotSupportedError)?
• What retry/backoff policy should be used, and should it be bounded?
• Should one combined tools/prompts subscription be re-opened, with both honored catalogs refetched after the new acknowledgment?
• How should recovery coordinate with the existing lifecycle owner without reconnecting from inside—and cancelling—the subscription consumer task?
• What diagnostics should distinguish graceful completion, abrupt loss, and permanent rejection?

Possible acceptance criteria

• Recovery behavior is explicitly decided and documented as Agent Framework policy.
• If enabled, graceful completion and SubscriptionLost back off before re-listening.
• Catalog refetch occurs only after the replacement subscription is acknowledged; no event replay is assumed.
• Tool and prompt catalogs share one subscription/recovery lifecycle.
• Close, reset, cancellation, and retry delay leave no background tasks or listen contexts behind.
• Permanent unsupported/rejected cases do not spin in a retry loop.
• Existing full-connection reconnect behavior continues to establish exactly one new subscription.

References

• MCP 2026 subscriptions specification: https://modelcontextprotocol.io/specification/2026-07-28/basic/patterns/subscriptions
• MCP Python SDK client subscription guide: https://py.sdk.modelcontextprotocol.io/client/subscriptions/
• Base Python MCP v2 migration: Python: [Feature]: Support the stateless MCP 2026-07-28 revision alongside 2025-era peers #8245

[Rudra-G-23]

Hi, I'd be interested in taking the implementation for this once the base MCP v2 migration in #8245 is ready.

My understanding is that the main decision needed first is whether Agent Framework should automatically re-listen after graceful completion / SubscriptionLost, with bounded backoff and a catalog refetch only after the replacement subscription is acknowledged.

Once that policy is decided, would you be open to an external contribution implementing it and adding the corresponding lifecycle/retry tests?