feat: deprecate cursor parameter in favor of params for list methods

Deprecate the cursor parameter in list_tools, list_prompts, list_resources,
and list_resource_templates methods, replacing it with a new params parameter
that accepts PaginatedRequestParams.

This change maintains complete backwards compatibility while providing opt-in
support for strict MCP servers that require the params field to always be
present in JSON-RPC requests (even if empty). When params is not provided or
is None, the SDK continues to omit the params field entirely, matching the
previous behavior.

The cursor parameter now issues a DeprecationWarning directing developers to
use the new params parameter. This matches the TypeScript SDK's API design.

Reported-by: justin-yi-wang

Author: felixweinberger

src/mcp/client/session.py

@@ -1,4 +1,5 @@
 import logging
+import warnings
 from datetime import timedelta
 from typing import Any, Protocol
 
@@ -212,25 +213,55 @@ async def set_logging_level(self, level: types.LoggingLevel) -> types.EmptyResul
             types.EmptyResult,
         )
 
-    async def list_resources(self, cursor: str | None = None) -> types.ListResourcesResult:
-        """Send a resources/list request."""
+    async def list_resources(
+        self,
+        cursor: str | None = None,
+        *,
+        params: types.PaginatedRequestParams | None = None,
+    ) -> types.ListResourcesResult:
+        """Send a resources/list request.
+
+        Args:
+            cursor: (Deprecated) Pagination cursor. Use params parameter instead.
+            params: Pagination parameters. Defaults to None (omits params field).
+        """
+        if cursor is not None:
+            warnings.warn(
+                "cursor parameter is deprecated, use params=PaginatedRequestParams(cursor=...) instead",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            if params is None:
+                params = types.PaginatedRequestParams(cursor=cursor)
+
         return await self.send_request(
-            types.ClientRequest(
-                types.ListResourcesRequest(
-                    params=types.PaginatedRequestParams(cursor=cursor),
-                )
-            ),
+            types.ClientRequest(types.ListResourcesRequest(params=params)),
             types.ListResourcesResult,
         )
 
-    async def list_resource_templates(self, cursor: str | None = None) -> types.ListResourceTemplatesResult:
-        """Send a resources/templates/list request."""
+    async def list_resource_templates(
+        self,
+        cursor: str | None = None,
+        *,
+        params: types.PaginatedRequestParams | None = None,
+    ) -> types.ListResourceTemplatesResult:
+        """Send a resources/templates/list request.
+
+        Args:
+            cursor: (Deprecated) Pagination cursor. Use params parameter instead.
+            params: Pagination parameters. Defaults to None (omits params field).
+        """
+        if cursor is not None:
+            warnings.warn(
+                "cursor parameter is deprecated, use params=PaginatedRequestParams(cursor=...) instead",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            if params is None:
+                params = types.PaginatedRequestParams(cursor=cursor)
+
         return await self.send_request(
-            types.ClientRequest(
-                types.ListResourceTemplatesRequest(
-                    params=types.PaginatedRequestParams(cursor=cursor),
-                )
-            ),
+            types.ClientRequest(types.ListResourceTemplatesRequest(params=params)),
             types.ListResourceTemplatesResult,
         )
 
@@ -317,14 +348,29 @@ async def _validate_tool_result(self, name: str, result: types.CallToolResult) -
             except SchemaError as e:
                 raise RuntimeError(f"Invalid schema for tool {name}: {e}")
 
-    async def list_prompts(self, cursor: str | None = None) -> types.ListPromptsResult:
-        """Send a prompts/list request."""
+    async def list_prompts(
+        self,
+        cursor: str | None = None,
+        *,
+        params: types.PaginatedRequestParams | None = None,
+    ) -> types.ListPromptsResult:
+        """Send a prompts/list request.
+
+        Args:
+            cursor: (Deprecated) Pagination cursor. Use params parameter instead.
+            params: Pagination parameters. Defaults to None (omits params field).
+        """
+        if cursor is not None:
+            warnings.warn(
+                "cursor parameter is deprecated, use params=PaginatedRequestParams(cursor=...) instead",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            if params is None:
+                params = types.PaginatedRequestParams(cursor=cursor)
+
         return await self.send_request(
-            types.ClientRequest(
-                types.ListPromptsRequest(
-                    params=types.PaginatedRequestParams(cursor=cursor),
-                )
-            ),
+            types.ClientRequest(types.ListPromptsRequest(params=params)),
             types.ListPromptsResult,
         )
 
@@ -363,14 +409,29 @@ async def complete(
             types.CompleteResult,
         )
 
-    async def list_tools(self, cursor: str | None = None) -> types.ListToolsResult:
-        """Send a tools/list request."""
+    async def list_tools(
+        self,
+        cursor: str | None = None,
+        *,
+        params: types.PaginatedRequestParams | None = None,
+    ) -> types.ListToolsResult:
+        """Send a tools/list request.
+
+        Args:
+            cursor: (Deprecated) Pagination cursor. Use params parameter instead.
+            params: Pagination parameters. Defaults to None (omits params field).
+        """
+        if cursor is not None:
+            warnings.warn(
+                "cursor parameter is deprecated, use params=PaginatedRequestParams(cursor=...) instead",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            if params is None:
+                params = types.PaginatedRequestParams(cursor=cursor)
+
         result = await self.send_request(
-            types.ClientRequest(
-                types.ListToolsRequest(
-                    params=types.PaginatedRequestParams(cursor=cursor),
-                )
-            ),
+            types.ClientRequest(types.ListToolsRequest(params=params)),
             types.ListToolsResult,
         )
 

tests/client/test_list_methods_cursor.py

@@ -2,6 +2,7 @@
 
 import pytest
 
+import mcp.types as types
 from mcp.server import Server
 from mcp.server.fastmcp import FastMCP
 from mcp.shared.memory import create_connected_server_and_client_session as create_session
@@ -12,6 +13,7 @@
 pytestmark = pytest.mark.anyio
 
 
+@pytest.mark.filterwarnings("ignore::DeprecationWarning")
 async def test_list_tools_cursor_parameter(stream_spy: Callable[[], StreamSpyCollection]):
     """Test that the cursor parameter is accepted for list_tools
     and that it is correctly passed to the server.
@@ -38,15 +40,15 @@ async def test_tool_2() -> str:
         _ = await client_session.list_tools()
         list_tools_requests = spies.get_client_requests(method="tools/list")
         assert len(list_tools_requests) == 1
-        assert list_tools_requests[0].params == {}
+        assert list_tools_requests[0].params is None
 
         spies.clear()
 
         # Test with cursor=None
         _ = await client_session.list_tools(cursor=None)
         list_tools_requests = spies.get_client_requests(method="tools/list")
         assert len(list_tools_requests) == 1
-        assert list_tools_requests[0].params == {}
+        assert list_tools_requests[0].params is None
 
         spies.clear()
 
@@ -67,6 +69,7 @@ async def test_tool_2() -> str:
         assert list_tools_requests[0].params["cursor"] == ""
 
 
+@pytest.mark.filterwarnings("ignore::DeprecationWarning")
 async def test_list_resources_cursor_parameter(stream_spy: Callable[[], StreamSpyCollection]):
     """Test that the cursor parameter is accepted for list_resources
     and that it is correctly passed to the server.
@@ -88,15 +91,15 @@ async def test_resource() -> str:
         _ = await client_session.list_resources()
         list_resources_requests = spies.get_client_requests(method="resources/list")
         assert len(list_resources_requests) == 1
-        assert list_resources_requests[0].params == {}
+        assert list_resources_requests[0].params is None
 
         spies.clear()
 
         # Test with cursor=None
         _ = await client_session.list_resources(cursor=None)
         list_resources_requests = spies.get_client_requests(method="resources/list")
         assert len(list_resources_requests) == 1
-        assert list_resources_requests[0].params == {}
+        assert list_resources_requests[0].params is None
 
         spies.clear()
 
@@ -117,6 +120,7 @@ async def test_resource() -> str:
         assert list_resources_requests[0].params["cursor"] == ""
 
 
+@pytest.mark.filterwarnings("ignore::DeprecationWarning")
 async def test_list_prompts_cursor_parameter(stream_spy: Callable[[], StreamSpyCollection]):
     """Test that the cursor parameter is accepted for list_prompts
     and that it is correctly passed to the server.
@@ -137,15 +141,15 @@ async def test_prompt(name: str) -> str:
         _ = await client_session.list_prompts()
         list_prompts_requests = spies.get_client_requests(method="prompts/list")
         assert len(list_prompts_requests) == 1
-        assert list_prompts_requests[0].params == {}
+        assert list_prompts_requests[0].params is None
 
         spies.clear()
 
         # Test with cursor=None
         _ = await client_session.list_prompts(cursor=None)
         list_prompts_requests = spies.get_client_requests(method="prompts/list")
         assert len(list_prompts_requests) == 1
-        assert list_prompts_requests[0].params == {}
+        assert list_prompts_requests[0].params is None
 
         spies.clear()
 
@@ -166,6 +170,7 @@ async def test_prompt(name: str) -> str:
         assert list_prompts_requests[0].params["cursor"] == ""
 
 
+@pytest.mark.filterwarnings("ignore::DeprecationWarning")
 async def test_list_resource_templates_cursor_parameter(stream_spy: Callable[[], StreamSpyCollection]):
     """Test that the cursor parameter is accepted for list_resource_templates
     and that it is correctly passed to the server.
@@ -187,15 +192,15 @@ async def test_template(name: str) -> str:
         _ = await client_session.list_resource_templates()
         list_templates_requests = spies.get_client_requests(method="resources/templates/list")
         assert len(list_templates_requests) == 1
-        assert list_templates_requests[0].params == {}
+        assert list_templates_requests[0].params is None
 
         spies.clear()
 
         # Test with cursor=None
         _ = await client_session.list_resource_templates(cursor=None)
         list_templates_requests = spies.get_client_requests(method="resources/templates/list")
         assert len(list_templates_requests) == 1
-        assert list_templates_requests[0].params == {}
+        assert list_templates_requests[0].params is None
 
         spies.clear()
 
@@ -244,5 +249,6 @@ async def handle_list_tools(request: ListToolsRequest) -> ListToolsResult:
         return ListToolsResult(tools=[])
 
     async with create_session(server) as client_session:
-        result = await client_session.list_tools()
+        # Use params to explicitly send params: {} for strict server compatibility
+        result = await client_session.list_tools(params=types.PaginatedRequestParams())
         assert result is not None