Skip to content

[v1.x] Deprecate the WebSocket transport and the experimental tasks entry points#2828

Draft
maxisbey wants to merge 1 commit into
v1.xfrom
deprecate-websocket-and-tasks-entry-points
Draft

[v1.x] Deprecate the WebSocket transport and the experimental tasks entry points#2828
maxisbey wants to merge 1 commit into
v1.xfrom
deprecate-websocket-and-tasks-entry-points

Conversation

@maxisbey

Copy link
Copy Markdown
Contributor

Summary

Marks two API surfaces as deprecated on the v1.x line. Both are already removed on main (v2): the WebSocket transport in #2785 and experimental tasks support in #2714. This change gives 1.x users advance notice before they upgrade to 2.0.

  • WebSocket transportwebsocket_client and websocket_server now carry typing_extensions.deprecated markers and emit a DeprecationWarning when called. WebSocket was never part of the MCP specification; the streamable HTTP transport is the replacement.
  • Experimental tasks entry pointsClientSession.experimental, the experimental_task_handlers constructor kwarg, ServerSession.experimental, and Server.experimental warn the same way. Tasks (SEP-1686) were removed from the MCP specification and are expected to return as a separate MCP extension in the future.

Design notes

  • Warnings fire only on use. There are no import-time warnings, so libraries that import these modules at top level (without calling them) are unaffected at runtime.
  • Library internals never trigger the warning. Internal callers now go through a private ServerSession._experimental accessor, and a regression test asserts that a plain client/server round trip emits zero deprecation warnings. @deprecated is applied outside @asynccontextmanager so the warning points at the caller's frame rather than contextlib internals.
  • The type-checker signal is intentional. Editors and type checkers that flag deprecated symbols (pyright's reportDeprecated, ty's deprecated rule) will now surface these usages downstream — that static channel reaches maintainers more reliably than runtime warnings, which Python hides by default.
  • Test-suite warning policy preserved. The suites that intentionally exercise these APIs get scoped filterwarnings ignores (a conftest for the tasks suite, a pytestmark for the websocket suite) instead of repo-global ignores, so the global filterwarnings = ["error"] net still catches any accidental warning from SDK internals elsewhere.
  • The experimental tasks docs pages now show a deprecation banner.

Deliberately not in this PR: the task types in mcp.types and the experimental module classes are untouched. Runtime warnings there would fire from inside libraries that build on these types and spam their users; a follow-up can add static-only markers (@deprecated(..., category=None)) for those.

Testing

  • New tests assert each entry point emits the warning, and that plain (non-tasks, non-websocket) usage stays warning-free.
  • Full suite passes with 100% coverage; pyright strict is clean.

AI Disclaimer

…ints

Both surfaces are removed in mcp 2.0, so mark them deprecated on the
v1.x line to give users advance notice:

- websocket_client and websocket_server now carry
  typing_extensions.deprecated markers and emit a DeprecationWarning
  when called. WebSocket was never part of the MCP specification; the
  streamable HTTP transport is the replacement.
- The experimental tasks entry points (ClientSession.experimental,
  the experimental_task_handlers kwarg, ServerSession.experimental,
  and Server.experimental) warn the same way. Tasks (SEP-1686) were
  removed from the MCP specification and are expected to return as a
  separate MCP extension.

Warnings are emitted only when the deprecated APIs are used: there are
no import-time warnings, and internal code paths now go through a
private ServerSession._experimental accessor so plain (non-tasks)
clients and servers never see a warning. A regression test asserts
that plain session usage stays warning-free, and the warning ignores
for the suites that intentionally exercise these APIs are scoped to
those suites rather than silenced globally.

The docs pages for the experimental tasks API now carry a deprecation
banner instead of the experimental one.
@maxisbey maxisbey force-pushed the deprecate-websocket-and-tasks-entry-points branch from 7aef6e6 to adda346 Compare June 10, 2026 15:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant