Split protocol types into a standalone mcp-types package (#2973)

src/mcp/__init__.py

@@ -1,11 +1,4 @@
-from .client.client import Client
-from .client.session import ClientSession
-from .client.session_group import ClientSessionGroup
-from .client.stdio import StdioServerParameters, stdio_client
-from .server.session import ServerSession
-from .server.stdio import stdio_server
-from .shared.exceptions import MCPDeprecationWarning, MCPError, UrlElicitationRequiredError
-from .types import (
+from mcp_types import (
     CallToolRequest,
     ClientCapabilities,
     ClientNotification,
@@ -63,7 +56,15 @@ from .types import (
     ToolUseContent,
     UnsubscribeRequest,
 )
-from .types import Role as SamplingRole
+from mcp_types import Role as SamplingRole
+
+from .client.client import Client
+from .client.session import ClientSession
+from .client.session_group import ClientSessionGroup
+from .client.stdio import StdioServerParameters, stdio_client
+from .server.session import ServerSession
+from .server.stdio import stdio_server
+from .shared.exceptions import MCPDeprecationWarning, MCPError, UrlElicitationRequiredError
 
 __all__ = [
     "CallToolRequest",

src/mcp/client/__main__.py

@@ -6,8 +6,8 @@ from functools import partial
 from urllib.parse import urlparse
 
 import anyio
+import mcp_types as types
 
-from mcp import types
 from mcp.client._transport import ReadStream, WriteStream
 from mcp.client.session import ClientSession
 from mcp.client.sse import sse_client

src/mcp/client/_probe.py

@@ -17,17 +17,17 @@ from __future__ import annotations
 
 from typing import Any
 
-from pydantic import ValidationError
-
-from mcp import types
-from mcp.client.session import ClientSession
-from mcp.shared.exceptions import MCPError
-from mcp.shared.version import (
+import mcp_types as types
+from mcp_types import UNSUPPORTED_PROTOCOL_VERSION
+from mcp_types.version import (
     HANDSHAKE_PROTOCOL_VERSIONS,
     LATEST_MODERN_VERSION,
     MODERN_PROTOCOL_VERSIONS,
 )
-from mcp.types import UNSUPPORTED_PROTOCOL_VERSION
+from pydantic import ValidationError
+
+from mcp.client.session import ClientSession
+from mcp.shared.exceptions import MCPError
 
 
 def _parse_supported(data: Any) -> list[str] | None:

src/mcp/client/auth/oauth2.py

@@ -16,6 +16,7 @@ from urllib.parse import quote, urlencode, urljoin, urlparse
 
 import anyio
 import httpx
+from mcp_types.version import is_version_at_least
 from pydantic import BaseModel, Field, ValidationError
 
 from mcp.client.auth.exceptions import OAuthFlowError, OAuthTokenError
@@ -54,7 +55,6 @@ from mcp.shared.auth_utils import (
     resource_url_from_server_url,
 )
 from mcp.shared.inbound import MCP_PROTOCOL_VERSION_HEADER
-from mcp.shared.version import is_version_at_least
 
 logger = logging.getLogger(__name__)
 

src/mcp/client/auth/utils.py

@@ -2,6 +2,7 @@ import re
 from urllib.parse import urljoin, urlparse
 
 from httpx import Request, Response
+from mcp_types import LATEST_PROTOCOL_VERSION
 from pydantic import AnyUrl, ValidationError
 
 from mcp.client.auth import OAuthFlowError, OAuthRegistrationError, OAuthTokenError
@@ -13,7 +14,6 @@ from mcp.shared.auth import (
     ProtectedResourceMetadata,
 )
 from mcp.shared.inbound import MCP_PROTOCOL_VERSION_HEADER
-from mcp.types import LATEST_PROTOCOL_VERSION
 
 
 def extract_field_from_www_auth(response: Response, field_name: str) -> str | None:

src/mcp/client/client.py

@@ -8,23 +8,8 @@ from dataclasses import KW_ONLY, dataclass, field
 from typing import Any, Literal, TypeVar, overload
 
 import anyio
-from typing_extensions import deprecated
-
-from mcp import types
-from mcp.client._memory import InMemoryTransport
-from mcp.client._probe import negotiate_auto
-from mcp.client._transport import Transport
-from mcp.client.session import ClientSession, ElicitationFnT, ListRootsFnT, LoggingFnT, MessageHandlerFnT, SamplingFnT
-from mcp.client.streamable_http import streamable_http_client
-from mcp.server import Server
-from mcp.server.mcpserver import MCPServer
-from mcp.server.runner import modern_on_request
-from mcp.shared.direct_dispatcher import create_direct_dispatcher_pair
-from mcp.shared.dispatcher import Dispatcher, ProgressFnT
-from mcp.shared.exceptions import MCPDeprecationWarning
-from mcp.shared.jsonrpc_dispatcher import JSONRPCDispatcher
-from mcp.shared.version import HANDSHAKE_PROTOCOL_VERSIONS, MODERN_PROTOCOL_VERSIONS
-from mcp.types import (
+import mcp_types as types
+from mcp_types import (
     CallToolResult,
     CompleteResult,
     EmptyResult,
@@ -44,6 +29,21 @@ from mcp.types import (
     ResourceTemplateReference,
     ServerCapabilities,
 )
+from mcp_types.version import HANDSHAKE_PROTOCOL_VERSIONS, MODERN_PROTOCOL_VERSIONS
+from typing_extensions import deprecated
+
+from mcp.client._memory import InMemoryTransport
+from mcp.client._probe import negotiate_auto
+from mcp.client._transport import Transport
+from mcp.client.session import ClientSession, ElicitationFnT, ListRootsFnT, LoggingFnT, MessageHandlerFnT, SamplingFnT
+from mcp.client.streamable_http import streamable_http_client
+from mcp.server import Server
+from mcp.server.mcpserver import MCPServer
+from mcp.server.runner import modern_on_request
+from mcp.shared.direct_dispatcher import create_direct_dispatcher_pair
+from mcp.shared.dispatcher import Dispatcher, ProgressFnT
+from mcp.shared.exceptions import MCPDeprecationWarning
+from mcp.shared.jsonrpc_dispatcher import JSONRPCDispatcher
 
 ConnectMode = Literal["legacy", "auto"] | str
 """``mode=`` value: ``"legacy"`` (initialize handshake), ``"auto"`` (discover, fall back to

src/mcp/client/session.py

@@ -9,10 +9,27 @@ from typing import Any, Literal, Protocol, cast, overload
 import anyio
 import anyio.abc
 import anyio.lowlevel
+import mcp_types as types
+from mcp_types import (
+    CLIENT_CAPABILITIES_META_KEY,
+    CLIENT_INFO_META_KEY,
+    INTERNAL_ERROR,
+    METHOD_NOT_FOUND,
+    PROTOCOL_VERSION_META_KEY,
+    UNSUPPORTED_PROTOCOL_VERSION,
+    RequestId,
+    RequestParamsMeta,
+)
+from mcp_types import methods as _methods
+from mcp_types.version import (
+    HANDSHAKE_PROTOCOL_VERSIONS,
+    LATEST_HANDSHAKE_VERSION,
+    LATEST_MODERN_VERSION,
+    MODERN_PROTOCOL_VERSIONS,
+)
 from pydantic import BaseModel, TypeAdapter, ValidationError
 from typing_extensions import Self, TypeVar, deprecated
 
-from mcp import types
 from mcp.client._transport import ReadStream, WriteStream
 from mcp.shared._compat import resync_tracer
 from mcp.shared.dispatcher import CallOptions, DispatchContext, Dispatcher, ProgressFnT
@@ -27,23 +44,6 @@ from mcp.shared.jsonrpc_dispatcher import JSONRPCDispatcher
 from mcp.shared.message import ClientMessageMetadata, SessionMessage
 from mcp.shared.session import RequestResponder
 from mcp.shared.transport_context import TransportContext
-from mcp.shared.version import (
-    HANDSHAKE_PROTOCOL_VERSIONS,
-    LATEST_HANDSHAKE_VERSION,
-    LATEST_MODERN_VERSION,
-    MODERN_PROTOCOL_VERSIONS,
-)
-from mcp.types import (
-    CLIENT_CAPABILITIES_META_KEY,
-    CLIENT_INFO_META_KEY,
-    INTERNAL_ERROR,
-    METHOD_NOT_FOUND,
-    PROTOCOL_VERSION_META_KEY,
-    UNSUPPORTED_PROTOCOL_VERSION,
-    RequestId,
-    RequestParamsMeta,
-)
-from mcp.types import methods as _methods
 
 DEFAULT_CLIENT_INFO = types.Implementation(name="mcp", version="0.1.0")
 DISCOVER_TIMEOUT_SECONDS = 10.0

src/mcp/client/session_group.py

@@ -15,11 +15,11 @@ from typing import Any, Literal, TypeAlias, overload
 
 import anyio
 import httpx
+import mcp_types as types
 from pydantic import BaseModel, Field
 from typing_extensions import Self
 
 import mcp
-from mcp import types
 from mcp.client.session import ElicitationFnT, ListRootsFnT, LoggingFnT, MessageHandlerFnT, SamplingFnT
 from mcp.client.sse import sse_client
 from mcp.client.stdio import StdioServerParameters

src/mcp/client/sse.py

@@ -6,10 +6,10 @@ from urllib.parse import parse_qs, urljoin, urlparse
 
 import anyio
 import httpx
+import mcp_types as types
 from anyio.abc import TaskStatus
 from httpx_sse import SSEError, aconnect_sse
 
-from mcp import types
 from mcp.shared._compat import resync_tracer
 from mcp.shared._context_streams import create_context_streams
 from mcp.shared._httpx_utils import McpHttpClientFactory, create_mcp_http_client

src/mcp/client/stdio.py

@@ -18,11 +18,11 @@ from typing import Literal, TextIO
 
 import anyio
 import anyio.lowlevel
+import mcp_types as types
 from anyio.abc import AsyncResource, Process
 from anyio.streams.text import TextReceiveStream
 from pydantic import BaseModel, Field
 
-from mcp import types
 from mcp.client._transport import TransportStreams
 from mcp.os.posix.utilities import terminate_posix_process_tree
 from mcp.os.win32.utilities import (

src/mcp/client/streamable_http.py

@@ -12,15 +12,7 @@ import anyio
 import httpx
 from anyio.abc import TaskGroup
 from httpx_sse import EventSource, ServerSentEvent, aconnect_sse
-from pydantic import ValidationError
-
-from mcp.client._transport import TransportStreams
-from mcp.shared._compat import resync_tracer
-from mcp.shared._context_streams import ContextReceiveStream, ContextSendStream, create_context_streams
-from mcp.shared._httpx_utils import create_mcp_http_client
-from mcp.shared.inbound import MCP_PROTOCOL_VERSION_HEADER
-from mcp.shared.message import ClientMessageMetadata, SessionMessage
-from mcp.types import (
+from mcp_types import (
     INTERNAL_ERROR,
     INVALID_REQUEST,
     METHOD_NOT_FOUND,
@@ -34,6 +26,14 @@ from mcp.types import (
     RequestId,
     jsonrpc_message_adapter,
 )
+from pydantic import ValidationError
+
+from mcp.client._transport import TransportStreams
+from mcp.shared._compat import resync_tracer
+from mcp.shared._context_streams import ContextReceiveStream, ContextSendStream, create_context_streams
+from mcp.shared._httpx_utils import create_mcp_http_client
+from mcp.shared.inbound import MCP_PROTOCOL_VERSION_HEADER
+from mcp.shared.message import ClientMessageMetadata, SessionMessage
 
 logger = logging.getLogger(__name__)
 

src/mcp/server/_otel.py

@@ -2,13 +2,13 @@ from __future__ import annotations
 
 from typing import Any
 
+from mcp_types import INVALID_PARAMS, CallToolResult
 from opentelemetry.trace import SpanKind, StatusCode
 from pydantic import ValidationError
 
 from mcp.server.context import CallNext, HandlerResult, ServerMiddleware, ServerRequestContext
 from mcp.shared._otel import extract_trace_context, otel_span
 from mcp.shared.exceptions import MCPError
-from mcp.types import INVALID_PARAMS, CallToolResult
 
 
 class OpenTelemetryMiddleware(ServerMiddleware[Any]):

src/mcp/server/_streamable_http_modern.py

@@ -19,6 +19,18 @@ from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any, TypeVar
 
 import anyio
+from mcp_types import (
+    INTERNAL_ERROR,
+    INVALID_REQUEST,
+    PARSE_ERROR,
+    ClientCapabilities,
+    ErrorData,
+    Implementation,
+    JSONRPCError,
+    JSONRPCRequest,
+    JSONRPCResponse,
+    RequestId,
+)
 from pydantic import BaseModel, ValidationError
 from starlette.requests import Request
 from starlette.responses import Response
@@ -33,18 +45,6 @@ from mcp.shared.inbound import ERROR_CODE_HTTP_STATUS, InboundLadderRejection, c
 from mcp.shared.jsonrpc_dispatcher import handler_exception_to_error_data
 from mcp.shared.message import MessageMetadata, ServerMessageMetadata
 from mcp.shared.transport_context import TransportContext
-from mcp.types import (
-    INTERNAL_ERROR,
-    INVALID_REQUEST,
-    PARSE_ERROR,
-    ClientCapabilities,
-    ErrorData,
-    Implementation,
-    JSONRPCError,
-    JSONRPCRequest,
-    JSONRPCResponse,
-    RequestId,
-)
 
 if TYPE_CHECKING:
     from mcp.server.lowlevel.server import Server

src/mcp/server/connection.py

@@ -25,14 +25,7 @@ from contextlib import AsyncExitStack
 from typing import Any, TypeVar, overload
 
 import anyio
-from pydantic import BaseModel
-from typing_extensions import deprecated
-
-from mcp.shared.dispatcher import CallOptions, Outbound
-from mcp.shared.exceptions import MCPDeprecationWarning, NoBackChannelError
-from mcp.shared.peer import Meta, dump_params
-from mcp.shared.version import LATEST_HANDSHAKE_VERSION
-from mcp.types import (
+from mcp_types import (
     ClientCapabilities,
     CreateMessageRequest,
     CreateMessageResult,
@@ -47,7 +40,14 @@ from mcp.types import (
     PingRequest,
     Request,
 )
-from mcp.types import methods as _methods
+from mcp_types import methods as _methods
+from mcp_types.version import LATEST_HANDSHAKE_VERSION
+from pydantic import BaseModel
+from typing_extensions import deprecated
+
+from mcp.shared.dispatcher import CallOptions, Outbound
+from mcp.shared.exceptions import MCPDeprecationWarning, NoBackChannelError
+from mcp.shared.peer import Meta, dump_params
 
 __all__ = ["Connection"]
 

src/mcp/server/context.py

@@ -2,6 +2,7 @@ from collections.abc import Awaitable, Callable, Mapping
 from dataclasses import dataclass
 from typing import Any, Generic, Protocol
 
+from mcp_types import LoggingLevel, RequestId, RequestParamsMeta
 from pydantic import BaseModel
 from typing_extensions import TypeVar, deprecated
 
@@ -13,7 +14,6 @@ from mcp.shared.exceptions import MCPDeprecationWarning
 from mcp.shared.message import CloseSSEStreamCallback
 from mcp.shared.peer import Meta
 from mcp.shared.transport_context import TransportContext
-from mcp.types import LoggingLevel, RequestId, RequestParamsMeta
 
 # Invariant: parametrizes a mutable dataclass field; dict default matches the default lifespan.
 LifespanContextT = TypeVar("LifespanContextT", default=dict[str, Any])

src/mcp/server/elicitation.py

@@ -4,15 +4,15 @@ from __future__ import annotations
 
 from typing import Any, Generic, Literal, TypeVar
 
+from mcp_types import RequestId
+
+# Internal surface package; imported as the gate's source of truth for spec-valid property schemas.
+from mcp_types.v2025_11_25 import PrimitiveSchemaDefinition
 from pydantic import BaseModel, ValidationError
 from pydantic.json_schema import GenerateJsonSchema, JsonSchemaValue
 from pydantic_core import core_schema
 
 from mcp.server.session import ServerSession
-from mcp.types import RequestId
-
-# Internal surface package; imported as the gate's source of truth for spec-valid property schemas.
-from mcp.types.v2025_11_25 import PrimitiveSchemaDefinition
 
 ElicitSchemaModelT = TypeVar("ElicitSchemaModelT", bound=BaseModel)
 

src/mcp/server/lowlevel/server.py

@@ -43,6 +43,8 @@ from dataclasses import dataclass
 from importlib.metadata import version as importlib_version
 from typing import Any, Generic
 
+import mcp_types as types
+from mcp_types.version import MODERN_PROTOCOL_VERSIONS
 from pydantic import BaseModel
 from starlette.applications import Starlette
 from starlette.middleware import Middleware
@@ -50,7 +52,6 @@ from starlette.middleware.authentication import AuthenticationMiddleware
 from starlette.routing import Mount, Route
 from typing_extensions import TypeVar
 
-from mcp import types
 from mcp.server.auth.middleware.auth_context import AuthContextMiddleware
 from mcp.server.auth.middleware.bearer_auth import BearerAuthBackend, RequireAuthMiddleware
 from mcp.server.auth.provider import OAuthAuthorizationServerProvider, TokenVerifier
@@ -64,7 +65,6 @@ from mcp.server.streamable_http_manager import StreamableHTTPASGIApp, Streamable
 from mcp.server.transport_security import TransportSecuritySettings
 from mcp.shared._stream_protocols import ReadStream, WriteStream
 from mcp.shared.message import SessionMessage
-from mcp.shared.version import MODERN_PROTOCOL_VERSIONS
 
 logger = logging.getLogger(__name__)
 

src/mcp/server/mcpserver/__init__.py

@@ -1,6 +1,6 @@
 """MCPServer - A more ergonomic interface for MCP servers."""
 
-from mcp.types import Icon
+from mcp_types import Icon
 
 from .context import Context
 from .server import MCPServer

src/mcp/server/mcpserver/context.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 from collections.abc import Iterable
 from typing import TYPE_CHECKING, Any, Generic
 
+from mcp_types import LoggingLevel
 from pydantic import AnyUrl, BaseModel
 from typing_extensions import deprecated
 
@@ -16,7 +17,6 @@ from mcp.server.elicitation import (
 )
 from mcp.server.lowlevel.helper_types import ReadResourceContents
 from mcp.shared.exceptions import MCPDeprecationWarning
-from mcp.types import LoggingLevel
 
 if TYPE_CHECKING:
     from mcp.server.mcpserver.server import MCPServer

src/mcp/server/mcpserver/prompts/base.py

@@ -8,12 +8,12 @@ from typing import TYPE_CHECKING, Any, Literal
 
 import anyio.to_thread
 import pydantic_core
+from mcp_types import ContentBlock, Icon, TextContent
 from pydantic import BaseModel, Field, TypeAdapter, validate_call
 
 from mcp.server.mcpserver.utilities.context_injection import find_context_parameter, inject_context
 from mcp.server.mcpserver.utilities.func_metadata import func_metadata
 from mcp.shared._callable_inspection import is_async_callable
-from mcp.types import ContentBlock, Icon, TextContent
 
 if TYPE_CHECKING:
     from mcp.server.context import LifespanContextT, RequestT