Make mcp.types a permanent alias, not a deprecation shim

A deprecation is a permanent commitment (a v3 removal) spent on a
transient goal (nudging the v1->v2 migration wave), and the second
break would cost every remaining user again for no functional gain:
the module is a star re-export that cannot drift. `import mcp.types as
types` is also baked into years of tutorials and generated code, and
is a genuinely clean types-only namespace for SDK users, while
`mcp_types` remains the spelling that installs without the SDK stack.

So drop the MCPDeprecationWarning and every "removed in v3" phrase.
Removed names now raise AttributeError from `__getattr__` as PEP 562
requires, keeping hasattr() and getattr(name, default) on their
fallback paths; the tradeoff is that `from mcp.types import <removed>`
falls back to CPython's generic ImportError, which is still fail-fast.
Fix two doc claims that still said mcp.types no longer exists.

Author: maxisbey

docs/migration.md

@@ -14,7 +14,7 @@ Every section heading below names the API it affects, so searching this page for
 |---|---|---|
 | `FastMCP` renamed to `MCPServer` | `ModuleNotFoundError: No module named 'mcp.server.fastmcp'` | [`FastMCP` renamed](#fastmcp-renamed-to-mcpserver) |
 | Fields renamed from camelCase to snake_case | `AttributeError: 'Tool' object has no attribute 'inputSchema'` | [snake_case fields](#field-names-changed-from-camelcase-to-snake_case) |
-| `mcp.types` moved to the `mcp-types` package | `MCPDeprecationWarning: mcp.types is deprecated; import from mcp_types.` | [`mcp.types` moved](#mcptypes-moved-to-the-mcp-types-package) |
+| `mcp.types` names removed | `AttributeError: mcp.types.Content was removed in v2; use ContentBlock.` | [Removed types](#removed-type-aliases-and-classes) |
 | `McpError` renamed to `MCPError` | `ImportError: cannot import name 'McpError' from 'mcp'` | [`McpError` renamed](#mcperror-renamed-to-mcperror) |
 | Resource URIs are `str`, not `AnyUrl` | `AttributeError: 'str' object has no attribute 'host'` | [URI type](#resource-uri-type-changed-from-anyurl-to-str) |
 | `streamablehttp_client` removed | `ImportError: cannot import name 'streamablehttp_client'` | [`streamablehttp_client`](#streamablehttp_client-removed) |
@@ -170,18 +170,19 @@ nothing on PyPI to pin to, keep the unpinned form.
 
 The protocol wire types now live in a standalone distribution, `mcp-types`, imported as
 `mcp_types`. Its only runtime dependencies are `pydantic` and `typing-extensions`, so code
-that just needs to (de)serialize MCP traffic can install it without the full SDK. The `mcp` package depends on `mcp-types` and
-continues to re-export the type names at the top level, so `from mcp import Tool` is
-unchanged. `mcp.shared.version` was removed. The package's API reference is at
+that just needs to (de)serialize MCP traffic can install it without the full SDK. The `mcp`
+package depends on `mcp-types` and continues to re-export the type names at the top level, so
+`from mcp import Tool` is unchanged. The package's API reference is at
 [`mcp_types`](api/mcp_types/index.md).
 
-`import mcp.types` still works in v2, as a compatibility shim that mirrors `mcp_types` and
-emits an `MCPDeprecationWarning` on first import; it will be removed in v3, so switch to
-`mcp_types` now. The shim only restores the import: the field renames below still apply, so
-code that imports through it can go on to fail on camelCase attribute access. The 23 names
-that no longer exist (listed under
-[Removed type aliases and classes](#removed-type-aliases-and-classes)) raise an
-`ImportError` from the shim that names their replacement.
+`import mcp.types` and `from mcp.types import ...` keep working: `mcp.types` is a permanent
+alias that mirrors `mcp_types` exactly (every name is the same object), so v1's most common
+import line needs no change if you already depend on `mcp`. Only `mcp.shared.version` was
+removed; import from `mcp_types.version` instead. Reading a name that no longer exists (listed
+under [Removed type aliases and classes](#removed-type-aliases-and-classes)) as
+`mcp.types.Content` raises an `AttributeError` that names its replacement; a
+`from mcp.types import Content` of one raises a plain `ImportError` (Python discards the hint on
+that path, but it still fails fast).
 
 **Why:** keeping the wire types in their own package lets tooling and lightweight clients
 depend on the protocol schema without pulling in `httpx2`, `starlette`, `uvicorn`, and the
@@ -197,11 +198,13 @@ from mcp.shared.version import LATEST_PROTOCOL_VERSION
 **After (v2):**
 
 ```python
+# Unchanged if you depend on the SDK:
+from mcp.types import Tool, Resource
+from mcp import Tool, Resource
+
+# Or the standalone package, which installs without the SDK's transport stack:
 from mcp_types import Tool, Resource
 from mcp_types.version import LATEST_PROTOCOL_VERSION
-
-# Names `mcp` already re-exported at the top level are unchanged:
-from mcp import Tool, Resource
 ```
 
 ### Removed type aliases and classes
@@ -1711,7 +1714,7 @@ except MCPError as e:
         raise
 ```
 
-`e.error.code` also still works; `e.code` is the v2 convenience property. `mcp.types` no longer exists, so the constant comes from `mcp_types`. The example uses the high-level `Client`; `ClientSession.call_tool()` raises the same `MCPError`.
+`e.error.code` also still works; `e.code` is the v2 convenience property. The constant is importable from `mcp_types` or, equivalently, `mcp.types`. The example uses the high-level `Client`; `ClientSession.call_tool()` raises the same `MCPError`.
 
 ### `ClientSession` now runs on `JSONRPCDispatcher`; `BaseSession` removed
 

docs/whats-new.md

@@ -117,7 +117,7 @@ Underneath, the v1 `BaseSession` receive loop was replaced by a dispatcher engin
 
 ### The wire types moved to `mcp-types`, and every field is snake_case
 
-The protocol types now live in their own distribution, `mcp-types`, imported as `mcp_types`. It depends on nothing but pydantic and typing-extensions, so a gateway, a proxy, or a code generator can consume MCP's wire shapes without installing an HTTP stack. `mcp` depends on it at an exact version and re-exports the common names, so `from mcp import Tool` still works; `import mcp.types` does not.
+The protocol types now live in their own distribution, `mcp-types`, imported as `mcp_types`. It depends on nothing but pydantic and typing-extensions, so a gateway, a proxy, or a code generator can consume MCP's wire shapes without installing an HTTP stack. `mcp` depends on it at an exact version, and both v1 spellings keep working: `from mcp import Tool` for the common names, and `import mcp.types` as a permanent alias that mirrors `mcp_types` exactly.
 
 On those types, every Python attribute is now snake_case: `result.is_error`, `tool.input_schema`, `listing.next_cursor`. The JSON on the wire is camelCase, exactly as before; only the attribute spelling changed. Two stricter defaults ride along: unknown fields are ignored instead of round-tripped (put extras in `_meta`), and both sides validate traffic against the protocol version they negotiated. See the **[Migration Guide](migration.md#field-names-changed-from-camelcase-to-snake_case)** for the rename table.
 
@@ -146,7 +146,7 @@ Each of these is a section in the **[Migration Guide](migration.md)**:
 
 * The **WebSocket transport**, both sides, and the `mcp[ws]` extra. It was never part of the MCP specification.
 * The **experimental Tasks** API (`mcp.*.experimental`). 2026-07-28 moves tasks out of the core protocol and into an official extension ([SEP-2663](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2663)), which this SDK does not implement yet.
-* `mcp.types`, `mcp.shared.version`, `mcp.shared.progress`, and `mcp.shared.session` (with the `RequestResponder` stub v1 `message_handler` annotations imported) as import paths.
+* `mcp.shared.version`, `mcp.shared.progress`, and `mcp.shared.session` (with the `RequestResponder` stub v1 `message_handler` annotations imported) as import paths. (`mcp.types` is *not* removed: it remains as a permanent alias for the standalone `mcp_types` package.)
 * The deprecated `streamablehttp_client` spelling, and the `get_session_id` callback from `streamable_http_client` (which now yields exactly two streams).
 * `McpError`, renamed **`MCPError`** with a direct `(code, message, data)` constructor.
 * `MCPServer.get_context()`, `mount_path=`, and the lowlevel `Server`'s decorator methods, ContextVar, and handler dicts.

pyproject.toml

@@ -217,7 +217,7 @@ max-complexity = 24 # Default is 10
 
 [tool.ruff.lint.per-file-ignores]
 "__init__.py" = ["F401"]
-# Deprecated compat shim that mirrors the whole mcp_types namespace by design.
+# mcp.types is an alias that mirrors the whole mcp_types namespace by design.
 "src/mcp/types.py" = ["F403"]
 # Generated by scripts/gen_surface_types.py: raw datamodel-codegen output (TID251 lifts the repo-wide RootModel ban for these generated validators).
 "src/mcp-types/mcp_types/v*/__init__.py" = ["D212", "E501", "I001", "TID251", "UP007", "UP037"]

scripts/docs/gen_ref_pages.py

@@ -30,8 +30,9 @@
 # it from `src/` would emit the unimportable `mcp-types.mcp_types.*`.
 PACKAGES = (ROOT / "src" / "mcp", ROOT / "src" / "mcp-types" / "mcp_types")
 
-# Deprecated compatibility shims: they mirror another module's namespace and
-# are documented in the migration guide, so they earn no API page of their own.
+# Alias modules that mirror another module's namespace (`mcp.types` mirrors
+# `mcp_types`): the mirrored package's pages are the canonical rendering, so
+# the alias earns no page of its own.
 EXCLUDED = frozenset({"mcp.types"})
 
 _KIND_SECTIONS = {

src/mcp/types.py

@@ -1,31 +1,23 @@
-"""Deprecated: the protocol types moved to the standalone `mcp_types` package.
+"""The MCP protocol wire types, as the `mcp.types` namespace.
 
-`import mcp.types` still works in v2 as a compatibility shim, but it emits an
-`MCPDeprecationWarning` and will be removed in v3. Import from `mcp_types` instead:
+This module mirrors the standalone `mcp_types` package exactly (every name is the
+same object), so SDK users can keep the familiar v1 spelling:
 
-    from mcp_types import Tool, TextContent
+    import mcp.types as types
 
-Field names also changed from camelCase to snake_case (`tool.input_schema`, not
-`tool.inputSchema`), so an import that succeeds through this shim can still fail
-later on attribute access. See the migration guide, "Types and wire format".
+    types.TextContent(type="text", text="hi")
+
+Depend on and import `mcp_types` directly instead when you only need to
+(de)serialize MCP traffic and don't want the SDK's transport stack: its only
+runtime dependencies are `pydantic` and `typing-extensions`.
 """
 
-# A wildcard mirror of the mcp_types namespace is the whole point of this shim.
+# A wildcard mirror of the mcp_types namespace is the whole point of this module.
 # pyright: reportWildcardImportFromLibrary=false
 
-import warnings
-
 from mcp_types import *
 from mcp_types import __all__ as __all__
 
-from mcp.shared.exceptions import MCPDeprecationWarning
-
-warnings.warn(
-    "mcp.types is deprecated; import from mcp_types. Fields are now snake_case; see the migration guide.",
-    MCPDeprecationWarning,
-    stacklevel=2,
-)
-
 # Names v1's mcp.types exposed that no longer exist. A bare "cannot import name"
 # leaves people grepping; naming the replacement finishes the migration step.
 _REMOVED = {
@@ -56,9 +48,9 @@
 
 def __getattr__(name: str) -> object:
     if (hint := _REMOVED.get(name)) is not None:
-        # ImportError, not AttributeError: `from mcp.types import X` swallows an
-        # AttributeError raised here and reports a generic "cannot import name",
-        # discarding the hint; an ImportError propagates through both the
-        # from-import and plain attribute-access paths with the message intact.
-        raise ImportError(f"mcp.types.{name} was removed in v2; {hint}. See the migration guide.")
+        # AttributeError as PEP 562 requires, so hasattr() and getattr(..., default)
+        # still take their fallback path. The cost: `from mcp.types import Content`
+        # discards this message for CPython's generic "cannot import name" (still
+        # fail-fast); attribute access, the far more common v1 spelling, keeps it.
+        raise AttributeError(f"mcp.types.{name} was removed in v2; {hint}. See the migration guide.")
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

tests/test_types.py

@@ -1,6 +1,3 @@
-import importlib
-import sys
-from types import ModuleType
 from typing import Any
 
 import mcp_types
@@ -43,7 +40,7 @@
 from pydantic import ValidationError
 
 import mcp
-from mcp import MCPDeprecationWarning
+import mcp.types
 
 
 @pytest.mark.anyio
@@ -454,42 +451,36 @@ def test_input_required_result_requires_at_least_one_of_input_requests_or_reques
     assert InputRequiredResult(request_state="s").input_requests is None
 
 
-def _import_deprecated_mcp_types_shim() -> ModuleType:
-    """Re-import the `mcp.types` compatibility shim so its import-time warning fires again."""
-    sys.modules.pop("mcp.types", None)
-    with pytest.warns(MCPDeprecationWarning) as record:
-        module = importlib.import_module("mcp.types")
-    assert str(record[0].message) == snapshot(
-        "mcp.types is deprecated; import from mcp_types. Fields are now snake_case; see the migration guide."
-    )
-    return module
-
-
-def test_deprecated_mcp_types_import_warns_and_mirrors_mcp_types():
-    """SDK-defined: the v1 `mcp.types` module is a warning shim that mirrors `mcp_types` exactly."""
-    module = _import_deprecated_mcp_types_shim()
-    assert module.__all__ == mcp_types.__all__
-    assert module.Tool is mcp_types.Tool
-    # Importing the submodule binds it on the package, so v1's `from mcp import types`
-    # idiom resolves to the same shim module.
-    assert getattr(mcp, "types") is module
-
-
-def test_deprecated_mcp_types_names_the_replacement_for_a_name_removed_in_v2():
-    """SDK-defined: a v1 name that no longer exists raises an error naming its v2 replacement."""
-    module = _import_deprecated_mcp_types_shim()
-    # ImportError rather than AttributeError so `from mcp.types import Content` keeps this
-    # message: the from-import path replaces an AttributeError with a generic one.
-    with pytest.raises(ImportError) as exc_info:
-        getattr(module, "Content")
+def test_mcp_types_namespace_mirrors_mcp_types_exactly():
+    """SDK-defined: `mcp.types` is a permanent alias whose every name is the `mcp_types` object."""
+    assert mcp.types.__all__ == mcp_types.__all__
+    assert all(getattr(mcp.types, name) is getattr(mcp_types, name) for name in mcp_types.__all__)
+
+
+def test_mcp_types_attribute_access_names_the_replacement_for_a_removed_name():
+    """SDK-defined: reading a v1 name that no longer exists names its v2 replacement."""
+    with pytest.raises(AttributeError) as exc_info:
+        getattr(mcp.types, "Content")
     assert str(exc_info.value) == snapshot(
         "mcp.types.Content was removed in v2; use ContentBlock. See the migration guide."
     )
+    # AttributeError (not ImportError) keeps the introspection contract for probing code.
+    assert not hasattr(mcp.types, "Content")
+    assert getattr(mcp.types, "Content", None) is None
+
+
+def test_mcp_types_from_import_of_a_removed_name_still_fails_fast():
+    """SDK-defined: `from mcp.types import <removed>` raises rather than importing a stale name.
+
+    CPython builds this ImportError itself and discards the module's hint text, so only the
+    exception type is asserted; the hint is on the attribute-access path above.
+    """
+    with pytest.raises(ImportError):
+        exec("from mcp.types import Content")
 
 
-def test_deprecated_mcp_types_unknown_attribute_raises_attribute_error():
-    """SDK-defined: an unknown attribute is a normal AttributeError, so `hasattr` still works."""
-    module = _import_deprecated_mcp_types_shim()
+def test_mcp_types_unknown_attribute_raises_attribute_error():
+    """SDK-defined: an unknown attribute is a normal AttributeError, so `hasattr` returns False."""
     with pytest.raises(AttributeError):
-        getattr(module, "not_a_protocol_type")
-    assert not hasattr(module, "not_a_protocol_type")
+        getattr(mcp.types, "not_a_protocol_type")
+    assert not hasattr(mcp.types, "not_a_protocol_type")