[DOC] simple mcp client with sampling capability

[yarnabrina]

Motivation and Context

The is no documented MCP client example how to support MCP servers using sampling capability. This PR attempts to add a basic example.

How Has This Been Tested?

This changes are subset of my personal repository. It is not tested in a production system, but thoroughly tested locally.

Breaking Changes

No

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

Related #1205
Closes #539

[yarnabrina]

@maxisbey @felixweinberger here's the first attempt, please have a look.

[yarnabrina]

@felixweinberger @maxisbey updated with the main branch, requesting review.

[yarnabrina]

@felixweinberger @maxisbey while waiting for the review, can you please help me understand why is CI failing? The failures with respect to missing files or in files under src are not changes introduced here, so should have failed in other PR's as well as in main based on my understanding.

[felixweinberger]

@felixweinberger @maxisbey while waiting for the review, can you please help me understand why is CI failing? The failures with respect to missing files or in files under src are not changes introduced here, so should have failed in other PR's as well as in main based on my understanding.

Looks like you have a bunch of typing failures:

pyright..................................................................Failed
- hook id: pyright
- duration: 9.61s
- exit code: 1

WARNING: there is a new pyright version available (v1.1.405 -> v1.1.406).
Please install the new version or set PYRIGHT_PYTHON_FORCE_VERSION to `latest`

/home/runner/work/python-sdk/python-sdk/src/mcp/cli/__init__.py
  /home/runner/work/python-sdk/python-sdk/src/mcp/cli/__init__.py:3:18 - error: Type of "app" is unknown (reportUnknownVariableType)
/home/runner/work/python-sdk/python-sdk/src/mcp/cli/cli.py
  /home/runner/work/python-sdk/python-sdk/src/mcp/cli/cli.py:15:12 - error: Import "typer" could not be resolved (reportMissingImports)
  /home/runner/work/python-sdk/python-sdk/src/mcp/cli/cli.py:34:1 - error: Type of "app" is unknown (reportUnknownVariableType)
  /home/runner/work/python-sdk/python-sdk/src/mcp/cli/cli.py:34:7 - error: Type of "Typer" is unknown (reportUnknownMemberType)
  /home/runner/work/python-sdk/python-sdk/src/mcp/cli/cli.py:211:2 - error: Type of "command" is unknown (reportUnknownMemberType)
  /home/runner/work/python-sdk/python-sdk/src/mcp/cli/cli.py:211:2 - error: Untyped function decorator obscures type of function; ignoring decorator (reportUntypedFunctionDecorator)
  /home/runner/work/python-sdk/python-sdk/src/mcp/cli/cli.py:222:2 - error: Type of "command" is unknown (reportUnknownMemberType)
  /home/runner/work/python-sdk/python-sdk/src/mcp/cli/cli.py:222:2 - error: Untyped function decorator obscures type of function; ignoring decorator (reportUntypedFunctionDecorator)
  /home/runner/work/python-sdk/python-sdk/src/mcp/cli/cli.py:224:22 - error: Type of "Argument" is unknown (reportUnknownMemberType)
  /home/runner/work/python-sdk/python-sdk/src/mcp/cli/cli.py:230:9 - error: Type of "Option" is unknown (reportUnknownMemberType)
  /home/runner/work/python-sdk/python-sdk/src/mcp/cli/cli.py:241:9 - error: Type of "Option" is unknown (reportUnknownMemberType)
  /home/runner/work/python-sdk/python-sdk/src/mcp/cli/cli.py:305:2 - error: Type of "command" is unknown (reportUnknownMemberType)
  /home/runner/work/python-sdk/python-sdk/src/mcp/cli/cli.py:305:2 - error: Untyped function decorator obscures type of function; ignoring decorator (reportUntypedFunctionDecorator)
  /home/runner/work/python-sdk/python-sdk/src/mcp/cli/cli.py:307:22 - error: Type of "Argument" is unknown (reportUnknownMemberType)
  /home/runner/work/python-sdk/python-sdk/src/mcp/cli/cli.py:313:9 - error: Type of "Option" is unknown (reportUnknownMemberType)
  /home/runner/work/python-sdk/python-sdk/src/mcp/cli/cli.py:362:2 - error: Type of "command" is unknown (reportUnknownMemberType)
  /home/runner/work/python-sdk/python-sdk/src/mcp/cli/cli.py:362:2 - error: Untyped function decorator obscures type of function; ignoring decorator (reportUntypedFunctionDecorator)
  /home/runner/work/python-sdk/python-sdk/src/mcp/cli/cli.py:364:22 - error: Type of "Argument" is unknown (reportUnknownMemberType)
  /home/runner/work/python-sdk/python-sdk/src/mcp/cli/cli.py:370:9 - error: Type of "Option" is unknown (reportUnknownMemberType)
  /home/runner/work/python-sdk/python-sdk/src/mcp/cli/cli.py:378:9 - error: Type of "Option" is unknown (reportUnknownMemberType)
  /home/runner/work/python-sdk/python-sdk/src/mcp/cli/cli.py:389:9 - error: Type of "Option" is unknown (reportUnknownMemberType)
  /home/runner/work/python-sdk/python-sdk/src/mcp/cli/cli.py:396:9 - error: Type of "Option" is unknown (reportUnknownMemberType)
  /home/runner/work/python-sdk/python-sdk/src/mcp/cli/cli.py:404:9 - error: Type of "Option" is unknown (reportUnknownMemberType)
/home/runner/work/python-sdk/python-sdk/src/mcp/client/websocket.py
  /home/runner/work/python-sdk/python-sdk/src/mcp/client/websocket.py:9:6 - error: Import "websockets.asyncio.client" could not be resolved (reportMissingImports)
  /home/runner/work/python-sdk/python-sdk/src/mcp/client/websocket.py:9:50 - error: Type of "ws_connect" is unknown (reportUnknownVariableType)
  /home/runner/work/python-sdk/python-sdk/src/mcp/client/websocket.py:10:6 - error: Import "websockets.typing" could not be resolved (reportMissingImports)
  /home/runner/work/python-sdk/python-sdk/src/mcp/client/websocket.py:10:31 - error: Type of "Subprotocol" is unknown (reportUnknownVariableType)
  /home/runner/work/python-sdk/python-sdk/src/mcp/client/websocket.py:49:70 - error: Type of "ws" is unknown (reportUnknownVariableType)
  /home/runner/work/python-sdk/python-sdk/src/mcp/client/websocket.py:57:27 - error: Type of "raw_text" is unknown (reportUnknownVariableType)
  /home/runner/work/python-sdk/python-sdk/src/mcp/client/websocket.py:59:76 - error: Argument type is unknown
    Argument corresponds to parameter "json_data" in function "model_validate_json" (reportUnknownArgumentType)
  /home/runner/work/python-sdk/python-sdk/src/mcp/client/websocket.py:75:27 - error: Type of "send" is unknown (reportUnknownMemberType)
31 errors, 0 warnings, 0 informations

Are you using any features only available in Python 3.13+? Please make sure any examples fir the repo, i.e. they need to be compatible with 3.10+

[felixweinberger]

Hi @yarnabrina thank you for this contribution.

Could you attach a screen recording or gif to your PR description demonstrating the example? That would make it easier to evaluate it.

Also for examples we aim to not introduce any dependencies on specific model providers like OpenAI or Anthropic - examples should be constructed in such a way that users can easily replace the relevant API calls with whatever provider they need or have access to.

[yarnabrina]

Hi @felixweinberger , I'll check on the openai to generic part, but I'm really not sure what I can do on the type checking part. This PR only adds new files under examples, so I'm not sure I'm following why type check failures are happening under src/mcp. Can you please help me understand that?

Does main branch pass these checks for you?

[I'll update openai to generic calls using requests in a day or two.]

[felixweinberger]

Hi @felixweinberger , I'll check on the openai to generic part, but I'm really not sure what I can do on the type checking part. This PR only adds new files under examples, so I'm not sure I'm following why type check failures are happening under src/mcp. Can you please help me understand that?

Does main branch pass these checks for you?

[I'll update openai to generic calls using requests in a day or two.]

Might have been some test flakes, kicking off another CI run

[felixweinberger]

Hi @felixweinberger , I'll check on the openai to generic part, but I'm really not sure what I can do on the type checking part. This PR only adds new files under examples, so I'm not sure I'm following why type check failures are happening under src/mcp. Can you please help me understand that?

Does main branch pass these checks for you?

[I'll update openai to generic calls using requests in a day or two.]

The problem was adding a restriction for Python 3.13+; this repo runs tests in 3.10, 3.11, 3.12, 3.13 so your examples need to support those. Pushed a commit to this branch here.

[yarnabrina]

@felixweinberger in a fresh clone in my local (windows 11), pyright pre-commit fails with 56 errors. Even though in the CI it seems now pre-commit passes. I need some help to understand what am I missing.

Could you attach a screen recording or gif to your PR description demonstrating the example? That would make it easier to evaluate it.

Attaching a screen recording.

Recording.2025-10-26.013427.mp4