fix: send params as empty object for list methods without cursor

[felixweinberger]

Motivation and Context

Some external MCP servers implement strict JSON-RPC validation requiring the params field to always be present. Previously, the Python SDK omitted params entirely when cursor=None, causing validation errors. There is no way to force params={} with the current implementation of list_tools(), making it not possible to interact with these servers.

This change allows sending params: {} by allowing the caller to specify a full types.PaginatedRequestParams rather than just cursor, matching TypeScript SDK flexibility and allowing more compatibility with strict servers. We achieve this by introducing a new optional param params: types.PaginatedRequestParams | None = None which will be the new way to interact with this API.

How Has This Been Tested?

Added a test demonstrating the specific behavior as well the new param.
Refactored the existing tests to be parameterized.

Breaking Changes

This change is fully backwards compatible as existing behavior stays the same and the new param is completely optional.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

[felixweinberger]

Re-evaluating the approach here, as we're basically making the params={} the default behavior with this when no cursor is supplied. The TS SDK allows both via:

// explicit {} param
const result = await client.listTools({});

// undefined param, gets ommited by JSON.stringify()
const result = await client.listTools();

Whereas with this change we would now always force list_tools(params={}) in Python. Maybe the better approach is to allow both {} and None in Python on list_tools() somehow.

The spec defines ListToolRequest with both fields as optional:

interface ListToolsRequest {
  method: “tools/list”;
  params?: { cursor?: string };
}

https://modelcontextprotocol.io/specification/2025-06-18/schema#listtoolsrequest

An alternative solution could be to change the signature of list_tools to something like:

  async def list_tools(
      self,
      cursor: str | None = None, # deprecated
      *,
      params: types.PaginatedRequestParams | None = None,
  ) -> types.ListToolsResult:

Which would be more complete and equivalent to TS capabilities here: https://github.com/modelcontextprotocol/typescript-sdk/blob/f4b8a48ded019a54a38d3d150a013427d6cbdbc6/src/client/index.ts#L500-L514

[felixweinberger]

Updated this PR with the approach described in the above comment.

This PR is probably easier to review looking at each commit, as I also took the chance to refactor tests for less repetition in the last commit.

[maxisbey]

I think doing something like this would help as it gives errors in the IDE if you use the wrong signature:

    @overload
    async def list_resources(self, cursor: str) -> types.ListResourcesResult: ...

    @overload
    async def list_resources(self, *, params: types.PaginatedRequestParams) -> types.ListResourcesResult: ...

    @overload
    async def list_resources(self) -> types.ListResourcesResult: ...

    @deprecated
    async def list_resources(
        self,
        cursor: str | None = None,
        *,
        params: types.PaginatedRequestParams | None = None,
    ) -> types.ListResourcesResult:
        """Send a resources/list request.

        Args:
            cursor: Simple cursor string for pagination (deprecated, use params instead)
            params: Full pagination parameters including cursor and any future fields
        """
        if params is not None and cursor is not None:
            raise ValueError("Cannot specify both cursor and params")

        if params is not None:
            request_params = params
        elif cursor is not None:
            request_params = types.PaginatedRequestParams(cursor=cursor)
        else:
            request_params = None

        return await self.send_request(
            types.ClientRequest(types.ListResourcesRequest(params=request_params)),
            types.ListResourcesResult,
        )

For testing here's a script which will show errors in pyright and your IDE:

"""Test file to verify overload typing works correctly."""

import asyncio

from mcp.client.session import ClientSession
from mcp.types import PaginatedRequestParams


async def test_overload_typing() -> None:
    """Test different ways of calling list_resources."""
    # This is just for type checking, we don't actually run it
    session: ClientSession = None  # type: ignore

    # Should work: no arguments
    result1 = await session.list_resources()

    # Should work: cursor as positional string
    result2 = await session.list_resources("some_cursor")

    # Should work: cursor as keyword string
    result3 = await session.list_resources(cursor="some_cursor")

    # Should work: params as keyword argument
    result4 = await session.list_resources(params=PaginatedRequestParams(cursor="some_cursor"))

    # Should ERROR: both cursor and params
    result5 = await session.list_resources(cursor="some_cursor", params=PaginatedRequestParams(cursor="other"))

    # Should ERROR: cursor=None (overload expects str, not str | None)
    result6 = await session.list_resources(cursor=None)

    # Should ERROR: params as positional
    result7 = await session.list_resources(PaginatedRequestParams(cursor="some_cursor"))


if __name__ == "__main__":
    asyncio.run(test_overload_typing())

[felixweinberger]

@maxisbey implemented the @overload approach in commit on top.

However I think the decorator was in the wrong place - it should only be on the old signature, i.e. list_tools(self, cursor: str | None).

I.e. I think the type errors should look like this (what it looks like with the current branch):

What this looks like on hover: