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

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

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

@@ -3,6 +3,7 @@
 import abc
 from typing import Any
 
+from mcp_types import Annotations, Icon
 from pydantic import (
     BaseModel,
     ConfigDict,
@@ -11,8 +12,6 @@ from pydantic import (
     field_validator,
 )
 
-from mcp.types import Annotations, Icon
-
 
 class Resource(BaseModel, abc.ABC):
     """Base class for all resources."""

src/mcp/server/mcpserver/resources/resource_manager.py

@@ -5,13 +5,13 @@ from __future__ import annotations
 from collections.abc import Callable
 from typing import TYPE_CHECKING, Any
 
+from mcp_types import Annotations, Icon
 from pydantic import AnyUrl
 
 from mcp.server.mcpserver.exceptions import ResourceNotFoundError
 from mcp.server.mcpserver.resources.base import Resource
 from mcp.server.mcpserver.resources.templates import ResourceTemplate
 from mcp.server.mcpserver.utilities.logging import get_logger
-from mcp.types import Annotations, Icon
 
 if TYPE_CHECKING:
     from mcp.server.context import LifespanContextT, RequestT

src/mcp/server/mcpserver/resources/templates.py

@@ -9,6 +9,7 @@ from typing import TYPE_CHECKING, Any
 from urllib.parse import unquote
 
 import anyio.to_thread
+from mcp_types import Annotations, Icon
 from pydantic import BaseModel, Field, validate_call
 
 from mcp.server.mcpserver.exceptions import ResourceError
@@ -17,7 +18,6 @@ from mcp.server.mcpserver.utilities.context_injection import find_context_parame
 from mcp.server.mcpserver.utilities.func_metadata import func_metadata
 from mcp.server.mcpserver.utilities.logging import get_logger
 from mcp.shared._callable_inspection import is_async_callable
-from mcp.types import Annotations, Icon
 
 logger = get_logger(__name__)
 

src/mcp/server/mcpserver/resources/types.py

@@ -12,11 +12,11 @@ import anyio.to_thread
 import httpx
 import pydantic
 import pydantic_core
+from mcp_types import Annotations, Icon
 from pydantic import Field, ValidationInfo, validate_call
 
 from mcp.server.mcpserver.resources.base import Resource
 from mcp.shared._callable_inspection import is_async_callable
-from mcp.types import Annotations, Icon
 
 
 class TextResource(Resource):

src/mcp/server/mcpserver/server.py

@@ -11,6 +11,35 @@ from typing import Any, Generic, Literal, TypeVar, overload
 
 import anyio
 import pydantic_core
+from mcp_types import (
+    INTERNAL_ERROR,
+    INVALID_PARAMS,
+    Annotations,
+    BlobResourceContents,
+    CallToolRequestParams,
+    CallToolResult,
+    CompleteRequestParams,
+    CompleteResult,
+    Completion,
+    GetPromptRequestParams,
+    GetPromptResult,
+    Icon,
+    ListPromptsResult,
+    ListResourcesResult,
+    ListResourceTemplatesResult,
+    ListToolsResult,
+    PaginatedRequestParams,
+    ReadResourceRequestParams,
+    ReadResourceResult,
+    TextContent,
+    TextResourceContents,
+    ToolAnnotations,
+)
+from mcp_types import Prompt as MCPPrompt
+from mcp_types import PromptArgument as MCPPromptArgument
+from mcp_types import Resource as MCPResource
+from mcp_types import ResourceTemplate as MCPResourceTemplate
+from mcp_types import Tool as MCPTool
 from pydantic.networks import AnyUrl
 from pydantic_settings import BaseSettings, SettingsConfigDict
 from starlette.applications import Starlette
@@ -42,35 +71,6 @@ from mcp.server.streamable_http import EventStore
 from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
 from mcp.server.transport_security import TransportSecuritySettings
 from mcp.shared.exceptions import MCPError
-from mcp.types import (
-    INTERNAL_ERROR,
-    INVALID_PARAMS,
-    Annotations,
-    BlobResourceContents,
-    CallToolRequestParams,
-    CallToolResult,
-    CompleteRequestParams,
-    CompleteResult,
-    Completion,
-    GetPromptRequestParams,
-    GetPromptResult,
-    Icon,
-    ListPromptsResult,
-    ListResourcesResult,
-    ListResourceTemplatesResult,
-    ListToolsResult,
-    PaginatedRequestParams,
-    ReadResourceRequestParams,
-    ReadResourceResult,
-    TextContent,
-    TextResourceContents,
-    ToolAnnotations,
-)
-from mcp.types import Prompt as MCPPrompt
-from mcp.types import PromptArgument as MCPPromptArgument
-from mcp.types import Resource as MCPResource
-from mcp.types import ResourceTemplate as MCPResourceTemplate
-from mcp.types import Tool as MCPTool
 
 logger = get_logger(__name__)
 

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

@@ -4,6 +4,7 @@ from collections.abc import Callable
 from functools import cached_property
 from typing import TYPE_CHECKING, Any
 
+from mcp_types import Icon, ToolAnnotations
 from pydantic import BaseModel, Field
 
 from mcp.server.mcpserver.exceptions import ToolError
@@ -12,7 +13,6 @@ from mcp.server.mcpserver.utilities.func_metadata import FuncMetadata, func_meta
 from mcp.shared._callable_inspection import is_async_callable
 from mcp.shared.exceptions import MCPError
 from mcp.shared.tool_name_validation import validate_and_warn_tool_name
-from mcp.types import Icon, ToolAnnotations
 
 if TYPE_CHECKING:
     from mcp.server.context import LifespanContextT, RequestT

src/mcp/server/mcpserver/tools/tool_manager.py

@@ -3,10 +3,11 @@ from __future__ import annotations
 from collections.abc import Callable
 from typing import TYPE_CHECKING, Any
 
+from mcp_types import Icon, ToolAnnotations
+
 from mcp.server.mcpserver.exceptions import ToolError
 from mcp.server.mcpserver.tools.base import Tool
 from mcp.server.mcpserver.utilities.logging import get_logger
-from mcp.types import Icon, ToolAnnotations
 
 if TYPE_CHECKING:
     from mcp.server.context import LifespanContextT, RequestT

src/mcp/server/mcpserver/utilities/func_metadata.py

@@ -9,6 +9,7 @@ from typing import Annotated, Any, cast, get_args, get_origin, get_type_hints
 import anyio
 import anyio.to_thread
 import pydantic_core
+from mcp_types import CallToolResult, ContentBlock, TextContent
 from pydantic import BaseModel, ConfigDict, Field, PydanticUserError, WithJsonSchema, create_model
 from pydantic.fields import FieldInfo
 from pydantic.json_schema import GenerateJsonSchema, JsonSchemaWarningKind
@@ -24,7 +25,6 @@ from typing_inspection.introspection import (
 from mcp.server.mcpserver.exceptions import InvalidSignature
 from mcp.server.mcpserver.utilities.logging import get_logger
 from mcp.server.mcpserver.utilities.types import Audio, Image
-from mcp.types import CallToolResult, ContentBlock, TextContent
 
 logger = get_logger(__name__)
 

src/mcp/server/mcpserver/utilities/types.py

@@ -3,7 +3,7 @@
 import base64
 from pathlib import Path
 
-from mcp.types import AudioContent, ImageContent
+from mcp_types import AudioContent, ImageContent
 
 
 class Image:

src/mcp/server/models.py

@@ -2,10 +2,9 @@
 and tools.
 """
 
+from mcp_types import Icon, ServerCapabilities
 from pydantic import BaseModel
 
-from mcp.types import Icon, ServerCapabilities
-
 
 class InitializationOptions(BaseModel):
     server_name: str

src/mcp/server/runner.py

@@ -21,6 +21,22 @@ from typing import TYPE_CHECKING, Any, Generic, cast
 
 import anyio
 import anyio.abc
+from mcp_types import (
+    CLIENT_CAPABILITIES_META_KEY,
+    CLIENT_INFO_META_KEY,
+    INTERNAL_ERROR,
+    INVALID_PARAMS,
+    METHOD_NOT_FOUND,
+    PROTOCOL_VERSION_META_KEY,
+    ErrorData,
+    Implementation,
+    InitializeRequestParams,
+    InitializeResult,
+    RequestParams,
+    RequestParamsMeta,
+)
+from mcp_types import methods as _methods
+from mcp_types.version import HANDSHAKE_PROTOCOL_VERSIONS, LATEST_HANDSHAKE_VERSION, LATEST_MODERN_VERSION
 from opentelemetry.trace import SpanKind, StatusCode
 from pydantic import BaseModel, ValidationError
 from typing_extensions import TypeVar
@@ -36,22 +52,6 @@ from mcp.shared.exceptions import MCPError
 from mcp.shared.jsonrpc_dispatcher import JSONRPCDispatcher
 from mcp.shared.message import ServerMessageMetadata, SessionMessage
 from mcp.shared.transport_context import TransportContext
-from mcp.shared.version import HANDSHAKE_PROTOCOL_VERSIONS, LATEST_HANDSHAKE_VERSION, LATEST_MODERN_VERSION
-from mcp.types import (
-    CLIENT_CAPABILITIES_META_KEY,
-    CLIENT_INFO_META_KEY,
-    INTERNAL_ERROR,
-    INVALID_PARAMS,
-    METHOD_NOT_FOUND,
-    PROTOCOL_VERSION_META_KEY,
-    ErrorData,
-    Implementation,
-    InitializeRequestParams,
-    InitializeResult,
-    RequestParams,
-    RequestParamsMeta,
-)
-from mcp.types import methods as _methods
 
 if TYPE_CHECKING:
     from mcp.server.lowlevel.server import Server