Upload folder using huggingface_hub (part 3)

.mcp-venv/lib/python3.13/site-packages/mcp-2.0.0.dist-info/INSTALLER

@@ -0,0 +1 @@
+pip

.mcp-venv/lib/python3.13/site-packages/mcp-2.0.0.dist-info/METADATA

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: mcp
+Version: 2.0.0
+Summary: Model Context Protocol SDK
+Project-URL: Homepage, https://modelcontextprotocol.io
+Project-URL: Documentation, https://py.sdk.modelcontextprotocol.io/
+Project-URL: Repository, https://github.com/modelcontextprotocol/python-sdk
+Project-URL: Issues, https://github.com/modelcontextprotocol/python-sdk/issues
+Author: Model Context Protocol a Series of LF Projects, LLC.
+Maintainer-email: David Soria Parra <davidsp@anthropic.com>, Marcelo Trylesinski <marcelotryle@gmail.com>, Max Isbey <maxisbey@anthropic.com>, Felix Weinberger <fweinberger@anthropic.com>
+License: MIT
+License-File: LICENSE
+Keywords: automation,llm,mcp
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Requires-Dist: anyio>=4.10; python_version >= '3.14'
+Requires-Dist: anyio>=4.9; python_version < '3.14'
+Requires-Dist: httpx2>=2.5.0
+Requires-Dist: jsonschema>=4.20.0
+Requires-Dist: mcp-types==2.0.0
+Requires-Dist: opentelemetry-api>=1.28.0
+Requires-Dist: pydantic>=2.12.0
+Requires-Dist: pyjwt[crypto]>=2.10.1
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: pywin32>=311; sys_platform == 'win32'
+Requires-Dist: sse-starlette>=3.0.0
+Requires-Dist: starlette>=0.27; python_version < '3.14'
+Requires-Dist: starlette>=0.48.0; python_version >= '3.14'
+Requires-Dist: typing-extensions>=4.13.0
+Requires-Dist: typing-inspection>=0.4.1
+Requires-Dist: uvicorn>=0.31.1; sys_platform != 'emscripten'
+Provides-Extra: cli
+Requires-Dist: python-dotenv>=1.0.0; extra == 'cli'
+Requires-Dist: typer>=0.16.0; extra == 'cli'
+Provides-Extra: rich
+Requires-Dist: rich>=13.9.4; extra == 'rich'
+Description-Content-Type: text/markdown
+
+# MCP Python SDK
+
+<div align="center">
+
+<strong>Python implementation of the Model Context Protocol (MCP)</strong>
+
+[![PyPI][pypi-badge]][pypi-url]
+[![MIT licensed][mit-badge]][mit-url]
+[![Python Version][python-badge]][python-url]
+[![Documentation][docs-badge]][docs-url]
+[![Protocol][protocol-badge]][protocol-url]
+[![Specification][spec-badge]][spec-url]
+
+</div>
+
+> [!NOTE]
+> **This is v2 of the MCP Python SDK, the current stable release line.** It is a major rework of the SDK, both to support the [2026-07-28 MCP specification](https://blog.modelcontextprotocol.io/posts/2026-07-28-release-candidate/) (and every earlier revision) and to fix long-standing architectural issues. Coming from v1? See [What's new in v2](https://py.sdk.modelcontextprotocol.io/whats-new/) for the tour of what changed and the [migration guide](https://py.sdk.modelcontextprotocol.io/migration/) for every breaking change.
+>
+> **Not ready to migrate?** v1.x lives on the [`v1.x` branch](https://github.com/modelcontextprotocol/python-sdk/tree/v1.x), continues to receive critical bug fixes and security patches, and is documented at <https://py.sdk.modelcontextprotocol.io/v1/>. Since `pip install mcp` now installs 2.x, keep a `<2` upper bound on your requirement (for example `mcp>=1.28,<2`) until you've migrated.
+>
+> Something rough, confusing, or broken? [Open an issue](https://github.com/modelcontextprotocol/python-sdk/issues/new?template=v2-feedback.yaml) or find us in [#python-sdk-dev on the MCP Contributors Discord](https://discord.gg/6CSzBmMkjX).
+
+## Documentation
+
+**The documentation lives at <https://py.sdk.modelcontextprotocol.io/>.**
+
+It has a [Get started guide](https://py.sdk.modelcontextprotocol.io/get-started/), [What's new in v2](https://py.sdk.modelcontextprotocol.io/whats-new/), the [API reference](https://py.sdk.modelcontextprotocol.io/api/mcp/), and the [migration guide](https://py.sdk.modelcontextprotocol.io/migration/).
+
+## What is MCP?
+
+The [Model Context Protocol](https://modelcontextprotocol.io) lets you build servers that expose data and functionality to LLM applications in a secure, standardized way. Think of it like a web API, but designed for LLM interactions. With this SDK you can:
+
+- **Build MCP servers** that expose tools, resources, and prompts to any MCP host
+- **Build MCP clients** that connect to any MCP server
+- Speak every standard transport: stdio, Streamable HTTP, and SSE
+
+## Requirements
+
+Python 3.10+.
+
+## Installation
+
+```bash
+uv add "mcp[cli]"      # or: pip install "mcp[cli]"
+```
+
+The `cli` extra adds the `mcp` command-line tool (`mcp dev`, `mcp run`, `mcp install`) on top of the SDK; install plain `mcp` if you don't need it. For one-off commands, `uv run --with "mcp[cli]" mcp ...` works without a project.
+
+## A server in 15 lines
+
+Create a `server.py`:
+
+<!-- snippet-source docs_src/index/tutorial001.py -->
+```python
+from mcp.server import MCPServer
+
+mcp = MCPServer("Demo")
+
+
+@mcp.tool()
+def add(a: int, b: int) -> int:
+    """Add two numbers."""
+    return a + b
+
+
+@mcp.resource("greeting://{name}")
+def greeting(name: str) -> str:
+    """Greet someone by name."""
+    return f"Hello, {name}!"
+```
+
+_Full example: [docs_src/index/tutorial001.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/docs_src/index/tutorial001.py)_
+<!-- /snippet-source -->
+
+That's a complete MCP server: one tool, one templated resource. Open it in the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):
+
+```bash
+uv run mcp dev server.py
+```
+
+Call `add` with `a=1`, `b=2` and you get `3` back.
+
+Notice what you did **not** write: no JSON Schema (`a: int, b: int` _is_ the schema), no request parsing, no validation code, no protocol handling. Two type-hinted Python functions and a docstring.
+
+[Get started](https://py.sdk.modelcontextprotocol.io/get-started/) takes it from here.
+
+## A client in 10 lines
+
+The same package is a full MCP **client**. `Client` connects to a URL, a stdio subprocess, a custom transport, or (for tests) straight to a server object in memory with no transport at all:
+
+```python
+import asyncio
+
+from mcp import Client
+
+from server import mcp
+
+
+async def main() -> None:
+    async with Client(mcp) as client:
+        result = await client.call_tool("add", {"a": 1, "b": 2})
+        print(result.structured_content)  # {'result': 3}
+
+
+asyncio.run(main())
+```
+
+Swap `mcp` for `"http://localhost:8000/mcp"` and the exact same code talks to a remote server.
+
+## Contributing
+
+We are passionate about supporting contributors of all levels of experience and would love to see you get involved in the project. See the [contributing guide](https://github.com/modelcontextprotocol/python-sdk/blob/main/CONTRIBUTING.md) to get started.
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](https://github.com/modelcontextprotocol/python-sdk/blob/main/LICENSE) file for details.
+
+[pypi-badge]: https://img.shields.io/pypi/v/mcp.svg
+[pypi-url]: https://pypi.org/project/mcp/
+[mit-badge]: https://img.shields.io/pypi/l/mcp.svg
+[mit-url]: https://github.com/modelcontextprotocol/python-sdk/blob/main/LICENSE
+[python-badge]: https://img.shields.io/pypi/pyversions/mcp.svg
+[python-url]: https://www.python.org/downloads/
+[docs-badge]: https://img.shields.io/badge/docs-python--sdk-blue.svg
+[docs-url]: https://py.sdk.modelcontextprotocol.io/
+[protocol-badge]: https://img.shields.io/badge/protocol-modelcontextprotocol.io-blue.svg
+[protocol-url]: https://modelcontextprotocol.io
+[spec-badge]: https://img.shields.io/badge/spec-spec.modelcontextprotocol.io-blue.svg
+[spec-url]: https://modelcontextprotocol.io/specification/latest

.mcp-venv/lib/python3.13/site-packages/mcp-2.0.0.dist-info/RECORD

@@ -0,0 +1,253 @@
+../../../bin/mcp,sha256=xBj1o--izDbW5fuime-ORyhoLLs9YnGDWjRI70FA7xA,260
+mcp-2.0.0.dist-info/INSTALLER,sha256=zuuue4knoyJ-UwPPXg8fezS7VCrXJQrAP7zeNuwvFQg,4
+mcp-2.0.0.dist-info/METADATA,sha256=dhx2va06eG7PC3x9nEiw_nvQ484IWrOIpiK95Nvugfk,7708
+mcp-2.0.0.dist-info/RECORD,,
+mcp-2.0.0.dist-info/REQUESTED,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mcp-2.0.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+mcp-2.0.0.dist-info/entry_points.txt,sha256=gnGBbo3yGF0YJNXfZpgkAg1-CQtKxnzxrlA53c8viYA,42
+mcp-2.0.0.dist-info/licenses/LICENSE,sha256=XhPbvB0SD8KgPOzefJFCSuLX3hG2PVje0vRDHiYe5Q0,1071
+mcp/__init__.py,sha256=yYm2cScDTFl5ryD6SimPnb0DsTxSKhlUvI1ZrvsIT5o,3719
+mcp/__pycache__/__init__.cpython-313.pyc,,
+mcp/cli/__init__.py,sha256=CIKfYFV5bAEtsFivmJkY7NHihqKlfp-kbX3lRm6DSqE,103
+mcp/cli/__pycache__/__init__.cpython-313.pyc,,
+mcp/cli/__pycache__/claude.cpython-313.pyc,,
+mcp/cli/__pycache__/cli.cpython-313.pyc,,
+mcp/cli/claude.py,sha256=iXeCBUQMfgT-XBfwOEACQ6ENgpK64c_VIXNiT7O4sQ4,6059
+mcp/cli/cli.py,sha256=5ynhHfRGUjb_0Fll2oCj4LzCJhmTNU5dco7XaqMrCMQ,15152
+mcp/client/__init__.py,sha256=8WMVUrx02eQuKBXU6tD1eEbGnxRAnqTWhBeGHfBIfDk,1033
+mcp/client/__main__.py,sha256=4siuy244dpMqsVPteG3eA4_EY0-PChS3QDteHXWYi7Y,2413
+mcp/client/__pycache__/__init__.cpython-313.pyc,,
+mcp/client/__pycache__/__main__.cpython-313.pyc,,
+mcp/client/__pycache__/_input_required.cpython-313.pyc,,
+mcp/client/__pycache__/_memory.cpython-313.pyc,,
+mcp/client/__pycache__/_probe.cpython-313.pyc,,
+mcp/client/__pycache__/_transport.cpython-313.pyc,,
+mcp/client/__pycache__/caching.cpython-313.pyc,,
+mcp/client/__pycache__/client.cpython-313.pyc,,
+mcp/client/__pycache__/context.cpython-313.pyc,,
+mcp/client/__pycache__/extension.cpython-313.pyc,,
+mcp/client/__pycache__/session.cpython-313.pyc,,
+mcp/client/__pycache__/session_group.cpython-313.pyc,,
+mcp/client/__pycache__/sse.cpython-313.pyc,,
+mcp/client/__pycache__/stdio.cpython-313.pyc,,
+mcp/client/__pycache__/streamable_http.cpython-313.pyc,,
+mcp/client/__pycache__/subscriptions.cpython-313.pyc,,
+mcp/client/_input_required.py,sha256=sVpGcZ0tYuLff0PVWL_EIya4LQ5YOzpc2o7R8nbYgjs,5323
+mcp/client/_memory.py,sha256=nYngTy-aDh97AvTkhMDJohAVVk8SdvakI4Jy-QhlvUM,4938
+mcp/client/_probe.py,sha256=3F8liG_P8Ks-WaQwLVg3iXSuYp8L7td6O9rSU1FiIZI,5392
+mcp/client/_transport.py,sha256=EyPFBefm_GgEu491SKF0Dl1NAj9uKomjXBTGdSTjnUg,695
+mcp/client/auth/__init__.py,sha256=9plDBtxrVeOOXztjjv5JfbsDhwp-YtTQL2kCw7-0h9w,571
+mcp/client/auth/__pycache__/__init__.cpython-313.pyc,,
+mcp/client/auth/__pycache__/exceptions.cpython-313.pyc,,
+mcp/client/auth/__pycache__/oauth2.cpython-313.pyc,,
+mcp/client/auth/__pycache__/utils.cpython-313.pyc,,
+mcp/client/auth/exceptions.py,sha256=uUDHX_P0S3R_tt7oAS8ALQrUgOiV2Dgc0QQAdaaBcW8,264
+mcp/client/auth/extensions/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mcp/client/auth/extensions/__pycache__/__init__.cpython-313.pyc,,
+mcp/client/auth/extensions/__pycache__/client_credentials.cpython-313.pyc,,
+mcp/client/auth/extensions/__pycache__/identity_assertion.cpython-313.pyc,,
+mcp/client/auth/extensions/client_credentials.py,sha256=8qDflJFw8My3BU1RDyqh7eQVePv1UKq6SSoqsMa-6Z4,13367
+mcp/client/auth/extensions/identity_assertion.py,sha256=hRGRFe-fmwQ0Wg5TvsIRtlOwAW1Maf9rkZAZG7H1ygk,10785
+mcp/client/auth/oauth2.py,sha256=kS9D9goCO2awXRAqXyMSr_vMtqYmZE8ZWqZznVLIcXw,38993
+mcp/client/auth/utils.py,sha256=sdqg4jkjCveA_ufPp_OjGADursCJJ0J02Etqqe1oK1M,16547
+mcp/client/caching.py,sha256=LI_zvXquqT9gmaH5G1gkPWHjIfdw8qATGgmHoPWc1qg,17358
+mcp/client/client.py,sha256=JVUXkY1Im2RbKKcUxR4gDeQUET5VTCB0lmgl-3fNRUQ,43293
+mcp/client/context.py,sha256=kC4AOFHdcrAF13DudyTSnekcxhOa7rabQkpawXbhIQc,136
+mcp/client/extension.py,sha256=YfU1M7MYrMRSsmJJ7tw6BrNxB96MFG-38FkiWHBadZs,8428
+mcp/client/session.py,sha256=d6bH690acrZQSK2nLn2nRN4PV9jfyzB2sRJyB5U6I5U,67109
+mcp/client/session_group.py,sha256=pY4ONoN3WdXwfcYrnBmuHBOjxddeofQm3wsbjANbn50,17976
+mcp/client/sse.py,sha256=PMjUSwPQk1A7UzQsK1cYWLJMnCoRELl8gBOaQNI811o,7918
+mcp/client/stdio.py,sha256=vJh5JaPacvTKWczWJ6b8a6JYWC1QUVpTJQOr5tG526s,13827
+mcp/client/streamable_http.py,sha256=bMc_jsfScL8wQzqFxbBaY4Sv3QjVQzaMVBh_lIQOBOU,32909
+mcp/client/subscriptions.py,sha256=5C9MUqbY60E8nArgJmOaFgNnlaDEwfx3sECESN5Wr5Y,11563
+mcp/os/__init__.py,sha256=uqaGIfCF4I0IPeSsEEZMNwZuDF91U0WKAIbDcKzPRLo,43
+mcp/os/__pycache__/__init__.cpython-313.pyc,,
+mcp/os/posix/__init__.py,sha256=l_2j8jhhgw69s_-eH4dCDk4QYxNlxKGIpaOCvcbv1Qk,40
+mcp/os/posix/__pycache__/__init__.cpython-313.pyc,,
+mcp/os/posix/__pycache__/utilities.cpython-313.pyc,,
+mcp/os/posix/utilities.py,sha256=yi36QfVndZKMZs-H1aKG8KS7isQL3E5Y_7h95rkMfVc,2392
+mcp/os/win32/__init__.py,sha256=7xyI7KWpZhDS3omGEBcu3200Q-DjIsS7c-a-vrn28Y4,42
+mcp/os/win32/__pycache__/__init__.cpython-313.pyc,,
+mcp/os/win32/__pycache__/utilities.cpython-313.pyc,,
+mcp/os/win32/utilities.py,sha256=mOh8d2oUzzJuY_jaAHEZFW061kOuf78n6bbm7x3FNL8,10336
+mcp/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mcp/server/__init__.py,sha256=jVxuDGAX-cxe4kLz2rg8WvzsURel4NeEE9g6fI6eqsY,318
+mcp/server/__main__.py,sha256=RTnPFUeIO3xPAkEfZBUenQ0vnBcY59TPTvgOfbetVMQ,585
+mcp/server/__pycache__/__init__.cpython-313.pyc,,
+mcp/server/__pycache__/__main__.cpython-313.pyc,,
+mcp/server/__pycache__/_otel.cpython-313.pyc,,
+mcp/server/__pycache__/_streamable_http_modern.cpython-313.pyc,,
+mcp/server/__pycache__/apps.cpython-313.pyc,,
+mcp/server/__pycache__/caching.cpython-313.pyc,,
+mcp/server/__pycache__/connection.cpython-313.pyc,,
+mcp/server/__pycache__/context.cpython-313.pyc,,
+mcp/server/__pycache__/elicitation.cpython-313.pyc,,
+mcp/server/__pycache__/extension.cpython-313.pyc,,
+mcp/server/__pycache__/models.cpython-313.pyc,,
+mcp/server/__pycache__/request_state.cpython-313.pyc,,
+mcp/server/__pycache__/runner.cpython-313.pyc,,
+mcp/server/__pycache__/session.cpython-313.pyc,,
+mcp/server/__pycache__/sse.cpython-313.pyc,,
+mcp/server/__pycache__/stdio.cpython-313.pyc,,
+mcp/server/__pycache__/streamable_http.cpython-313.pyc,,
+mcp/server/__pycache__/streamable_http_manager.cpython-313.pyc,,
+mcp/server/__pycache__/subscriptions.cpython-313.pyc,,
+mcp/server/__pycache__/transport_security.cpython-313.pyc,,
+mcp/server/__pycache__/validation.cpython-313.pyc,,
+mcp/server/_otel.py,sha256=k71jSlD1U7uQjx0wWHkDW9W-wqUvddZIce5sNCrJjms,3359
+mcp/server/_streamable_http_modern.py,sha256=HAsp0ZmjYJoZBugVFtCeBTZdYNrYTRbSHWK-XVAQt6g,19411
+mcp/server/apps.py,sha256=srksMEEFBHjtyrZ2S9q7upQ1jhEiuj4fP9hm9gBPOso,9680
+mcp/server/auth/__init__.py,sha256=_JhI3YU6YP6401tYr0L_Fi6rJhUusJTye-xZd0_xCqQ,49
+mcp/server/auth/__pycache__/__init__.cpython-313.pyc,,
+mcp/server/auth/__pycache__/errors.cpython-313.pyc,,
+mcp/server/auth/__pycache__/json_response.cpython-313.pyc,,
+mcp/server/auth/__pycache__/provider.cpython-313.pyc,,
+mcp/server/auth/__pycache__/routes.cpython-313.pyc,,
+mcp/server/auth/__pycache__/settings.cpython-313.pyc,,
+mcp/server/auth/errors.py,sha256=8YjlejJPl-qMjZrbJTDzMPBOAOITn0Da0pC5QWn9QdE,224
+mcp/server/auth/handlers/__init__.py,sha256=KuVuAHZLupFuUBp46a48h3AV9Z6Qp7_IPlxegGiW-xs,56
+mcp/server/auth/handlers/__pycache__/__init__.cpython-313.pyc,,
+mcp/server/auth/handlers/__pycache__/authorize.cpython-313.pyc,,
+mcp/server/auth/handlers/__pycache__/metadata.cpython-313.pyc,,
+mcp/server/auth/handlers/__pycache__/register.cpython-313.pyc,,
+mcp/server/auth/handlers/__pycache__/revoke.cpython-313.pyc,,
+mcp/server/auth/handlers/__pycache__/token.cpython-313.pyc,,
+mcp/server/auth/handlers/authorize.py,sha256=qMcje0xGcZcgFWAV6qTG1w8hEGgaK-l90_igKOrLtvQ,9773
+mcp/server/auth/handlers/metadata.py,sha256=mWPkrs1DfG-Qzq1nZU2HzwxSwk8K_vXe-ZpEDZ0k_QA,853
+mcp/server/auth/handlers/register.py,sha256=f03h4UFVdYGRuUG13-7MpyO4dxbSCeXTa6tRVUE2ObQ,7179
+mcp/server/auth/handlers/revoke.py,sha256=6z9TW1-9oJ08GlRN3prMokzQVyPdLhLaQFC_ndQYCU4,3083
+mcp/server/auth/handlers/token.py,sha256=OCbUZW_joKh7r83gH1qwyxVSoX039jOfxX-VcFpA3Ng,12544
+mcp/server/auth/json_response.py,sha256=EMv3qAH62vRuw8XBHdFU3kYp0S8Jd6DjRGfwc7Jc9XU,377
+mcp/server/auth/middleware/__init__.py,sha256=hzEnzjSR61OBZBrDxL8Om3LLET20teK1HS-pqnqQEVw,40
+mcp/server/auth/middleware/__pycache__/__init__.cpython-313.pyc,,
+mcp/server/auth/middleware/__pycache__/auth_context.cpython-313.pyc,,
+mcp/server/auth/middleware/__pycache__/bearer_auth.cpython-313.pyc,,
+mcp/server/auth/middleware/__pycache__/client_auth.cpython-313.pyc,,
+mcp/server/auth/middleware/auth_context.py,sha256=HwdfSIwEKvTfWNn1jtLTQbAYTI5JT3fPbF5MZx_k2X0,1686
+mcp/server/auth/middleware/bearer_auth.py,sha256=fTts5E_9f5C1WYS_RqD1EEnOaDSG9VErGgRmvmmqauA,5172
+mcp/server/auth/middleware/client_auth.py,sha256=z_sJU8Pfn3wnwKNc24zjuvPNr4Z9UlT1U7w7vyh5JLw,5019
+mcp/server/auth/provider.py,sha256=zFxkeqHeU9KhdsauSf1SqkJ96Vjedh2rJwEZEOarWDs,14164
+mcp/server/auth/routes.py,sha256=3Scx7RSkgAN8zVs6VjgDRS494L4VcQyQDF4BbeOGB3Y,10049
+mcp/server/auth/settings.py,sha256=rEIZxhX0Kw69zZm42sxBfDg1vL_Dv1yn9O3ZzfFN7E0,1802
+mcp/server/caching.py,sha256=AYLvl9PXNgPmVnsnUwp8ujbCS7My1xYuXDLTb7LUz3k,3623
+mcp/server/connection.py,sha256=TfQplwP8FEPNb7UwHyQlZWckmEnHhvWAGgqFuUhvLaQ,21924
+mcp/server/context.py,sha256=eWx8i0eed4d7qQb1HdB8y24xV6WAl4kjj7X8f9v-2s4,8546
+mcp/server/elicitation.py,sha256=DTer9VWiXBIygYqIxRr45Nvw3dhK9kzoTA2D_U5Erw4,7015
+mcp/server/extension.py,sha256=xcT7Mqo4CzEUw2EKgJItuaThqxht6Ke4jAznyJ51U5Q,8028
+mcp/server/lowlevel/__init__.py,sha256=zUMGFpya9MVyLjNBoo7lkMGjPUDLcDsEMhbCfouxCTQ,93
+mcp/server/lowlevel/__pycache__/__init__.cpython-313.pyc,,
+mcp/server/lowlevel/__pycache__/helper_types.cpython-313.pyc,,
+mcp/server/lowlevel/__pycache__/server.cpython-313.pyc,,
+mcp/server/lowlevel/helper_types.py,sha256=LVC0N6JMPynVs4fMJSfBmqKIigHNLsRNhBvbU06rg6A,251
+mcp/server/lowlevel/server.py,sha256=U1q8fnWzhYZxKkAw3_tOhiFBSoKsAXYavJXrtRR6Nvk,35998
+mcp/server/mcpserver/__init__.py,sha256=qxvMcxd6rs4-ObyWAqKTiWpANnwTqPaCE7KFnqgDW-s,1340
+mcp/server/mcpserver/__pycache__/__init__.cpython-313.pyc,,
+mcp/server/mcpserver/__pycache__/context.cpython-313.pyc,,
+mcp/server/mcpserver/__pycache__/exceptions.cpython-313.pyc,,
+mcp/server/mcpserver/__pycache__/resolve.cpython-313.pyc,,
+mcp/server/mcpserver/__pycache__/server.cpython-313.pyc,,
+mcp/server/mcpserver/context.py,sha256=y0sV3lV49GfM2ttxSWzMf0PRlHsmhSDTcTZPznUPfkM,16418
+mcp/server/mcpserver/exceptions.py,sha256=F7v5JqEu3NIaHGHXoDa1l7OxanhlS-s1PdFV-4bMcjc,676
+mcp/server/mcpserver/prompts/__init__.py,sha256=4BsMxoYolpoxg74xkkkzCFL8vvdkLVJ5cIPNs1ND1Jo,99
+mcp/server/mcpserver/prompts/__pycache__/__init__.cpython-313.pyc,,
+mcp/server/mcpserver/prompts/__pycache__/base.cpython-313.pyc,,
+mcp/server/mcpserver/prompts/__pycache__/manager.cpython-313.pyc,,
+mcp/server/mcpserver/prompts/base.py,sha256=DaSnTV6K-8ctaGQpFk5XQwpKWJp3y32ceyfYfhOwUmk,7764
+mcp/server/mcpserver/prompts/manager.py,sha256=j3fAmQCAQdbEL98A7Io1uAqwk4PcdR9rp-_ALh-ADaE,2028
+mcp/server/mcpserver/resolve.py,sha256=5VTfUx7bIc2msbwv1eV4AMq3RbdZV6XVwHy-yL60Lcw,35408
+mcp/server/mcpserver/resources/__init__.py,sha256=FLGQHcOjvM-7ANl0To68SXUueovIGewXpzpUWpYzhKg,618
+mcp/server/mcpserver/resources/__pycache__/__init__.cpython-313.pyc,,
+mcp/server/mcpserver/resources/__pycache__/base.cpython-313.pyc,,
+mcp/server/mcpserver/resources/__pycache__/resource_manager.cpython-313.pyc,,
+mcp/server/mcpserver/resources/__pycache__/templates.cpython-313.pyc,,
+mcp/server/mcpserver/resources/__pycache__/types.cpython-313.pyc,,
+mcp/server/mcpserver/resources/base.py,sha256=YkEG24pEbbsYYBTwEGX4qXeBRkpQhSkc_o6YXtY1w-0,1660
+mcp/server/mcpserver/resources/resource_manager.py,sha256=MVuw2vciN9NLHlND_evojeD9cCabZxqArkIrTjx-T9U,5124
+mcp/server/mcpserver/resources/templates.py,sha256=gSOVALIQrjnJG2b1JUI36ihcDG2vFjwVijnZJ-23Jb8,10090
+mcp/server/mcpserver/resources/types.py,sha256=J7rrVY6fW8FkFXhdpsl-cKmdF67NOjOvWWKi4p1QcIc,9484
+mcp/server/mcpserver/server.py,sha256=zE_FLRTweCaXfJoqOGcZtzJQcYbAgWAZh91Y387gVKo,55896
+mcp/server/mcpserver/tools/__init__.py,sha256=ZboxhyMJDl87Svjov8YwNYwNZi55P9VhmpTjBZLesnk,96
+mcp/server/mcpserver/tools/__pycache__/__init__.cpython-313.pyc,,
+mcp/server/mcpserver/tools/__pycache__/base.cpython-313.pyc,,
+mcp/server/mcpserver/tools/__pycache__/tool_manager.cpython-313.pyc,,
+mcp/server/mcpserver/tools/base.py,sha256=-j7Ej17e8xOeCUZN4KmegCS_mS4CFEQ_PVqED7XLNmI,7852
+mcp/server/mcpserver/tools/tool_manager.py,sha256=peEBf_SpzOPJOtN51XjlccMYfJJQopV1DLLhhxeQODg,2805
+mcp/server/mcpserver/utilities/__init__.py,sha256=RU33vSfWMx0-WDN5Sowi2M9h4tchQmDizGTL9-kGPd8,33
+mcp/server/mcpserver/utilities/__pycache__/__init__.cpython-313.pyc,,
+mcp/server/mcpserver/utilities/__pycache__/context_injection.cpython-313.pyc,,
+mcp/server/mcpserver/utilities/__pycache__/func_metadata.cpython-313.pyc,,
+mcp/server/mcpserver/utilities/__pycache__/logging.cpython-313.pyc,,
+mcp/server/mcpserver/utilities/__pycache__/types.cpython-313.pyc,,
+mcp/server/mcpserver/utilities/context_injection.py,sha256=4pDn-HrSdxzQM4LUTa6gAV9xbBLA4KkkxzwRJo8ar60,2053
+mcp/server/mcpserver/utilities/func_metadata.py,sha256=B90oV26YO4VLg9RyjRgu1vkGTOJngcxtcOfjR5xMBuo,25118
+mcp/server/mcpserver/utilities/logging.py,sha256=pwvj0_Y9Eg9am3UtfEVQLUg1Lk07Iwqu_2pDK7Qtoh8,978
+mcp/server/mcpserver/utilities/types.py,sha256=irHdBNRsBkTDnpWmSpB5abkUQu4J-1rAuvDBQlrhLP8,3430
+mcp/server/models.py,sha256=mODTf-8u7fCzVahQh7PZZ2xvccOmZy4ZdRDrFSvB5M8,474
+mcp/server/request_state.py,sha256=DavmX50RO4XhfjjawctsVD2rbg2K3PRckxshLqTexCk,19798
+mcp/server/runner.py,sha256=vlXLQsvKJhwpl7tPVOKsiS-7XDWTVAnvlRrJ9ztSeyk,39549
+mcp/server/session.py,sha256=YTLKaChdDyog0Z8ONGsR-4ZvLPSFCgmw79RN-XRSByY,20478
+mcp/server/sse.py,sha256=pn7pLOyexuf_vAGYAdkK0ddtXBRZm3jMPWUI71clR-w,11815
+mcp/server/stdio.py,sha256=Kj5zruVwVqBd74HLrSEEWEN96XtNoMmZMyWxlja8qew,8137
+mcp/server/streamable_http.py,sha256=hexH1Ncnfns1AvIQaSS7pZaFVZHhss4pW4c9U_kzurs,49655
+mcp/server/streamable_http_manager.py,sha256=LVDs_rCFLUjF3o9cL2OQTGqMp4uHQ35h8F584f0QMdU,21934
+mcp/server/subscriptions.py,sha256=V7MIO8YUwaO7P0XRj2UCJuB2JorLHT9jdsnghYTLXZ0,11043
+mcp/server/transport_security.py,sha256=bEH7iVU_VN3ufFfzYmM2vJvENmuaP6KKFJm3-SiO9Us,4482
+mcp/server/validation.py,sha256=pTtwz1QK15UCZ3PSzFTGhSqiYyfQliLSQwua8kQxMUA,3665
+mcp/shared/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mcp/shared/__pycache__/__init__.cpython-313.pyc,,
+mcp/shared/__pycache__/_callable_inspection.cpython-313.pyc,,
+mcp/shared/__pycache__/_compat.cpython-313.pyc,,
+mcp/shared/__pycache__/_context_streams.cpython-313.pyc,,
+mcp/shared/__pycache__/_httpx_utils.cpython-313.pyc,,
+mcp/shared/__pycache__/_otel.cpython-313.pyc,,
+mcp/shared/__pycache__/_stream_protocols.cpython-313.pyc,,
+mcp/shared/__pycache__/auth.cpython-313.pyc,,
+mcp/shared/__pycache__/auth_utils.cpython-313.pyc,,
+mcp/shared/__pycache__/context.cpython-313.pyc,,
+mcp/shared/__pycache__/direct_dispatcher.cpython-313.pyc,,
+mcp/shared/__pycache__/dispatcher.cpython-313.pyc,,
+mcp/shared/__pycache__/exceptions.cpython-313.pyc,,
+mcp/shared/__pycache__/extension.cpython-313.pyc,,
+mcp/shared/__pycache__/inbound.cpython-313.pyc,,
+mcp/shared/__pycache__/jsonrpc_dispatcher.cpython-313.pyc,,
+mcp/shared/__pycache__/memory.cpython-313.pyc,,
+mcp/shared/__pycache__/message.cpython-313.pyc,,
+mcp/shared/__pycache__/metadata_utils.cpython-313.pyc,,
+mcp/shared/__pycache__/path_security.cpython-313.pyc,,
+mcp/shared/__pycache__/peer.cpython-313.pyc,,
+mcp/shared/__pycache__/subscriptions.cpython-313.pyc,,
+mcp/shared/__pycache__/tool_name_validation.cpython-313.pyc,,
+mcp/shared/__pycache__/transport_context.cpython-313.pyc,,
+mcp/shared/__pycache__/uri_template.cpython-313.pyc,,
+mcp/shared/_callable_inspection.py,sha256=8ODRH9Bls7m_lgPqS0comKAswWRLGHLbSXXO5qaAkpY,867
+mcp/shared/_compat.py,sha256=bzQH1crrW-VNX_qeAokeroLj4F3bqocRXRT9U271QSI,815
+mcp/shared/_context_streams.py,sha256=4OmFYdaxKgtDduD7DnIZXX9ZQcFdo-NqHYgfuVTiejA,3759
+mcp/shared/_httpx_utils.py,sha256=5rfKm1rC4s-qvhOvibqXOMyNYkyZGFlrrvpWm2zhR_Q,2977
+mcp/shared/_otel.py,sha256=1PMkVOc00FvlqxmTgCw_4hDvaqWlZFhtcoGfGU0VOSE,1748
+mcp/shared/_stream_protocols.py,sha256=8FqmXR9NN4rVrevHWnEZL0cHDe8H4ileZiJOWfJGFLc,1470
+mcp/shared/auth.py,sha256=iZr9-k82jonWZyFBQxtqMvg5-eOKfws6bmZUzaJSAOI,12116
+mcp/shared/auth_utils.py,sha256=aX1l1S3pDlE_9r0Fv25I76huJp1wqB25iUROb25xuuc,2881
+mcp/shared/context.py,sha256=r4ybUzYfkt9BzOUpzBwDYPZtJf0fTEOSUxZTSwFA_fQ,3096
+mcp/shared/direct_dispatcher.py,sha256=2FCGiL_t5Y-cK4hwc-CMGuKOqoolZHYK93VxeOiQ334,14610
+mcp/shared/dispatcher.py,sha256=k5woCHfD8oSM_Ovb2X4A3n3QfN5Lj6tw_ePU_4sOT4Y,10892
+mcp/shared/exceptions.py,sha256=P3hVB1g0LspGyMF89KhlnUpfPh4HSwMulA_Afg-LX64,4225
+mcp/shared/extension.py,sha256=8Xyv-GR0ZB16GTX7mnVqZj9VTl6nfFRAt2o1gE2X_8A,1168
+mcp/shared/inbound.py,sha256=s4zcr04IXywKYONspJdLjdZDvVVTIof4oiC-_LXwDEk,25369
+mcp/shared/jsonrpc_dispatcher.py,sha256=gq32ZILKNr3Dzoj7WOmfd4UUlJ1T6rOBgCTvmFF4BS0,38066
+mcp/shared/memory.py,sha256=U-L68iheegxdooC--mxIgEwXolllxVdSSJWWOp19qP4,1479
+mcp/shared/message.py,sha256=UoeMEjzal32I1RmELn0zAj5k7TRluXdHm-JW_iBtHCk,2356
+mcp/shared/metadata_utils.py,sha256=NOwz9Gf_PqVcNSg6RO0juzA0m3onKXnodsXuKTnxvdA,1737
+mcp/shared/path_security.py,sha256=TFAW2v-iWK0BKMsGEeLp9LYwHc70qAlsiIsRc0Q5SNw,6210
+mcp/shared/peer.py,sha256=F6L4dc66gzQKDnb9uIdMSRxfda796sbZKK9Ebqzh-as,9797
+mcp/shared/subscriptions.py,sha256=mMSwdFZUpmpCydHuKgwuHb_8VVpXzn4VKwqtvG5Ye5U,4049
+mcp/shared/tool_name_validation.py,sha256=2MQFDVgED5BMQyS0_L24as1Xf-kJNkbExeHiNnvptg8,4535
+mcp/shared/transport_context.py,sha256=W2Mg4wlLD2b97znWAcXs9yBnl0jwhmXCxeHTxfsCkxg,1867
+mcp/shared/uri_template.py,sha256=b3grvBhqaf4QHT1uodxEOg9aUNyOKOeAy3-F8HYXtEU,43857
+mcp/types/__init__.py,sha256=ovVpPdU3IhzC1uzF4qaVUTRHKjg_MHy3_hBy09AhFnY,1259
+mcp/types/__pycache__/__init__.cpython-313.pyc,,
+mcp/types/__pycache__/jsonrpc.cpython-313.pyc,,
+mcp/types/__pycache__/methods.cpython-313.pyc,,
+mcp/types/__pycache__/version.cpython-313.pyc,,
+mcp/types/jsonrpc.py,sha256=oClAyfV6VTSqu7x-xekGdT4CZxdeVUDOJ_noz10uIC0,589
+mcp/types/methods.py,sha256=TiilvvUqJzWhRH-ngzMyFEh1Fii8dJg-f_jIWn_gA1U,572
+mcp/types/version.py,sha256=ysQCr4rfyGeVXqZ-4KaCLbdrIwG1FPaVy6mBXOgbXUw,606

.mcp-venv/lib/python3.13/site-packages/mcp-2.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

.mcp-venv/lib/python3.13/site-packages/mcp-2.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mcp = mcp.cli:app [cli]

.mcp-venv/lib/python3.13/site-packages/mcp-2.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Anthropic, PBC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

.mcp-venv/lib/python3.13/site-packages/mcp/client/auth/extensions/client_credentials.py

@@ -0,0 +1,333 @@
+"""OAuth client credential extensions for MCP.
+
+Provides OAuth providers for machine-to-machine authentication flows:
+- ClientCredentialsOAuthProvider: For client_credentials with client_id + client_secret
+- PrivateKeyJWTOAuthProvider: For client_credentials with private_key_jwt authentication
+  (typically using a pre-built JWT from workload identity federation)
+"""
+
+import time
+from collections.abc import Awaitable, Callable
+from typing import Any, Literal
+from uuid import uuid4
+
+import httpx2
+import jwt
+from pydantic import BaseModel, Field
+
+from mcp.client.auth import OAuthClientProvider, OAuthFlowError, TokenStorage
+from mcp.shared.auth import OAuthClientInformationFull, OAuthClientMetadata
+
+
+class ClientCredentialsOAuthProvider(OAuthClientProvider):
+    """OAuth provider for client_credentials grant with client_id + client_secret.
+
+    This provider sets client_info directly, bypassing dynamic client registration.
+    Use this when you already have client credentials (client_id and client_secret).
+
+    Example:
+        ```python
+        provider = ClientCredentialsOAuthProvider(
+            server_url="https://api.example.com",
+            storage=my_token_storage,
+            client_id="my-client-id",
+            client_secret="my-client-secret",
+        )
+        ```
+    """
+
+    def __init__(
+        self,
+        server_url: str,
+        storage: TokenStorage,
+        client_id: str,
+        client_secret: str,
+        token_endpoint_auth_method: Literal["client_secret_basic", "client_secret_post"] = "client_secret_basic",
+        scope: str | None = None,
+    ) -> None:
+        """Initialize client_credentials OAuth provider.
+
+        Args:
+            server_url: The MCP server URL.
+            storage: Token storage implementation.
+            client_id: The OAuth client ID.
+            client_secret: The OAuth client secret.
+            token_endpoint_auth_method: Authentication method for token endpoint.
+                Either "client_secret_basic" (default) or "client_secret_post".
+            scope: Optional space-separated list of scopes to request.
+        """
+        # Build minimal client_metadata for the base class
+        client_metadata = OAuthClientMetadata(
+            redirect_uris=None,
+            grant_types=["client_credentials"],
+            token_endpoint_auth_method=token_endpoint_auth_method,
+            scope=scope,
+        )
+        super().__init__(server_url, client_metadata, storage, None, None)
+        # Store client_info to be set during _initialize - no dynamic registration needed
+        self._fixed_client_info = OAuthClientInformationFull(
+            redirect_uris=None,
+            client_id=client_id,
+            client_secret=client_secret,
+            grant_types=["client_credentials"],
+            token_endpoint_auth_method=token_endpoint_auth_method,
+            scope=scope,
+        )
+
+    async def _initialize(self) -> None:
+        """Load stored tokens and set pre-configured client_info."""
+        self.context.current_tokens = await self.context.storage.get_tokens()
+        self.context.client_info = self._fixed_client_info
+        self._initialized = True
+
+    async def _perform_authorization(self) -> httpx2.Request:
+        """Perform client_credentials authorization."""
+        return await self._exchange_token_client_credentials()
+
+    async def _exchange_token_client_credentials(self) -> httpx2.Request:
+        """Build token exchange request for client_credentials grant."""
+        token_data: dict[str, Any] = {
+            "grant_type": "client_credentials",
+        }
+
+        headers: dict[str, str] = {"Content-Type": "application/x-www-form-urlencoded"}
+
+        # Use standard auth methods (client_secret_basic, client_secret_post, none)
+        token_data, headers = self.context.prepare_token_auth(token_data, headers)
+
+        if self.context.should_include_resource_param(self.context.protocol_version):
+            token_data["resource"] = self.context.get_resource_url()
+
+        if self.context.client_metadata.scope:
+            token_data["scope"] = self.context.client_metadata.scope
+
+        token_url = self._get_token_endpoint()
+        return httpx2.Request("POST", token_url, data=token_data, headers=headers)
+
+
+def static_assertion_provider(token: str) -> Callable[[str], Awaitable[str]]:
+    """Create an assertion provider that returns a static JWT token.
+
+    Use this when you have a pre-built JWT (e.g., from workload identity federation)
+    that doesn't need the audience parameter.
+
+    Example:
+        ```python
+        provider = PrivateKeyJWTOAuthProvider(
+            server_url="https://api.example.com",
+            storage=my_token_storage,
+            client_id="my-client-id",
+            assertion_provider=static_assertion_provider(my_prebuilt_jwt),
+        )
+        ```
+
+    Args:
+        token: The pre-built JWT assertion string.
+
+    Returns:
+        An async callback suitable for use as an assertion_provider.
+    """
+
+    async def provider(audience: str) -> str:
+        return token
+
+    return provider
+
+
+class SignedJWTParameters(BaseModel):
+    """Parameters for creating SDK-signed JWT assertions.
+
+    Use `create_assertion_provider()` to create an assertion provider callback
+    for use with `PrivateKeyJWTOAuthProvider`.
+
+    Example:
+        ```python
+        jwt_params = SignedJWTParameters(
+            issuer="my-client-id",
+            subject="my-client-id",
+            signing_key=private_key_pem,
+        )
+        provider = PrivateKeyJWTOAuthProvider(
+            server_url="https://api.example.com",
+            storage=my_token_storage,
+            client_id="my-client-id",
+            assertion_provider=jwt_params.create_assertion_provider(),
+        )
+        ```
+    """
+
+    issuer: str = Field(description="Issuer for JWT assertions (typically client_id).")
+    subject: str = Field(description="Subject identifier for JWT assertions (typically client_id).")
+    signing_key: str = Field(description="Private key for JWT signing (PEM format).")
+    signing_algorithm: str = Field(default="RS256", description="Algorithm for signing JWT assertions.")
+    lifetime_seconds: int = Field(default=300, description="Lifetime of generated JWT in seconds.")
+    additional_claims: dict[str, Any] | None = Field(default=None, description="Additional claims.")
+
+    def create_assertion_provider(self) -> Callable[[str], Awaitable[str]]:
+        """Create an assertion provider callback for use with PrivateKeyJWTOAuthProvider.
+
+        Returns:
+            An async callback that takes the audience (authorization server issuer URL)
+            and returns a signed JWT assertion.
+        """
+
+        async def provider(audience: str) -> str:
+            now = int(time.time())
+            claims: dict[str, Any] = {
+                "iss": self.issuer,
+                "sub": self.subject,
+                "aud": audience,
+                "exp": now + self.lifetime_seconds,
+                "iat": now,
+                "jti": str(uuid4()),
+            }
+            if self.additional_claims:
+                claims.update(self.additional_claims)
+
+            return jwt.encode(claims, self.signing_key, algorithm=self.signing_algorithm)
+
+        return provider
+
+
+class PrivateKeyJWTOAuthProvider(OAuthClientProvider):
+    """OAuth provider for client_credentials grant with private_key_jwt authentication.
+
+    Uses RFC 7523 Section 2.2 for client authentication via JWT assertion.
+
+    The JWT assertion's audience MUST be the authorization server's issuer identifier
+    (per RFC 7523bis security updates). The `assertion_provider` callback receives
+    this audience value and must return a JWT with that audience.
+
+    **Option 1: Pre-built JWT via Workload Identity Federation**
+
+    In production scenarios, the JWT assertion is typically obtained from a workload
+    identity provider (e.g., GCP, AWS IAM, Azure AD):
+
+        ```python
+        async def get_workload_identity_token(audience: str) -> str:
+            # Fetch JWT from your identity provider
+            # The JWT's audience must match the provided audience parameter
+            return await fetch_token_from_identity_provider(audience=audience)
+
+        provider = PrivateKeyJWTOAuthProvider(
+            server_url="https://api.example.com",
+            storage=my_token_storage,
+            client_id="my-client-id",
+            assertion_provider=get_workload_identity_token,
+        )
+        ```
+
+    **Option 2: Static pre-built JWT**
+
+    If you have a static JWT that doesn't need the audience parameter:
+
+        ```python
+        provider = PrivateKeyJWTOAuthProvider(
+            server_url="https://api.example.com",
+            storage=my_token_storage,
+            client_id="my-client-id",
+            assertion_provider=static_assertion_provider(my_prebuilt_jwt),
+        )
+        ```
+
+    **Option 3: SDK-signed JWT (for testing/simple setups)**
+
+    For testing or simple deployments, use `SignedJWTParameters.create_assertion_provider()`:
+
+        ```python
+        jwt_params = SignedJWTParameters(
+            issuer="my-client-id",
+            subject="my-client-id",
+            signing_key=private_key_pem,
+        )
+        provider = PrivateKeyJWTOAuthProvider(
+            server_url="https://api.example.com",
+            storage=my_token_storage,
+            client_id="my-client-id",
+            assertion_provider=jwt_params.create_assertion_provider(),
+        )
+        ```
+    """
+
+    def __init__(
+        self,
+        server_url: str,
+        storage: TokenStorage,
+        client_id: str,
+        assertion_provider: Callable[[str], Awaitable[str]],
+        scope: str | None = None,
+    ) -> None:
+        """Initialize private_key_jwt OAuth provider.
+
+        Args:
+            server_url: The MCP server URL.
+            storage: Token storage implementation.
+            client_id: The OAuth client ID.
+            assertion_provider: Async callback that takes the audience (authorization
+                server's issuer identifier) and returns a JWT assertion. Use
+                `SignedJWTParameters.create_assertion_provider()` for SDK-signed JWTs,
+                `static_assertion_provider()` for pre-built JWTs, or provide your own
+                callback for workload identity federation.
+            scope: Optional space-separated list of scopes to request.
+        """
+        # Build minimal client_metadata for the base class
+        client_metadata = OAuthClientMetadata(
+            redirect_uris=None,
+            grant_types=["client_credentials"],
+            token_endpoint_auth_method="private_key_jwt",
+            scope=scope,
+        )
+        super().__init__(server_url, client_metadata, storage, None, None)
+        self._assertion_provider = assertion_provider
+        # Store client_info to be set during _initialize - no dynamic registration needed
+        self._fixed_client_info = OAuthClientInformationFull(
+            redirect_uris=None,
+            client_id=client_id,
+            grant_types=["client_credentials"],
+            token_endpoint_auth_method="private_key_jwt",
+            scope=scope,
+        )
+
+    async def _initialize(self) -> None:
+        """Load stored tokens and set pre-configured client_info."""
+        self.context.current_tokens = await self.context.storage.get_tokens()
+        self.context.client_info = self._fixed_client_info
+        self._initialized = True
+
+    async def _perform_authorization(self) -> httpx2.Request:
+        """Perform client_credentials authorization with private_key_jwt."""
+        return await self._exchange_token_client_credentials()
+
+    async def _add_client_authentication_jwt(self, *, token_data: dict[str, Any]) -> None:
+        """Add JWT assertion for client authentication to token endpoint parameters."""
+        if not self.context.oauth_metadata:
+            raise OAuthFlowError("Missing OAuth metadata for private_key_jwt flow")  # pragma: no cover
+
+        # Audience MUST be the issuer identifier of the authorization server
+        # https://datatracker.ietf.org/doc/html/draft-ietf-oauth-rfc7523bis-01
+        audience = str(self.context.oauth_metadata.issuer)
+        assertion = await self._assertion_provider(audience)
+
+        # RFC 7523 Section 2.2: client authentication via JWT
+        token_data["client_assertion"] = assertion
+        token_data["client_assertion_type"] = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
+
+    async def _exchange_token_client_credentials(self) -> httpx2.Request:
+        """Build token exchange request for client_credentials grant with private_key_jwt."""
+        token_data: dict[str, Any] = {
+            "grant_type": "client_credentials",
+        }
+
+        headers: dict[str, str] = {"Content-Type": "application/x-www-form-urlencoded"}
+
+        # Add JWT client authentication (RFC 7523 Section 2.2)
+        await self._add_client_authentication_jwt(token_data=token_data)
+
+        if self.context.should_include_resource_param(self.context.protocol_version):
+            token_data["resource"] = self.context.get_resource_url()
+
+        if self.context.client_metadata.scope:
+            token_data["scope"] = self.context.client_metadata.scope
+
+        token_url = self._get_token_endpoint()
+        return httpx2.Request("POST", token_url, data=token_data, headers=headers)

.mcp-venv/lib/python3.13/site-packages/mcp/client/auth/extensions/identity_assertion.py

@@ -0,0 +1,213 @@
+"""SEP-990 Identity Assertion Authorization Grant (RFC 7523 jwt-bearer) client provider.
+
+`IdentityAssertionOAuthProvider` is the client side of SEP-990 leg 2: it presents an Identity
+Assertion Authorization Grant (ID-JAG) - a signed JWT issued by the enterprise identity provider -
+to the MCP authorization server's token endpoint using the RFC 7523 jwt-bearer grant
+(`grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer`, ID-JAG as `assertion`), and receives an
+MCP access token.
+
+The authorization server is configuration, not discovery. SEP-990's trust model is the inverse of
+the default OAuth client's: the AS issuer is supplied at construction, authorization-server metadata
+is fetched from that issuer's own RFC 8414 well-known, and the resource server is never asked which
+AS to use - so it cannot redirect the ID-JAG or client secret elsewhere. There is no protected
+resource metadata fetch, no dynamic client registration, and no server-driven scope selection.
+
+Obtaining the ID-JAG (logging into the IdP and the leg-1 token exchange against it) is
+deployment-specific and out of scope for the SDK. The caller supplies it through the
+`assertion_provider` callback, which receives the configured issuer (the `aud` the ID-JAG must
+carry) and the MCP server's resource identifier (the `resource` claim it must carry, per ext-auth
+section 4.3), and returns the ID-JAG.
+"""
+
+import base64
+import time
+from collections.abc import AsyncGenerator, Awaitable, Callable
+from typing import Literal
+from urllib.parse import quote, urlsplit
+
+import anyio
+import httpx2
+
+from mcp.client.auth import OAuthFlowError, OAuthTokenError, TokenStorage
+from mcp.client.auth.utils import (
+    build_oauth_authorization_server_metadata_discovery_urls,
+    create_oauth_metadata_request,
+    extract_field_from_www_auth,
+    extract_scope_from_www_auth,
+    handle_auth_metadata_response,
+    handle_token_response_scopes,
+    union_scopes,
+    validate_metadata_issuer,
+)
+from mcp.shared.auth import JWT_BEARER_GRANT_TYPE, OAuthClientInformationFull, OAuthToken
+from mcp.shared.auth_utils import calculate_token_expiry, resource_url_from_server_url
+
+_DEFAULT_PORTS = {"https": 443, "http": 80}
+
+
+def _origin(url: str) -> tuple[str, str, int | None]:
+    """Return the (scheme, host, port) origin of a URL for same-origin comparison.
+
+    The port is normalized to the scheme's default so an explicit `:443`/`:80` compares equal to the
+    same origin written without a port.
+    """
+    parsed = urlsplit(url)
+    port = parsed.port if parsed.port is not None else _DEFAULT_PORTS.get(parsed.scheme)
+    return (parsed.scheme, parsed.hostname or "", port)
+
+
+class IdentityAssertionOAuthProvider(httpx2.Auth):
+    """`httpx2.Auth` for the SEP-990 ID-JAG flow (RFC 7523 jwt-bearer grant) against a configured AS.
+
+    The authorization server `issuer` is fixed at construction; metadata is fetched from its
+    RFC 8414 well-known and the ID-JAG and client secret are sent only to that issuer's token
+    endpoint. The resource server is never consulted for AS selection. The ID-JAG is fetched lazily
+    from `assertion_provider` so a fresh assertion is used on each exchange.
+
+    Example:
+        ```python
+        async def fetch_id_jag(audience: str, resource: str) -> str:
+            # `audience` is the configured issuer (the ID-JAG `aud`); `resource` is the MCP
+            # server's identifier (the ID-JAG `resource` claim). Obtaining the ID-JAG from the
+            # enterprise IdP is deployment-specific and not handled by the SDK.
+            return await my_idp.issue_id_jag(audience=audience, resource=resource)
+
+
+        provider = IdentityAssertionOAuthProvider(
+            server_url="https://mcp.example.com/mcp",
+            storage=my_token_storage,
+            client_id="my-client-id",
+            client_secret="my-client-secret",
+            issuer="https://auth.example.com",
+            assertion_provider=fetch_id_jag,
+        )
+        ```
+    """
+
+    requires_response_body = True
+
+    def __init__(
+        self,
+        server_url: str,
+        storage: TokenStorage,
+        client_id: str,
+        client_secret: str,
+        issuer: str,
+        assertion_provider: Callable[[str, str], Awaitable[str]],
+        scope: str | None = None,
+        token_endpoint_auth_method: Literal["client_secret_basic", "client_secret_post"] = "client_secret_post",
+    ) -> None:
+        """Initialize the identity-assertion OAuth provider.
+
+        Args:
+            server_url: The MCP server URL.
+            storage: Token storage implementation.
+            client_id: The OAuth client ID registered with the MCP authorization server.
+            client_secret: The client secret. SEP-990 section 5.1 requires a confidential client.
+            issuer: The issuer identifier of the MCP authorization server this client is provisioned
+                for. Authorization-server metadata is fetched from this issuer's well-known and the
+                ID-JAG and secret are sent only to its token endpoint.
+            assertion_provider: Async callback taking `(audience, resource)` - the configured issuer
+                and the MCP server's resource identifier - and returning the ID-JAG.
+            scope: Optional space-separated list of scopes to request.
+            token_endpoint_auth_method: Confidential-client auth method, either `client_secret_post`
+                (default) or `client_secret_basic`.
+        """
+        if not client_secret:
+            raise ValueError("client_secret is required: SEP-990 mandates a confidential client")
+        if not issuer:
+            raise ValueError("issuer is required: the authorization server is configuration, not discovery")
+        self._resource = resource_url_from_server_url(server_url)
+        self._storage = storage
+        self._issuer = issuer
+        self._assertion_provider = assertion_provider
+        self._scope = scope
+        self._client = OAuthClientInformationFull(
+            client_id=client_id,
+            client_secret=client_secret,
+            redirect_uris=None,
+            grant_types=[JWT_BEARER_GRANT_TYPE],
+            token_endpoint_auth_method=token_endpoint_auth_method,
+            issuer=issuer,
+        )
+        self._token_endpoint: str | None = None
+        self._tokens: OAuthToken | None = None
+        self._expiry: float | None = None
+        self._lock = anyio.Lock()
+        self._initialized = False
+
+    def _build_token_request(self, scope: str | None, assertion: str) -> httpx2.Request:
+        """Build the RFC 7523 jwt-bearer token request, applying confidential-client auth."""
+        assert self._token_endpoint is not None
+        assert self._client.client_id is not None and self._client.client_secret is not None
+        data: dict[str, str] = {
+            "grant_type": JWT_BEARER_GRANT_TYPE,
+            "assertion": assertion,
+            "client_id": self._client.client_id,
+            "resource": self._resource,
+        }
+        if scope:
+            data["scope"] = scope
+        headers = {"Content-Type": "application/x-www-form-urlencoded"}
+        if self._client.token_endpoint_auth_method == "client_secret_basic":
+            # RFC 6749 section 2.3.1: URL-encode each part, then base64 the colon-joined pair.
+            encoded_id = quote(self._client.client_id, safe="")
+            encoded_secret = quote(self._client.client_secret, safe="")
+            credentials = base64.b64encode(f"{encoded_id}:{encoded_secret}".encode()).decode()
+            headers["Authorization"] = f"Basic {credentials}"
+        else:
+            data["client_secret"] = self._client.client_secret
+        return httpx2.Request("POST", self._token_endpoint, data=data, headers=headers)
+
+    async def async_auth_flow(self, request: httpx2.Request) -> AsyncGenerator[httpx2.Request, httpx2.Response]:
+        async with self._lock:
+            if not self._initialized:
+                self._tokens = await self._storage.get_tokens()
+                self._expiry = calculate_token_expiry(self._tokens.expires_in) if self._tokens else None
+                self._initialized = True
+
+            if self._tokens and (self._expiry is None or time.time() <= self._expiry):
+                request.headers["Authorization"] = f"Bearer {self._tokens.access_token}"
+            response = yield request
+
+            if response.status_code == 401:
+                scope_to_request = self._scope
+            elif response.status_code == 403 and extract_field_from_www_auth(response, "error") == "insufficient_scope":
+                scope_to_request = union_scopes(self._scope, extract_scope_from_www_auth(response))
+            else:
+                return
+
+            # Discover ASM from the configured issuer's well-known. The RS is not consulted: both
+            # arguments are the issuer, so even the helper's legacy fallback resolves there.
+            if self._token_endpoint is None:
+                for url in build_oauth_authorization_server_metadata_discovery_urls(self._issuer, self._issuer):
+                    asm_response = yield create_oauth_metadata_request(url)
+                    ok, asm = await handle_auth_metadata_response(asm_response)
+                    if not ok:
+                        break
+                    if asm is not None:
+                        validate_metadata_issuer(asm, self._issuer)
+                        token_endpoint = str(asm.token_endpoint)
+                        if _origin(token_endpoint) != _origin(self._issuer):
+                            raise OAuthFlowError(
+                                f"Token endpoint {token_endpoint} is not on the configured issuer origin {self._issuer}"
+                            )
+                        self._token_endpoint = token_endpoint
+                        break
+                if self._token_endpoint is None:
+                    raise OAuthFlowError(f"No authorization server metadata at configured issuer {self._issuer}")
+
+            assertion = await self._assertion_provider(self._issuer, self._resource)
+            token_response = yield self._build_token_request(scope_to_request, assertion)
+            if token_response.status_code != 200:
+                body = (await token_response.aread()).decode(errors="replace")
+                raise OAuthTokenError(f"Token exchange failed ({token_response.status_code}): {body}")
+            tokens = await handle_token_response_scopes(token_response)
+            if tokens.scope is None:
+                tokens.scope = scope_to_request
+            self._tokens = tokens
+            self._expiry = calculate_token_expiry(tokens.expires_in)
+            await self._storage.set_tokens(tokens)
+
+            request.headers["Authorization"] = f"Bearer {tokens.access_token}"
+            yield request

.mcp-venv/lib/python3.13/site-packages/mcp/client/auth/oauth2.py

@@ -0,0 +1,785 @@
+"""OAuth2 Authentication implementation for httpx2.
+
+Implements authorization code flow with PKCE and automatic token refresh.
+"""
+
+import base64
+import hashlib
+import logging
+import secrets
+import string
+import time
+from collections.abc import AsyncGenerator, Awaitable, Callable
+from dataclasses import dataclass, field
+from typing import Any, Protocol, get_args
+from urllib.parse import quote, urlencode, urljoin, urlparse
+
+import anyio
+import httpx2
+from mcp_types.version import is_version_at_least
+from pydantic import BaseModel, Field, ValidationError
+
+from mcp.client.auth.exceptions import OAuthFlowError, OAuthRegistrationError, OAuthTokenError
+from mcp.client.auth.utils import (
+    build_oauth_authorization_server_metadata_discovery_urls,
+    build_protected_resource_metadata_discovery_urls,
+    create_client_info_from_metadata_url,
+    create_client_registration_request,
+    create_oauth_metadata_request,
+    credentials_match_issuer,
+    extract_field_from_www_auth,
+    extract_resource_metadata_from_www_auth,
+    extract_scope_from_www_auth,
+    get_client_metadata_scopes,
+    handle_auth_metadata_response,
+    handle_protected_resource_response,
+    handle_registration_response,
+    handle_token_response_scopes,
+    is_valid_client_metadata_url,
+    should_use_client_metadata_url,
+    union_scopes,
+    validate_authorization_response_iss,
+    validate_metadata_issuer,
+)
+from mcp.shared.auth import (
+    AuthorizationCodeResult,
+    OAuthClientInformationFull,
+    OAuthClientMetadata,
+    OAuthMetadata,
+    OAuthToken,
+    ProtectedResourceMetadata,
+    TokenEndpointAuthMethod,
+)
+from mcp.shared.auth_utils import (
+    calculate_token_expiry,
+    check_resource_allowed,
+    resource_url_from_server_url,
+)
+from mcp.shared.inbound import MCP_PROTOCOL_VERSION_HEADER
+
+logger = logging.getLogger(__name__)
+
+# Methods a registered client's record may carry without a token request being an error,
+# derived from the set the SDK is willing to request so the two cannot drift. `None`/"none"
+# send no client secret. `private_key_jwt` sends none from here either: only
+# `PrivateKeyJWTOAuthProvider` signs the assertion, and only in its client-credentials
+# exchange, so its inherited refresh path must pass through here without raising - a refresh
+# the server then rejects falls back to a fresh client-credentials exchange, which signs.
+# Anything else is a method no client here can apply.
+_KNOWN_TOKEN_ENDPOINT_AUTH_METHODS: tuple[str | None, ...] = (None, *get_args(TokenEndpointAuthMethod))
+
+# Methods that authenticate the token request with the minted `client_secret`; a
+# registration assigning one is only usable if the server issued that secret.
+_SECRET_TOKEN_ENDPOINT_AUTH_METHODS = ("client_secret_post", "client_secret_basic")
+
+# Methods a registration completed by the authorization-code flow can act on. That flow
+# authenticates the token request with the minted client secret (or nothing); it holds no key
+# to sign a `private_key_jwt` assertion, so a server assigning that method has registered a
+# client this flow cannot use. `PrivateKeyJWTOAuthProvider` never registers dynamically.
+_REGISTRATION_USABLE_TOKEN_ENDPOINT_AUTH_METHODS: tuple[str | None, ...] = tuple(
+    method for method in _KNOWN_TOKEN_ENDPOINT_AUTH_METHODS if method != "private_key_jwt"
+)
+
+
+def check_registration_usable(client_info: OAuthClientInformationFull) -> None:
+    """Confirm a registration this flow completed is one it can act on.
+
+    RFC 7591 §3.2.1 lets the authorization server replace requested metadata and leaves it to
+    the client to "check the values in the response to determine if the registration is
+    sufficient for use". Two substitutions make the minted credentials unusable, and both are
+    judged here - before the record is persisted or any interactive authorization begins -
+    rather than surfacing later as an opaque failure at the token endpoint: a token-endpoint
+    auth method the authorization-code flow cannot apply (one it does not implement, or
+    `private_key_jwt`, whose assertion this flow has no key to sign), and a secret-based
+    method the flow could apply but for which the server issued no `client_secret`.
+
+    Raises:
+        OAuthRegistrationError: The server registered the client with a
+            `token_endpoint_auth_method` this flow cannot apply, or with a secret-based
+            method but no `client_secret`.
+    """
+    method = client_info.token_endpoint_auth_method
+    if method not in _REGISTRATION_USABLE_TOKEN_ENDPOINT_AUTH_METHODS:
+        raise OAuthRegistrationError(
+            f"Authorization server registered the client with unsupported token_endpoint_auth_method {method!r}"
+        )
+    if method in _SECRET_TOKEN_ENDPOINT_AUTH_METHODS and client_info.client_secret is None:
+        raise OAuthRegistrationError(
+            f"Authorization server registered the client for {method!r} but issued no client_secret"
+        )
+
+
+class PKCEParameters(BaseModel):
+    """PKCE (Proof Key for Code Exchange) parameters."""
+
+    code_verifier: str = Field(..., min_length=43, max_length=128)
+    code_challenge: str = Field(..., min_length=43, max_length=128)
+
+    @classmethod
+    def generate(cls) -> "PKCEParameters":
+        """Generate new PKCE parameters."""
+        code_verifier = "".join(secrets.choice(string.ascii_letters + string.digits + "-._~") for _ in range(128))
+        digest = hashlib.sha256(code_verifier.encode()).digest()
+        code_challenge = base64.urlsafe_b64encode(digest).decode().rstrip("=")
+        return cls(code_verifier=code_verifier, code_challenge=code_challenge)
+
+
+class TokenStorage(Protocol):
+    """Protocol for token storage implementations."""
+
+    async def get_tokens(self) -> OAuthToken | None:
+        """Get stored tokens."""
+        ...
+
+    async def set_tokens(self, tokens: OAuthToken) -> None:
+        """Store tokens."""
+        ...
+
+    async def get_client_info(self) -> OAuthClientInformationFull | None:
+        """Get stored client information."""
+        ...
+
+    async def set_client_info(self, client_info: OAuthClientInformationFull) -> None:
+        """Store client information."""
+        ...
+
+
+@dataclass
+class OAuthContext:
+    """OAuth flow context."""
+
+    server_url: str
+    client_metadata: OAuthClientMetadata
+    storage: TokenStorage
+    redirect_handler: Callable[[str], Awaitable[None]] | None
+    callback_handler: Callable[[], Awaitable[AuthorizationCodeResult]] | None
+    client_metadata_url: str | None = None
+
+    # Discovered metadata
+    protected_resource_metadata: ProtectedResourceMetadata | None = None
+    oauth_metadata: OAuthMetadata | None = None
+    auth_server_url: str | None = None
+    protocol_version: str | None = None
+
+    # Client registration
+    client_info: OAuthClientInformationFull | None = None
+
+    # Token management
+    current_tokens: OAuthToken | None = None
+    token_expiry_time: float | None = None
+
+    # State
+    lock: anyio.Lock = field(default_factory=anyio.Lock)
+
+    def get_authorization_base_url(self, server_url: str) -> str:
+        """Extract base URL by removing path component."""
+        parsed = urlparse(server_url)
+        return f"{parsed.scheme}://{parsed.netloc}"
+
+    def update_token_expiry(self, token: OAuthToken) -> None:
+        """Update token expiry time using shared util function."""
+        self.token_expiry_time = calculate_token_expiry(token.expires_in)
+
+    def is_token_valid(self) -> bool:
+        """Check if current token is valid."""
+        return bool(
+            self.current_tokens
+            and self.current_tokens.access_token
+            and (not self.token_expiry_time or time.time() <= self.token_expiry_time)
+        )
+
+    def can_refresh_token(self) -> bool:
+        """Check if token can be refreshed."""
+        return bool(self.current_tokens and self.current_tokens.refresh_token and self.client_info)
+
+    def clear_tokens(self) -> None:
+        """Clear current tokens."""
+        self.current_tokens = None
+        self.token_expiry_time = None
+
+    def get_resource_url(self) -> str:
+        """Get resource URL for RFC 8707.
+
+        Uses PRM resource if it's a valid parent, otherwise uses canonical server URL.
+        """
+        resource = resource_url_from_server_url(self.server_url)
+
+        # If PRM provides a resource that's a valid parent, use it
+        if self.protected_resource_metadata and self.protected_resource_metadata.resource:
+            prm_resource = str(self.protected_resource_metadata.resource)
+            if check_resource_allowed(requested_resource=resource, configured_resource=prm_resource):
+                resource = prm_resource
+
+        return resource
+
+    def should_include_resource_param(self, protocol_version: str | None = None) -> bool:
+        """Determine if the resource parameter should be included in OAuth requests.
+
+        Returns True if:
+        - Protected resource metadata is available, OR
+        - MCP-Protocol-Version header is 2025-06-18 or later
+        """
+        # If we have protected resource metadata, include the resource param
+        if self.protected_resource_metadata is not None:
+            return True
+
+        # If no protocol version provided, don't include resource param
+        if not protocol_version:
+            return False
+
+        return is_version_at_least(protocol_version, "2025-06-18")
+
+    def prepare_token_auth(
+        self, data: dict[str, str], headers: dict[str, str] | None = None
+    ) -> tuple[dict[str, str], dict[str, str]]:
+        """Prepare authentication for token requests.
+
+        Args:
+            data: The form data to send
+            headers: Optional headers dict to update
+
+        Returns:
+            Tuple of (updated_data, updated_headers)
+
+        Raises:
+            OAuthTokenError: The client record carries a `token_endpoint_auth_method` this
+                client does not know. A dynamic registration assigning an unusable method is
+                rejected earlier, by `check_registration_usable`; this fires for a stored or
+                pre-registered record that reaches a token request with such a method.
+        """
+        if headers is None:
+            headers = {}  # pragma: no cover
+
+        if not self.client_info:
+            return data, headers
+
+        auth_method = self.client_info.token_endpoint_auth_method
+
+        if auth_method == "client_secret_basic" and self.client_info.client_secret:
+            # URL-encode client ID and secret per RFC 6749 Section 2.3.1
+            encoded_id = quote(self.client_info.client_id, safe="")
+            encoded_secret = quote(self.client_info.client_secret, safe="")
+            credentials = f"{encoded_id}:{encoded_secret}"
+            encoded_credentials = base64.b64encode(credentials.encode()).decode()
+            headers["Authorization"] = f"Basic {encoded_credentials}"
+            # Don't include client_secret in body for basic auth
+            data = {k: v for k, v in data.items() if k != "client_secret"}
+        elif auth_method == "client_secret_post" and self.client_info.client_secret:
+            # Include client_id and client_secret in request body (RFC 6749 §2.3.1)
+            data["client_id"] = self.client_info.client_id
+            data["client_secret"] = self.client_info.client_secret
+        elif auth_method not in _KNOWN_TOKEN_ENDPOINT_AUTH_METHODS:
+            raise OAuthTokenError(f"Registered client uses unsupported token_endpoint_auth_method {auth_method!r}")
+        # For "none" (or absent), don't add any client_secret; "private_key_jwt" adds its
+        # assertion in the provider that implements it, not here.
+
+        return data, headers
+
+
+class OAuthClientProvider(httpx2.Auth):
+    """OAuth2 authentication for httpx2.
+
+    Handles OAuth flow with automatic client registration and token storage.
+    """
+
+    requires_response_body = True
+
+    def __init__(
+        self,
+        server_url: str,
+        client_metadata: OAuthClientMetadata,
+        storage: TokenStorage,
+        redirect_handler: Callable[[str], Awaitable[None]] | None = None,
+        callback_handler: Callable[[], Awaitable[AuthorizationCodeResult]] | None = None,
+        client_metadata_url: str | None = None,
+        validate_resource_url: Callable[[str, str | None], Awaitable[None]] | None = None,
+    ):
+        """Initialize OAuth2 authentication.
+
+        Args:
+            server_url: The MCP server URL.
+            client_metadata: OAuth client metadata for registration.
+            storage: Token storage implementation.
+            redirect_handler: Handler for authorization redirects.
+            callback_handler: Handler for authorization callbacks.
+            client_metadata_url: URL-based client ID. When provided and the server
+                advertises client_id_metadata_document_supported=True, this URL will be
+                used as the client_id instead of performing dynamic client registration.
+                Must be a valid HTTPS URL with a non-root pathname.
+            validate_resource_url: Optional callback to override resource URL validation.
+                Called with (server_url, prm_resource) where prm_resource is the resource
+                from Protected Resource Metadata (or None if not present). If not provided,
+                default validation rejects mismatched resources per RFC 8707.
+
+        Raises:
+            ValueError: If client_metadata_url is provided but not a valid HTTPS URL
+                with a non-root pathname.
+        """
+        # Validate client_metadata_url if provided
+        if client_metadata_url is not None and not is_valid_client_metadata_url(client_metadata_url):
+            raise ValueError(
+                f"client_metadata_url must be a valid HTTPS URL with a non-root pathname, got: {client_metadata_url}"
+            )
+
+        self.context = OAuthContext(
+            server_url=server_url,
+            client_metadata=client_metadata,
+            storage=storage,
+            redirect_handler=redirect_handler,
+            callback_handler=callback_handler,
+            client_metadata_url=client_metadata_url,
+        )
+        self._validate_resource_url_callback = validate_resource_url
+        self._initialized = False
+
+    async def _handle_protected_resource_response(self, response: httpx2.Response) -> bool:
+        """Handle protected resource metadata discovery response.
+
+        Per SEP-985, supports fallback when discovery fails at one URL.
+
+        Returns:
+            True if metadata was successfully discovered, False if we should try next URL
+        """
+        if response.status_code == 200:
+            try:
+                content = await response.aread()
+                metadata = ProtectedResourceMetadata.model_validate_json(content)
+                self.context.protected_resource_metadata = metadata
+                if metadata.authorization_servers:  # pragma: no branch
+                    self.context.auth_server_url = str(metadata.authorization_servers[0])
+                return True
+
+            except ValidationError:  # pragma: no cover
+                # Invalid metadata - try next URL
+                logger.warning(f"Invalid protected resource metadata at {response.request.url}")
+                return False
+        elif response.status_code == 404:  # pragma: no cover
+            # Not found - try next URL in fallback chain
+            logger.debug(f"Protected resource metadata not found at {response.request.url}, trying next URL")
+            return False
+        else:
+            # Other error - fail immediately
+            raise OAuthFlowError(
+                f"Protected Resource Metadata request failed: {response.status_code}"
+            )  # pragma: no cover
+
+    async def _perform_authorization(self) -> httpx2.Request:
+        """Perform the authorization flow."""
+        auth_code, code_verifier = await self._perform_authorization_code_grant()
+        token_request = await self._exchange_token_authorization_code(auth_code, code_verifier)
+        return token_request
+
+    async def _perform_authorization_code_grant(self) -> tuple[str, str]:
+        """Perform the authorization redirect and get auth code."""
+        if self.context.client_metadata.redirect_uris is None:
+            raise OAuthFlowError("No redirect URIs provided for authorization code grant")  # pragma: no cover
+        if not self.context.redirect_handler:
+            raise OAuthFlowError("No redirect handler provided for authorization code grant")  # pragma: no cover
+        if not self.context.callback_handler:
+            raise OAuthFlowError("No callback handler provided for authorization code grant")  # pragma: no cover
+
+        if self.context.oauth_metadata and self.context.oauth_metadata.authorization_endpoint:
+            auth_endpoint = str(self.context.oauth_metadata.authorization_endpoint)
+        else:
+            auth_base_url = self.context.get_authorization_base_url(self.context.server_url)
+            auth_endpoint = urljoin(auth_base_url, "/authorize")
+
+        if not self.context.client_info:
+            raise OAuthFlowError("No client info available for authorization")  # pragma: no cover
+
+        # Generate PKCE parameters
+        pkce_params = PKCEParameters.generate()
+        state = secrets.token_urlsafe(32)
+
+        auth_params = {
+            "response_type": "code",
+            "client_id": self.context.client_info.client_id,
+            "redirect_uri": str(self.context.client_metadata.redirect_uris[0]),
+            "state": state,
+            "code_challenge": pkce_params.code_challenge,
+            "code_challenge_method": "S256",
+        }
+
+        # Only include resource param if conditions are met
+        if self.context.should_include_resource_param(self.context.protocol_version):
+            auth_params["resource"] = self.context.get_resource_url()  # RFC 8707
+
+        if self.context.client_metadata.scope:  # pragma: no branch
+            auth_params["scope"] = self.context.client_metadata.scope
+
+            # OIDC requires prompt=consent when offline_access is requested
+            # https://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess
+            if "offline_access" in self.context.client_metadata.scope.split():
+                auth_params["prompt"] = "consent"
+
+        authorization_url = f"{auth_endpoint}?{urlencode(auth_params)}"
+        await self.context.redirect_handler(authorization_url)
+
+        # Wait for callback
+        result = await self.context.callback_handler()
+
+        if result.state is None or not secrets.compare_digest(result.state, state):
+            raise OAuthFlowError(f"State parameter mismatch: {result.state} != {state}")
+
+        # RFC 9207: validate the authorization-response issuer
+        validate_authorization_response_iss(result.iss, self.context.oauth_metadata)
+
+        if not result.code:
+            raise OAuthFlowError("No authorization code received")
+
+        # Return auth code and code verifier for token exchange
+        return result.code, pkce_params.code_verifier
+
+    def _get_token_endpoint(self) -> str:
+        if self.context.oauth_metadata and self.context.oauth_metadata.token_endpoint:
+            token_url = str(self.context.oauth_metadata.token_endpoint)
+        else:
+            auth_base_url = self.context.get_authorization_base_url(self.context.server_url)
+            token_url = urljoin(auth_base_url, "/token")
+        return token_url
+
+    async def _exchange_token_authorization_code(self, auth_code: str, code_verifier: str) -> httpx2.Request:
+        """Build token exchange request for authorization_code flow."""
+        if self.context.client_metadata.redirect_uris is None:
+            raise OAuthFlowError("No redirect URIs provided for authorization code grant")  # pragma: no cover
+        if not self.context.client_info:
+            raise OAuthFlowError("Missing client info")  # pragma: no cover
+
+        token_url = self._get_token_endpoint()
+        token_data: dict[str, Any] = {
+            "grant_type": "authorization_code",
+            "code": auth_code,
+            "redirect_uri": str(self.context.client_metadata.redirect_uris[0]),
+            "client_id": self.context.client_info.client_id,
+            "code_verifier": code_verifier,
+        }
+
+        # Only include resource param if conditions are met
+        if self.context.should_include_resource_param(self.context.protocol_version):
+            token_data["resource"] = self.context.get_resource_url()  # RFC 8707
+
+        # Prepare authentication based on preferred method
+        headers = {"Content-Type": "application/x-www-form-urlencoded"}
+        token_data, headers = self.context.prepare_token_auth(token_data, headers)
+
+        return httpx2.Request("POST", token_url, data=token_data, headers=headers)
+
+    async def _handle_token_response(self, response: httpx2.Response) -> None:
+        """Handle token exchange response."""
+        if response.status_code not in {200, 201}:
+            body = await response.aread()
+            body_text = body.decode("utf-8")
+            raise OAuthTokenError(f"Token exchange failed ({response.status_code}): {body_text}")
+
+        # Parse and validate response with scope validation
+        token_response = await handle_token_response_scopes(response)
+
+        # RFC 6749 §5.1: an omitted scope means the granted scope equals the requested
+        # scope. Record it explicitly so the persisted token is self-describing — the
+        # SEP-2350 step-up union reads it after a restart, when client_metadata.scope
+        # has reverted to its constructor value.
+        if token_response.scope is None:
+            token_response.scope = self.context.client_metadata.scope
+
+        # Store tokens in context
+        self.context.current_tokens = token_response
+        self.context.update_token_expiry(token_response)
+        await self.context.storage.set_tokens(token_response)
+
+    async def _refresh_token(self) -> httpx2.Request:
+        """Build token refresh request."""
+        if not self.context.current_tokens or not self.context.current_tokens.refresh_token:
+            raise OAuthTokenError("No refresh token available")  # pragma: no cover
+
+        if not self.context.client_info or not self.context.client_info.client_id:
+            raise OAuthTokenError("No client info available")  # pragma: no cover
+
+        if self.context.oauth_metadata and self.context.oauth_metadata.token_endpoint:
+            token_url = str(self.context.oauth_metadata.token_endpoint)
+        else:
+            auth_base_url = self.context.get_authorization_base_url(self.context.server_url)
+            token_url = urljoin(auth_base_url, "/token")
+
+        refresh_data: dict[str, str] = {
+            "grant_type": "refresh_token",
+            "refresh_token": self.context.current_tokens.refresh_token,
+            "client_id": self.context.client_info.client_id,
+        }
+
+        # Only include resource param if conditions are met
+        if self.context.should_include_resource_param(self.context.protocol_version):
+            refresh_data["resource"] = self.context.get_resource_url()  # RFC 8707
+
+        # Prepare authentication based on preferred method
+        headers = {"Content-Type": "application/x-www-form-urlencoded"}
+        refresh_data, headers = self.context.prepare_token_auth(refresh_data, headers)
+
+        return httpx2.Request("POST", token_url, data=refresh_data, headers=headers)
+
+    async def _handle_refresh_response(self, response: httpx2.Response) -> bool:
+        """Handle token refresh response. Returns True if successful."""
+        if response.status_code != 200:
+            logger.warning(f"Token refresh failed: {response.status_code}")
+            self.context.clear_tokens()
+            return False
+
+        try:
+            content = await response.aread()
+            token_response = OAuthToken.model_validate_json(content)
+
+            # RFC 6749 §6: a refresh response may omit scope (unchanged) and refresh_token
+            # (the AS does not rotate). Carry both forward so the persisted token stays
+            # self-describing for the SEP-2350 step-up union and the next expiry can
+            # still refresh instead of forcing a full re-authorization.
+            prior = self.context.current_tokens
+            if token_response.scope is None and prior is not None:
+                token_response.scope = prior.scope
+            if token_response.refresh_token is None and prior is not None:
+                token_response.refresh_token = prior.refresh_token
+
+            self.context.current_tokens = token_response
+            self.context.update_token_expiry(token_response)
+            await self.context.storage.set_tokens(token_response)
+
+            return True
+        except ValidationError:  # pragma: no cover
+            logger.exception("Invalid refresh response")
+            self.context.clear_tokens()
+            return False
+
+    async def _initialize(self) -> None:
+        """Load stored tokens and client info."""
+        self.context.current_tokens = await self.context.storage.get_tokens()
+        self.context.client_info = await self.context.storage.get_client_info()
+        self._initialized = True
+
+    def _add_auth_header(self, request: httpx2.Request) -> None:
+        """Add authorization header to request if we have valid tokens."""
+        if self.context.current_tokens and self.context.current_tokens.access_token:  # pragma: no branch
+            request.headers["Authorization"] = f"Bearer {self.context.current_tokens.access_token}"
+
+    async def _handle_oauth_metadata_response(self, response: httpx2.Response) -> None:
+        content = await response.aread()
+        metadata = OAuthMetadata.model_validate_json(content)
+        self.context.oauth_metadata = metadata
+
+    async def _validate_resource_match(self, prm: ProtectedResourceMetadata) -> None:
+        """Validate that PRM resource matches the server URL per RFC 8707."""
+        prm_resource = str(prm.resource) if prm.resource else None
+
+        if self._validate_resource_url_callback is not None:
+            await self._validate_resource_url_callback(self.context.server_url, prm_resource)
+            return
+
+        if not prm_resource:
+            return  # pragma: no cover
+        default_resource = resource_url_from_server_url(self.context.server_url)
+        if not check_resource_allowed(requested_resource=default_resource, configured_resource=prm_resource):
+            raise OAuthFlowError(f"Protected resource {prm_resource} does not match expected {default_resource}")
+
+    async def async_auth_flow(self, request: httpx2.Request) -> AsyncGenerator[httpx2.Request, httpx2.Response]:
+        """httpx2 auth flow integration."""
+        async with self.context.lock:
+            if not self._initialized:
+                await self._initialize()
+
+            # Capture protocol version from request headers
+            self.context.protocol_version = request.headers.get(MCP_PROTOCOL_VERSION_HEADER)
+
+            if not self.context.is_token_valid() and self.context.can_refresh_token():
+                # Try to refresh token
+                refresh_request = await self._refresh_token()
+                refresh_response = yield refresh_request
+
+                if not await self._handle_refresh_response(refresh_response):
+                    # Refresh failed, need full re-authentication
+                    self._initialized = False
+
+            if self.context.is_token_valid():
+                self._add_auth_header(request)
+
+            response = yield request
+
+            if response.status_code == 401:
+                # Perform full OAuth flow
+                try:
+                    # OAuth flow must be inline due to generator constraints
+                    www_auth_resource_metadata_url = extract_resource_metadata_from_www_auth(response)
+
+                    # Step 1: Discover protected resource metadata (SEP-985 with fallback support)
+                    prm_discovery_urls = build_protected_resource_metadata_discovery_urls(
+                        www_auth_resource_metadata_url, self.context.server_url
+                    )
+
+                    for url in prm_discovery_urls:  # pragma: no branch
+                        discovery_request = create_oauth_metadata_request(url)
+
+                        discovery_response = yield discovery_request  # sending request
+
+                        prm = await handle_protected_resource_response(discovery_response)
+                        if prm:
+                            # Validate PRM resource matches server URL (RFC 8707)
+                            await self._validate_resource_match(prm)
+                            self.context.protected_resource_metadata = prm
+
+                            # todo: try all authorization_servers to find the OASM
+                            assert (
+                                len(prm.authorization_servers) > 0
+                            )  # this is always true as authorization_servers has a min length of 1
+
+                            self.context.auth_server_url = str(prm.authorization_servers[0])
+                            break
+                        else:
+                            logger.debug(f"Protected resource metadata discovery failed: {url}")
+
+                    # SEP-2352: stored credentials are bound to the issuer that registered them.
+                    # If the authorization server changed, drop them (and the old tokens) so the
+                    # flow re-registers instead of presenting another server's credentials.
+                    if (
+                        self.context.client_info is not None
+                        and self.context.auth_server_url is not None
+                        and not credentials_match_issuer(
+                            self.context.client_info, self.context.auth_server_url, self.context.client_metadata_url
+                        )
+                    ):
+                        logger.debug("Authorization server changed; discarding bound credentials and re-registering")
+                        self.context.client_info = None
+                        self.context.clear_tokens()
+                        # Any cached AS metadata is for the old server; drop it so a failed
+                        # rediscovery cannot leak the old registration/token endpoints into Step 4.
+                        self.context.oauth_metadata = None
+
+                    asm_discovery_urls = build_oauth_authorization_server_metadata_discovery_urls(
+                        self.context.auth_server_url, self.context.server_url
+                    )
+
+                    # Step 2: Discover OAuth Authorization Server Metadata (OASM) (with fallback for legacy servers)
+                    for url in asm_discovery_urls:  # pragma: no branch
+                        oauth_metadata_request = create_oauth_metadata_request(url)
+                        oauth_metadata_response = yield oauth_metadata_request
+
+                        ok, asm = await handle_auth_metadata_response(oauth_metadata_response)
+                        if not ok:
+                            break
+                        if ok and asm:
+                            # SEP-2468: metadata issuer must match the discovery issuer
+                            if self.context.auth_server_url is not None:
+                                validate_metadata_issuer(asm, self.context.auth_server_url)
+                            self.context.oauth_metadata = asm
+                            break
+                        else:
+                            logger.debug(f"OAuth metadata discovery failed: {url}")
+
+                    # SEP-2352: on the legacy no-PRM path the issuer is only known after ASM
+                    # discovery, so re-evaluate the binding here using the discovered metadata
+                    # issuer (mirroring the bound_issuer fallback in Step 4).
+                    if (
+                        self.context.client_info is not None
+                        and self.context.auth_server_url is None
+                        and self.context.oauth_metadata is not None
+                        and not credentials_match_issuer(
+                            self.context.client_info,
+                            str(self.context.oauth_metadata.issuer),
+                            self.context.client_metadata_url,
+                        )
+                    ):
+                        logger.debug("Authorization server changed; discarding bound credentials and re-registering")
+                        self.context.client_info = None
+                        self.context.clear_tokens()
+
+                    # Step 3: Apply scope selection strategy
+                    self.context.client_metadata.scope = get_client_metadata_scopes(
+                        extract_scope_from_www_auth(response),
+                        self.context.protected_resource_metadata,
+                        self.context.oauth_metadata,
+                        self.context.client_metadata.grant_types,
+                    )
+
+                    # Step 4: Register client or use URL-based client ID (CIMD)
+                    if not self.context.client_info:
+                        # SEP-2352: the issuer to bind these credentials to, when known.
+                        discovered_issuer: str | None = None
+                        if self.context.oauth_metadata is not None:
+                            discovered_issuer = self.context.auth_server_url or str(self.context.oauth_metadata.issuer)
+
+                        if should_use_client_metadata_url(
+                            self.context.oauth_metadata, self.context.client_metadata_url
+                        ):
+                            # Use URL-based client ID (CIMD). CIMD records are portable across
+                            # authorization servers, so the issuer stamp is informational.
+                            logger.debug(f"Using URL-based client ID (CIMD): {self.context.client_metadata_url}")
+                            client_information = create_client_info_from_metadata_url(
+                                self.context.client_metadata_url,  # type: ignore[arg-type]
+                                redirect_uris=self.context.client_metadata.redirect_uris,
+                            )
+                            client_information.issuer = discovered_issuer
+                            self.context.client_info = client_information
+                            await self.context.storage.set_client_info(client_information)
+                        else:
+                            # Fallback to Dynamic Client Registration
+                            fallback_base = self.context.get_authorization_base_url(self.context.server_url)
+                            registration_request = create_client_registration_request(
+                                self.context.oauth_metadata, self.context.client_metadata, fallback_base
+                            )
+                            registration_response = yield registration_request
+                            client_information = await handle_registration_response(registration_response)
+                            check_registration_usable(client_information)
+                            # Only record the issuer when the registration above actually targeted
+                            # the discovered AS — either via its published registration_endpoint,
+                            # or because the resource-origin /register fallback is on the issuer's
+                            # own host (legacy same-origin embedded AS). Otherwise the fallback hit
+                            # a different server and recording a binding to the PRM-advertised AS
+                            # would persist a binding that was never established.
+                            if (
+                                self.context.oauth_metadata is not None
+                                and discovered_issuer is not None
+                                and (
+                                    self.context.oauth_metadata.registration_endpoint is not None
+                                    or self.context.get_authorization_base_url(discovered_issuer) == fallback_base
+                                )
+                            ):
+                                client_information.issuer = discovered_issuer
+                            self.context.client_info = client_information
+                            await self.context.storage.set_client_info(client_information)
+
+                    # Step 5: Perform authorization and complete token exchange
+                    token_response = yield await self._perform_authorization()
+                    await self._handle_token_response(token_response)
+                except Exception:
+                    logger.exception("OAuth flow error")
+                    raise
+
+                # Retry with new tokens
+                self._add_auth_header(request)
+                yield request
+            elif response.status_code == 403:
+                # Step 1: Extract error field from WWW-Authenticate header
+                error = extract_field_from_www_auth(response, "error")
+
+                # Step 2: Check if we need to step-up authorization
+                if error == "insufficient_scope":  # pragma: no branch
+                    try:
+                        # Step 2a: Union previously requested scopes with the newly challenged
+                        # scopes (SEP-2350) so escalating one operation keeps the others' grants.
+                        # Fold in the stored token's scope too: on a restart the token is reloaded
+                        # but client_metadata.scope is not, so it would otherwise be the only basis.
+                        challenged_scope = get_client_metadata_scopes(
+                            extract_scope_from_www_auth(response),
+                            self.context.protected_resource_metadata,
+                            self.context.oauth_metadata,
+                            self.context.client_metadata.grant_types,
+                        )
+                        granted_scope = self.context.current_tokens.scope if self.context.current_tokens else None
+                        prior_scope = union_scopes(self.context.client_metadata.scope, granted_scope)
+                        self.context.client_metadata.scope = union_scopes(prior_scope, challenged_scope)
+
+                        # Step 2b: Perform (re-)authorization and token exchange
+                        token_response = yield await self._perform_authorization()
+                        await self._handle_token_response(token_response)
+                    except Exception:  # pragma: no cover
+                        logger.exception("OAuth flow error")
+                        raise
+
+                # Retry with new tokens
+                self._add_auth_header(request)
+                yield request

.mcp-venv/lib/python3.13/site-packages/mcp/client/auth/utils.py

@@ -0,0 +1,427 @@
+import re
+from typing import Any, cast
+from urllib.parse import urljoin, urlparse
+
+from httpx2 import Request, Response
+from mcp_types import LATEST_PROTOCOL_VERSION
+from pydantic import AnyUrl, ValidationError
+from pydantic_core import from_json
+
+from mcp.client.auth import OAuthFlowError, OAuthRegistrationError, OAuthTokenError
+from mcp.shared.auth import (
+    OAuthClientInformationFull,
+    OAuthClientMetadata,
+    OAuthMetadata,
+    OAuthToken,
+    ProtectedResourceMetadata,
+)
+from mcp.shared.inbound import MCP_PROTOCOL_VERSION_HEADER
+
+
+def extract_field_from_www_auth(response: Response, field_name: str) -> str | None:
+    """Extract field from WWW-Authenticate header.
+
+    Returns:
+        Field value if found in WWW-Authenticate header, None otherwise
+    """
+    www_auth_header = response.headers.get("WWW-Authenticate")
+    if not www_auth_header:
+        return None
+
+    # Pattern matches: field_name="value" or field_name=value (unquoted)
+    pattern = rf'{field_name}=(?:"([^"]+)"|([^\s,]+))'
+    match = re.search(pattern, www_auth_header)
+
+    if match:
+        # Return quoted value if present, otherwise unquoted value
+        return match.group(1) or match.group(2)
+
+    return None
+
+
+def extract_scope_from_www_auth(response: Response) -> str | None:
+    """Extract scope parameter from WWW-Authenticate header as per RFC 6750.
+
+    Returns:
+        Scope string if found in WWW-Authenticate header, None otherwise
+    """
+    return extract_field_from_www_auth(response, "scope")
+
+
+def extract_resource_metadata_from_www_auth(response: Response) -> str | None:
+    """Extract protected resource metadata URL from WWW-Authenticate header as per RFC 9728.
+
+    Returns:
+        Resource metadata URL if found in WWW-Authenticate header, None otherwise
+    """
+    if not response or response.status_code != 401:
+        return None  # pragma: no cover
+
+    return extract_field_from_www_auth(response, "resource_metadata")
+
+
+def build_protected_resource_metadata_discovery_urls(www_auth_url: str | None, server_url: str) -> list[str]:
+    """Build ordered list of URLs to try for protected resource metadata discovery.
+
+    Per SEP-985, the client MUST:
+    1. Try resource_metadata from WWW-Authenticate header (if present)
+    2. Fall back to path-based well-known URI: /.well-known/oauth-protected-resource/{path}
+    3. Fall back to root-based well-known URI: /.well-known/oauth-protected-resource
+
+    Args:
+        www_auth_url: Optional resource_metadata URL extracted from the WWW-Authenticate header
+        server_url: Server URL
+
+    Returns:
+        Ordered list of URLs to try for discovery
+    """
+    urls: list[str] = []
+
+    # Priority 1: WWW-Authenticate header with resource_metadata parameter
+    if www_auth_url:
+        urls.append(www_auth_url)
+
+    # Priority 2-3: Well-known URIs (RFC 9728)
+    parsed = urlparse(server_url)
+    base_url = f"{parsed.scheme}://{parsed.netloc}"
+
+    # Priority 2: Path-based well-known URI (if server has a path component)
+    if parsed.path and parsed.path != "/":
+        path_based_url = urljoin(base_url, f"/.well-known/oauth-protected-resource{parsed.path}")
+        urls.append(path_based_url)
+
+    # Priority 3: Root-based well-known URI
+    root_based_url = urljoin(base_url, "/.well-known/oauth-protected-resource")
+    urls.append(root_based_url)
+
+    return urls
+
+
+def get_client_metadata_scopes(
+    www_authenticate_scope: str | None,
+    protected_resource_metadata: ProtectedResourceMetadata | None,
+    authorization_server_metadata: OAuthMetadata | None = None,
+    client_grant_types: list[str] | None = None,
+) -> str | None:
+    """Select effective scopes and augment for refresh token support."""
+    selected_scope: str | None = None
+
+    # MCP spec scope selection priority:
+    #   1. WWW-Authenticate header scope
+    #   2. PRM scopes_supported
+    #   3. AS scopes_supported (SDK fallback)
+    #   4. Omit scope parameter
+    if www_authenticate_scope is not None:
+        selected_scope = www_authenticate_scope
+    elif protected_resource_metadata is not None and protected_resource_metadata.scopes_supported is not None:
+        selected_scope = " ".join(protected_resource_metadata.scopes_supported)
+    elif authorization_server_metadata is not None and authorization_server_metadata.scopes_supported is not None:
+        selected_scope = " ".join(authorization_server_metadata.scopes_supported)
+
+    # SEP-2207: append offline_access when the AS supports it and the client can use refresh tokens
+    if (
+        selected_scope is not None
+        and authorization_server_metadata is not None
+        and authorization_server_metadata.scopes_supported is not None
+        and "offline_access" in authorization_server_metadata.scopes_supported
+        and client_grant_types is not None
+        and "refresh_token" in client_grant_types
+        and "offline_access" not in selected_scope.split()
+    ):
+        selected_scope = f"{selected_scope} offline_access"
+
+    return selected_scope
+
+
+def union_scopes(previous_scope: str | None, new_scope: str | None) -> str | None:
+    """Merge two space-delimited scope strings, preserving order and dropping duplicates.
+
+    SEP-2350: on step-up re-authorization the client requests the union of previously requested
+    scopes and the newly challenged scopes, so escalating one operation does not drop the
+    permissions granted for another. Previously requested scopes come first; new scopes are
+    appended in order.
+    """
+    if not previous_scope:
+        return new_scope
+    if not new_scope:
+        return previous_scope
+
+    merged = previous_scope.split()
+    seen = set(merged)
+    for scope in new_scope.split():
+        if scope not in seen:
+            merged.append(scope)
+            seen.add(scope)
+    return " ".join(merged)
+
+
+def build_oauth_authorization_server_metadata_discovery_urls(auth_server_url: str | None, server_url: str) -> list[str]:
+    """Generate an ordered list of URLs for authorization server metadata discovery.
+
+    Args:
+        auth_server_url: OAuth Authorization Server Metadata URL if found, otherwise None
+        server_url: URL for the MCP server, used as a fallback if auth_server_url is None
+    """
+
+    if not auth_server_url:
+        # Legacy path using the 2025-03-26 spec:
+        # link: https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization
+        parsed = urlparse(server_url)
+        return [f"{parsed.scheme}://{parsed.netloc}/.well-known/oauth-authorization-server"]
+
+    urls: list[str] = []
+    parsed = urlparse(auth_server_url)
+    base_url = f"{parsed.scheme}://{parsed.netloc}"
+
+    # RFC 8414: Path-aware OAuth discovery
+    if parsed.path and parsed.path != "/":
+        oauth_path = f"/.well-known/oauth-authorization-server{parsed.path.rstrip('/')}"
+        urls.append(urljoin(base_url, oauth_path))
+
+        # RFC 8414 section 5: Path-aware OIDC discovery
+        # See https://www.rfc-editor.org/rfc/rfc8414.html#section-5
+        oidc_path = f"/.well-known/openid-configuration{parsed.path.rstrip('/')}"
+        urls.append(urljoin(base_url, oidc_path))
+
+        # https://openid.net/specs/openid-connect-discovery-1_0.html
+        oidc_path = f"{parsed.path.rstrip('/')}/.well-known/openid-configuration"
+        urls.append(urljoin(base_url, oidc_path))
+        return urls
+
+    # OAuth root
+    urls.append(urljoin(base_url, "/.well-known/oauth-authorization-server"))
+
+    # OIDC 1.0 fallback (appends to full URL per OIDC spec)
+    # https://openid.net/specs/openid-connect-discovery-1_0.html
+    urls.append(urljoin(base_url, "/.well-known/openid-configuration"))
+
+    return urls
+
+
+async def handle_protected_resource_response(
+    response: Response,
+) -> ProtectedResourceMetadata | None:
+    """Handle protected resource metadata discovery response.
+
+    Per SEP-985, supports fallback when discovery fails at one URL.
+
+    Returns:
+        ProtectedResourceMetadata if successfully discovered, None if we should try next URL
+    """
+    if response.status_code == 200:
+        try:
+            content = await response.aread()
+            metadata = ProtectedResourceMetadata.model_validate_json(content)
+            return metadata
+
+        except ValidationError:  # pragma: no cover
+            # Invalid metadata - try next URL
+            return None
+    else:
+        # Not found - try next URL in fallback chain
+        return None
+
+
+async def handle_auth_metadata_response(response: Response) -> tuple[bool, OAuthMetadata | None]:
+    if response.status_code == 200:
+        try:
+            content = await response.aread()
+            asm = OAuthMetadata.model_validate_json(content)
+            return True, asm
+        except ValidationError:  # pragma: no cover
+            return True, None
+    elif response.status_code < 400 or response.status_code >= 500:
+        return False, None  # Non-4XX error, stop trying
+    return True, None
+
+
+def validate_authorization_response_iss(iss: str | None, oauth_metadata: OAuthMetadata | None) -> None:
+    """Validate the RFC 9207 `iss` authorization-response parameter.
+
+    Per RFC 9207 section 2.4, the client compares `iss` against the issuer of the
+    authorization server the request was sent to, using simple string comparison
+    (RFC 3986 section 6.2.1, i.e. without URL normalization), and rejects on mismatch.
+    A response that omits `iss` is rejected only when the server advertised support via
+    `authorization_response_iss_parameter_supported`.
+
+    Raises:
+        OAuthFlowError: If `iss` is present and does not match, or is absent when the
+            authorization server advertised support.
+    """
+    expected = str(oauth_metadata.issuer) if oauth_metadata else None
+
+    if iss is not None:
+        if iss != expected:
+            raise OAuthFlowError(f"Authorization response iss mismatch: {iss} != {expected}")
+        return
+
+    if oauth_metadata is not None and oauth_metadata.authorization_response_iss_parameter_supported:
+        raise OAuthFlowError("Authorization response missing iss parameter advertised by the authorization server")
+
+
+def validate_metadata_issuer(oauth_metadata: OAuthMetadata, expected_issuer: str) -> None:
+    """Validate that authorization server metadata `issuer` matches the discovery issuer.
+
+    Per RFC 8414 section 3.3 / SEP-2468, the `issuer` in the metadata must match the issuer
+    used to construct the well-known URL, compared as a simple string (RFC 3986 section 6.2.1).
+
+    Raises:
+        OAuthFlowError: If the metadata issuer does not match `expected_issuer`.
+    """
+    if str(oauth_metadata.issuer) != expected_issuer:
+        raise OAuthFlowError(
+            f"Authorization server metadata issuer mismatch: {oauth_metadata.issuer} != {expected_issuer}"
+        )
+
+
+def create_oauth_metadata_request(url: str) -> Request:
+    return Request("GET", url, headers={MCP_PROTOCOL_VERSION_HEADER: LATEST_PROTOCOL_VERSION})
+
+
+def create_client_registration_request(
+    auth_server_metadata: OAuthMetadata | None, client_metadata: OAuthClientMetadata, auth_base_url: str
+) -> Request:
+    """Build a client registration request."""
+
+    if auth_server_metadata and auth_server_metadata.registration_endpoint:
+        registration_url = str(auth_server_metadata.registration_endpoint)
+    else:
+        registration_url = urljoin(auth_base_url, "/register")
+
+    registration_data = client_metadata.model_dump(by_alias=True, mode="json", exclude_none=True)
+
+    return Request("POST", registration_url, json=registration_data, headers={"Content-Type": "application/json"})
+
+
+async def handle_registration_response(response: Response) -> OAuthClientInformationFull:
+    """Handle registration response."""
+    if response.status_code not in (200, 201):
+        await response.aread()
+        raise OAuthRegistrationError(f"Registration failed: {response.status_code} {response.text}")
+
+    try:
+        content = await response.aread()
+        body = from_json(content)
+        # `issuer` is the SDK's own binding of these credentials to the server they were
+        # registered with (SEP-2352), stamped by the auth flow - never sourced from the
+        # wire, so it is dropped before the body is parsed rather than trusted or cleared.
+        if isinstance(body, dict):
+            cast(dict[str, Any], body).pop("issuer", None)
+        return OAuthClientInformationFull.model_validate(body)
+    except ValueError as e:
+        # `from_json` reports malformed bytes/JSON as ValueError, and pydantic's
+        # ValidationError is itself a ValueError, so both parse layers surface here.
+        raise OAuthRegistrationError(f"Invalid registration response: {e}") from e
+
+
+def is_valid_client_metadata_url(url: str | None) -> bool:
+    """Validate that a URL is suitable for use as a client_id (CIMD).
+
+    The URL must be HTTPS with a non-root pathname.
+
+    Args:
+        url: The URL to validate
+
+    Returns:
+        True if the URL is a valid HTTPS URL with a non-root pathname
+    """
+    if not url:
+        return False
+    try:
+        parsed = urlparse(url)
+        return parsed.scheme == "https" and parsed.path not in ("", "/")
+    except Exception:
+        return False
+
+
+def credentials_match_issuer(
+    client_info: OAuthClientInformationFull, issuer: str, client_metadata_url: str | None
+) -> bool:
+    """Whether stored client credentials may be reused against `issuer` (SEP-2352).
+
+    A URL-based client ID (CIMD) is portable across authorization servers — the same self-hosted
+    document is resolved by whichever server is in use — so it always matches; CIMD is identified
+    by the client ID being the configured `client_metadata_url`, not by URL shape (a registration
+    server may also issue URL-shaped IDs that are bound to it). Credentials with a recorded issuer
+    match only when it equals `issuer` (simple string comparison). Credentials with no recorded
+    issuer (pre-registered, or stored before issuer binding existed) carry no binding to enforce
+    and are left as-is.
+    """
+    if client_metadata_url is not None and client_info.client_id == client_metadata_url:
+        return True
+    if client_info.issuer is None:
+        return True
+    return client_info.issuer == issuer
+
+
+def should_use_client_metadata_url(
+    oauth_metadata: OAuthMetadata | None,
+    client_metadata_url: str | None,
+) -> bool:
+    """Determine if URL-based client ID (CIMD) should be used instead of DCR.
+
+    URL-based client IDs should be used when:
+    1. The server advertises client_id_metadata_document_supported=True
+    2. The client has a valid client_metadata_url configured
+
+    Args:
+        oauth_metadata: OAuth authorization server metadata
+        client_metadata_url: URL-based client ID (already validated)
+
+    Returns:
+        True if CIMD should be used, False if DCR should be used
+    """
+    if not client_metadata_url:
+        return False
+
+    if not oauth_metadata:
+        return False
+
+    return oauth_metadata.client_id_metadata_document_supported is True
+
+
+def create_client_info_from_metadata_url(
+    client_metadata_url: str, redirect_uris: list[AnyUrl] | None = None
+) -> OAuthClientInformationFull:
+    """Create client information using a URL-based client ID (CIMD).
+
+    When using URL-based client IDs, the URL itself becomes the client_id
+    and no client_secret is used (token_endpoint_auth_method="none").
+
+    Args:
+        client_metadata_url: The URL to use as the client_id
+        redirect_uris: The redirect URIs from the client metadata, recorded on the client
+            information alongside the client_id
+
+    Returns:
+        OAuthClientInformationFull with the URL as client_id
+    """
+    return OAuthClientInformationFull(
+        client_id=client_metadata_url,
+        token_endpoint_auth_method="none",
+        redirect_uris=redirect_uris,
+    )
+
+
+async def handle_token_response_scopes(
+    response: Response,
+) -> OAuthToken:
+    """Parse and validate a token response.
+
+    Parses token response JSON. Callers should check response.status_code before calling.
+
+    Args:
+        response: HTTP response from token endpoint (status already checked by caller)
+
+    Returns:
+        Validated OAuthToken model
+
+    Raises:
+        OAuthTokenError: If response JSON is invalid
+    """
+    try:
+        content = await response.aread()
+        token_response = OAuthToken.model_validate_json(content)
+        return token_response
+    except ValidationError as e:  # pragma: no cover
+        raise OAuthTokenError(f"Invalid token response: {e}")

.mcp-venv/lib/python3.13/site-packages/mcp/client/caching.py

@@ -0,0 +1,387 @@
+"""Client-side response caching primitives (SEP-2549, protocol revision 2026-07-28)."""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, Final, Literal, Protocol
+
+import anyio
+import anyio.lowlevel
+from mcp_types import (
+    CacheableResult,
+    PromptListChangedNotification,
+    ResourceListChangedNotification,
+    ResourceUpdatedNotification,
+    ServerNotification,
+    ToolListChangedNotification,
+)
+from mcp_types.version import MODERN_PROTOCOL_VERSIONS
+
+__all__ = [
+    "MAX_TTL_MS",
+    "CacheConfig",
+    "CacheEntry",
+    "CacheKey",
+    "CacheMode",
+    "InMemoryResponseCacheStore",
+    "ResponseCacheStore",
+]
+
+logger = logging.getLogger(__name__)
+
+CacheMode = Literal["use", "refresh", "bypass"]
+"""Per-call cache behavior: `"use"` serves and stores, `"refresh"` stores
+without serving, `"bypass"` skips the cache entirely."""
+
+MAX_TTL_MS: Final[int] = 24 * 60 * 60 * 1000
+"""Cap on any entry's time-to-live (24 hours, in milliseconds); larger `ttlMs` values are clamped down."""
+
+
+@dataclass(frozen=True, slots=True)
+class CacheKey:
+    """Identity of one cached response; compare as the field tuple, never a flattened string (collision hazard)."""
+
+    method: str
+
+    params_key: str = ""
+    """Result-affecting params discriminator: the uri for `resources/read`, `""` for the list methods."""
+
+    partition: str = ""
+    """Coordinator-computed arm identifier; opaque to stores."""
+
+
+@dataclass(frozen=True, slots=True)
+class CacheEntry:
+    """One cached response with its freshness and sharing metadata."""
+
+    value: Any
+    """The cached result; the SDK deep-copies on write and on serve, so a store may hold it as-is."""
+
+    scope: Literal["public", "private"]
+    """Server-asserted `cacheScope`: only `"public"` entries may be shared across authorization contexts."""
+
+    expires_at: float | None
+    """Epoch seconds after which the entry is stale; `None` is never fresh."""
+
+
+class ResponseCacheStore(Protocol):
+    """Storage contract for the client response cache.
+
+    Each `Client` calls its store from a single event loop; per-operation
+    atomicity is the implementation's responsibility. Operations may raise -
+    the SDK degrades to a miss rather than failing the call. A serializing
+    store must round-trip `value` back to the result model object (a
+    wrong-shape entry is a miss, never an error). A lookup may issue two
+    sequential `get` calls (private arm, then public).
+    """
+
+    async def get(self, key: CacheKey) -> CacheEntry | None: ...
+
+    async def set(self, key: CacheKey, entry: CacheEntry) -> None: ...
+
+    async def delete(self, key: CacheKey) -> None: ...
+
+    async def clear(self) -> None: ...
+
+
+@dataclass(frozen=True, slots=True)
+class CacheConfig:
+    """Configuration for a `Client`'s response cache.
+
+    Raises:
+        ValueError: On a custom `store` without `partition`, an empty `target_id`, or a negative `default_ttl_ms`.
+    """
+
+    store: ResponseCacheStore | None = None
+    """Backing store; `None` means a per-client `InMemoryResponseCacheStore`.
+    A custom store requires an explicit `partition`."""
+
+    partition: str = ""
+    """Authorization-context identifier isolating `"private"`-scoped entries
+    within a shared store. Derive it from a verified credential - never from
+    request-supplied data or the server URL. Fixed for the `Client`'s
+    lifetime: construct a new `Client` when the principal changes."""
+
+    target_id: str | None = None
+    """Server-identity override for custom transports and proxies where the
+    SDK cannot derive one from a URL; must be non-empty when provided."""
+
+    default_ttl_ms: int = 0
+    """TTL in milliseconds for results carrying no `ttlMs` hint; the default `0` leaves them uncached."""
+
+    clock: Callable[[], float] = time.time
+    """Wall-clock source returning epoch seconds; injectable for expiry tests."""
+
+    share_public: bool = False
+    """Serve server-marked `"public"` entries across every partition in the store.
+
+    WARNING: this trusts the server's `"public"` classification for every
+    principal sharing the store - a mislabeled response leaks across tenants.
+    Constructor-level only: the per-call `cache_mode` can never widen sharing."""
+
+    def __post_init__(self) -> None:
+        if self.store is not None and not self.partition:
+            raise ValueError("a custom store requires an explicit partition")
+        if self.target_id == "":
+            raise ValueError("target_id must be a non-empty string or omitted")
+        if self.default_ttl_ms < 0:
+            raise ValueError(f"default_ttl_ms must be >= 0, got {self.default_ttl_ms}")
+
+
+class InMemoryResponseCacheStore:
+    """Default in-process `ResponseCacheStore`.
+
+    Method bodies are synchronous, so concurrent tasks never observe a torn
+    write. `max_entries` caps the whole store, evicting least-recently-used
+    at the cap (`0` disables it); `get` and `set` both refresh recency, so a
+    hot entry survives churn from other keys.
+
+    Raises:
+        ValueError: If `max_entries` is negative.
+    """
+
+    def __init__(self, *, max_entries: int = 1024) -> None:
+        if max_entries < 0:
+            raise ValueError(f"max_entries must be >= 0, got {max_entries}")
+        self._max_entries = max_entries
+        self._entries: dict[CacheKey, CacheEntry] = {}
+
+    async def get(self, key: CacheKey) -> CacheEntry | None:
+        entry = self._entries.get(key)
+        if entry is not None:
+            # Pop-and-reinsert moves the key to the back: the dict's insertion order is the LRU ledger.
+            self._entries[key] = self._entries.pop(key)
+        return entry
+
+    async def set(self, key: CacheKey, entry: CacheEntry) -> None:
+        self._entries.pop(key, None)
+        self._entries[key] = entry
+        if self._max_entries and len(self._entries) > self._max_entries:
+            del self._entries[next(iter(self._entries))]
+
+    async def delete(self, key: CacheKey) -> None:
+        self._entries.pop(key, None)
+
+    async def clear(self) -> None:
+        self._entries.clear()
+
+
+_GENERATION_MAP_CAP: Final[int] = 4096
+"""Cap on the generation map; at the cap the oldest key's eviction-race guard is dropped (FIFO)."""
+
+_STORE_CLEANUP_TIMEOUT: Final[float] = 5
+"""Bound for must-complete store cleanup deletes (mirrors the dispatcher's final-write bound);
+a wedged store delete must not hold client teardown uncancellably."""
+
+
+class ClientResponseCache:
+    """Coordinates the `Client` caching verbs with a `ResponseCacheStore`: keys, era gate, TTL/scope, eviction."""
+
+    def __init__(
+        self,
+        *,
+        store: ResponseCacheStore,
+        partition: str,
+        arm_id: str,
+        default_ttl_ms: int,
+        clock: Callable[[], float],
+        share_public: bool,
+        negotiated_version: Callable[[], str | None],
+        generation_map_cap: int = _GENERATION_MAP_CAP,
+        store_cleanup_timeout: float = _STORE_CLEANUP_TIMEOUT,
+    ) -> None:
+        self._store = store
+        self._partition = partition
+        self._arm_id = arm_id
+        self._share_public = share_public
+        self._default_ttl_ms = default_ttl_ms
+        self._clock = clock
+        self._negotiated_version = negotiated_version
+        # A key is eviction-race-guarded iff registered here.
+        self._generations: dict[tuple[str, str], int] = {}
+        self._generation_map_cap = generation_map_cap
+        self._store_cleanup_timeout = store_cleanup_timeout
+        self._warned_store_ops: set[str] = set()
+
+    def _arm(self, scope: Literal["public", "private"]) -> str:
+        # JSON arrays so crafted arm_id/partition values cannot collide across field boundaries.
+        # The negotiated version era-scopes every arm: a session never serves an entry written
+        # under a different protocol era (its content differs - sieve-stripped fields, header
+        # filtering). Every caller runs post-connect; were that ever untrue, the supplier's
+        # None still partitions harmlessly.
+        fields: list[str | None] = [scope, self._negotiated_version(), self._arm_id]
+        if scope == "private" or not self._share_public:
+            fields.append(self._partition)
+        return json.dumps(fields)
+
+    async def read(self, method: str, params_key: str) -> CacheableResult | None:
+        """Serve a fresh entry for the key, or `None`; the served result is a deep copy."""
+        # A hit completes without any other yielding await, so checkpoint here: a poll
+        # loop over a fresh entry must not starve spawned tasks (eviction dispatch).
+        await anyio.lowlevel.checkpoint()
+        # A wrong-shape entry raises as late as the copy, so the boundary wraps the whole read path.
+        try:
+            entry = await self._get_fresh(CacheKey(method, params_key, self._arm("private")))
+            if entry is None:
+                # After a scope flip, a stale private entry must not shadow a fresh public one.
+                entry = await self._get_fresh(CacheKey(method, params_key, self._arm("public")))
+                if entry is not None and entry.scope != "public":
+                    # Never serve an entry the server scoped "private" out of the shared arm.
+                    entry = None
+            copied: CacheableResult | None = None if entry is None else entry.value.model_copy(deep=True)
+        except Exception:  # boundary around user store code: any read-path failure is a miss, never a failed call
+            self._warn_store_failure("get")
+            return None
+        self._warned_store_ops.discard("get")
+        return copied
+
+    async def _get_fresh(self, key: CacheKey) -> CacheEntry | None:
+        entry = await self._store.get(key)
+        if entry is None or entry.expires_at is None or entry.expires_at <= self._clock():
+            return None
+        return entry
+
+    def capture(self, method: str, params_key: str) -> int:
+        """Register the key for eviction-race detection before the fetch; `write` takes the returned generation."""
+        gen_key = (method, params_key)
+        if gen_key not in self._generations:
+            if len(self._generations) >= self._generation_map_cap:
+                # FIFO overflow: the dropped key's race guard degrades to the accepted co-tenant class.
+                del self._generations[next(iter(self._generations))]
+            self._generations[gen_key] = 0
+        return self._generations[gen_key]
+
+    async def write(
+        self,
+        method: str,
+        params_key: str,
+        result: CacheableResult,
+        gen_at_capture: int,
+        mode: Literal["use", "refresh"],
+    ) -> None:
+        """Store a fetched result under the arm its resolved scope selects."""
+        gen_key = (method, params_key)
+        if self._generation_moved(gen_key, gen_at_capture):
+            return  # the key was evicted while the fetch was in flight
+        ttl_ms, scope = self._resolve(result)
+        private_key = CacheKey(method, params_key, self._arm("private"))
+        public_key = CacheKey(method, params_key, self._arm("public"))
+        if ttl_ms <= 0:
+            if mode == "refresh":
+                # The refetch superseded the warm entry, which a cancellation must not leave serving.
+                await self._cleanup_delete(private_key, public_key)
+            return
+        own, opposite = (public_key, private_key) if scope == "public" else (private_key, public_key)
+        # Opposite arm first: a failed delete aborts before the set - never two arms answering for one key.
+        if not await self._delete(opposite):
+            # The own arm's entry is superseded too: best-effort delete, degrading to a full miss.
+            await self._cleanup_delete(own)
+            return
+        entry = CacheEntry(value=result.model_copy(deep=True), scope=scope, expires_at=self._clock() + ttl_ms / 1000)
+        try:
+            if not await self._set(own, entry):
+                # The fetch superseded any pre-existing own-arm entry, and the failed set
+                # left it in place: purge it (mirrors the opposite-arm-failure path).
+                await self._cleanup_delete(own)
+        finally:
+            # An eviction can land while the set commits - even when the await
+            # is cancelled - so re-check on every exit; the delete must complete
+            # so the pending cancellation cannot resurrect the evicted entry.
+            if self._generation_moved(gen_key, gen_at_capture):
+                await self._cleanup_delete(own)
+
+    async def evict_method(self, method: str) -> None:
+        """Evict the method's cursor-less entry."""
+        await self.evict_key(method, "")
+
+    async def evict_key(self, method: str, params_key: str) -> None:
+        """Evict one key from both arms.
+
+        Only the current era's arms are touched; other-era entries in a persistent store age out by TTL.
+        """
+        gen_key = (method, params_key)
+        # Bump first so an in-flight fetch cannot write the evicted entry back.
+        # Unregistered keys skip the bump (uris must not grow the map) but not
+        # the deletes - a persistent store may hold uncaptured entries.
+        if gen_key in self._generations:
+            self._generations[gen_key] += 1
+        # Must complete: a cancellation between the deletes would leave one arm serving the evicted entry.
+        await self._cleanup_delete(
+            CacheKey(method, params_key, self._arm("private")),
+            CacheKey(method, params_key, self._arm("public")),
+        )
+
+    async def evict_for_notification(self, notification: ServerNotification) -> None:
+        """Map a server notification to the entries it makes stale.
+
+        Eviction is eventual (spawned-task dispatch): the generation bump closes
+        the write-back race; a racing read may briefly serve the old entry.
+        """
+        match notification:
+            case ToolListChangedNotification():
+                await self.evict_method("tools/list")
+            case PromptListChangedNotification():
+                await self.evict_method("prompts/list")
+            case ResourceListChangedNotification():
+                # Templates enumerate the same changed resource space.
+                await self.evict_method("resources/list")
+                await self.evict_method("resources/templates/list")
+            case ResourceUpdatedNotification():
+                await self.evict_key("resources/read", notification.params.uri)
+            case _:
+                pass
+
+    def _resolve(self, result: CacheableResult) -> tuple[int, Literal["public", "private"]]:
+        # A legacy peer can also put `ttlMs`/`cacheScope` keys on the wire, so
+        # wire presence is not a peer-era signal - hints count only when modern.
+        modern = self._negotiated_version() in MODERN_PROTOCOL_VERSIONS
+        if modern and "ttl_ms" in result.model_fields_set:
+            # An explicit `ttlMs: 0` stays 0, and negatives are unconstructible
+            # upstream (model ge=0, parse-seam floor) - only the cap applies.
+            ttl_ms = result.ttl_ms
+        else:
+            ttl_ms = self._default_ttl_ms
+        scope: Literal["public", "private"] = "public" if modern and result.cache_scope == "public" else "private"
+        return min(ttl_ms, MAX_TTL_MS), scope
+
+    def _generation_moved(self, gen_key: tuple[str, str], gen_at_capture: int) -> bool:
+        # A FIFO-dropped key fails open (the accepted co-tenant race) rather than discarding the fetch.
+        return self._generations.get(gen_key, gen_at_capture) != gen_at_capture
+
+    async def _set(self, key: CacheKey, entry: CacheEntry) -> bool:
+        try:
+            await self._store.set(key, entry)
+        except Exception:  # boundary around user store code: nothing cached, the fetch already succeeded
+            self._warn_store_failure("set")
+            return False
+        self._warned_store_ops.discard("set")
+        return True
+
+    async def _cleanup_delete(self, *keys: CacheKey) -> None:
+        # Must-complete cleanup: shielded so a pending cancellation cannot skip the deletes,
+        # bounded so a wedged store delete cannot hold client teardown uncancellably.
+        with anyio.move_on_after(self._store_cleanup_timeout, shield=True) as scope:
+            for key in keys:
+                await self._delete(key)
+        if scope.cancelled_caught:
+            logger.warning("Response cache store delete timed out; the entry will age out by TTL")
+
+    async def _delete(self, key: CacheKey) -> bool:
+        try:
+            await self._store.delete(key)
+        except Exception:  # boundary around user store code: callers decide whether a failed delete aborts
+            self._warn_store_failure("delete")
+            return False
+        self._warned_store_ops.discard("delete")
+        return True
+
+    def _warn_store_failure(self, kind: Literal["get", "set", "delete"]) -> None:
+        # One warning per failure burst, per op kind; re-armed only when that
+        # same kind succeeds, so a healthy delete cannot re-arm a broken set.
+        if kind not in self._warned_store_ops:
+            self._warned_store_ops.add(kind)
+            logger.warning("Response cache store operation failed; continuing without the cache", exc_info=True)

.mcp-venv/lib/python3.13/site-packages/mcp/client/client.py

@@ -0,0 +1,950 @@
+"""Unified MCP Client that wraps ClientSession with transport management."""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import uuid
+from collections.abc import Awaitable, Callable, Mapping, Sequence
+from contextlib import AbstractAsyncContextManager, AsyncExitStack
+from dataclasses import KW_ONLY, dataclass, field
+from typing import Any, Literal, TypeVar, cast
+
+import anyio
+import anyio.lowlevel
+import mcp_types as types
+from mcp_types import (
+    INVALID_PARAMS,
+    CacheableResult,
+    CallToolResult,
+    CompleteResult,
+    EmptyResult,
+    ErrorData,
+    GetPromptResult,
+    Implementation,
+    InputRequest,
+    InputRequiredResult,
+    InputResponse,
+    InputResponses,
+    ListPromptsResult,
+    ListResourcesResult,
+    ListResourceTemplatesResult,
+    ListToolsResult,
+    LoggingLevel,
+    PaginatedRequestParams,
+    PromptReference,
+    ReadResourceResult,
+    RequestParamsMeta,
+    ResourceTemplateReference,
+    Result,
+    ServerCapabilities,
+)
+from mcp_types.version import HANDSHAKE_PROTOCOL_VERSIONS, MODERN_PROTOCOL_VERSIONS
+from typing_extensions import deprecated
+
+from mcp.client._input_required import DEFAULT_INPUT_REQUIRED_MAX_ROUNDS, run_input_required_driver
+from mcp.client._memory import InMemoryTransport
+from mcp.client._probe import negotiate_auto
+from mcp.client._transport import Transport
+from mcp.client.caching import CacheConfig, CacheMode, ClientResponseCache, InMemoryResponseCacheStore
+from mcp.client.extension import ClaimContext, ClientExtension, NotificationBinding, ResultClaim
+from mcp.client.session import (
+    ClientRequestContext,
+    ClientSession,
+    ElicitationFnT,
+    IncomingMessage,
+    ListRootsFnT,
+    LoggingFnT,
+    MessageHandlerFnT,
+    SamplingFnT,
+)
+from mcp.client.streamable_http import streamable_http_client
+from mcp.client.subscriptions import ServerEvent, Subscription
+from mcp.client.subscriptions import listen as _listen
+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, MCPError
+from mcp.shared.extension import validate_extension_identifier
+from mcp.shared.jsonrpc_dispatcher import JSONRPCDispatcher
+from mcp.shared.subscriptions import event_to_notification
+
+logger = logging.getLogger(__name__)
+
+ConnectMode = Literal["legacy", "auto"] | str
+"""``mode=`` value: ``"legacy"`` (initialize handshake), ``"auto"`` (discover, fall back to
+initialize), or a modern protocol-version string (adopt directly). The ``str`` arm is for
+forward-compat; ``Client.__post_init__`` rejects anything outside that set at construction."""
+
+_T = TypeVar("_T")
+_ResultT = TypeVar("_ResultT")
+_CacheableT = TypeVar("_CacheableT", bound=CacheableResult)
+
+_Connector = Callable[[AsyncExitStack, ConnectMode, bool], Awaitable["Dispatcher[Any]"]]
+"""Resolved at ``__post_init__`` from the shape of ``server`` alone: enter whatever resources
+are needed onto the exit stack and hand back the ``Dispatcher`` ``ClientSession`` will drive.
+``mode`` and ``raise_exceptions`` are passed at call time so they're read at the same moment
+``__aenter__`` reads them for the handshake step."""
+
+
+def _connect_transport(transport: Transport) -> _Connector:
+    """Connector for the stream-backed paths (URL, user-supplied ``Transport``)."""
+
+    async def connect(exit_stack: AsyncExitStack, _mode: ConnectMode, _raise_exceptions: bool) -> Dispatcher[Any]:
+        read_stream, write_stream = await exit_stack.enter_async_context(transport)
+        return JSONRPCDispatcher(read_stream, write_stream)
+
+    return connect
+
+
+def _connect_inproc(server: Server[Any]) -> _Connector:
+    """Connector for an in-process ``Server``: legacy mode drives the stream loop via
+    ``InMemoryTransport``; any other mode drives the modern per-request path through a
+    ``DirectDispatcher`` peer pair (no streams, no JSON-RPC framing, no initialize handshake)."""
+
+    async def connect(exit_stack: AsyncExitStack, mode: ConnectMode, raise_exceptions: bool) -> Dispatcher[Any]:
+        if mode == "legacy":
+            transport = InMemoryTransport(server, raise_exceptions=raise_exceptions)
+            read_stream, write_stream = await exit_stack.enter_async_context(transport)
+            return JSONRPCDispatcher(read_stream, write_stream)
+        lifespan_state = await exit_stack.enter_async_context(server.lifespan(server))
+        client_disp, server_disp = create_direct_dispatcher_pair(raise_handler_exceptions=raise_exceptions)
+        tg = await exit_stack.enter_async_context(anyio.create_task_group())
+        exit_stack.callback(server_disp.close)
+        on_request = modern_on_request(server, lifespan_state)
+        await tg.start(server_disp.run, on_request, _no_inbound_client_notifications)
+        return client_disp
+
+    return connect
+
+
+def _connected(value: _T | None) -> _T:
+    """Narrow a post-handshake session attribute from ``T | None`` to ``T``.
+
+    ``Client.__aenter__`` only assigns ``_session`` after the handshake succeeds, so inside
+    ``async with Client(...)`` these attributes are always populated; the ``.session`` gate
+    raises before this is reached otherwise. The guard exists for pyright, not runtime.
+    """
+    if value is None:  # pragma: no cover
+        raise RuntimeError("Client must be used within an async context manager")
+    return value
+
+
+def _strip_userinfo(url: str) -> str:
+    """Drop any userinfo from the URL's authority component; byte-exact otherwise.
+
+    Credentials must not enter cache-key material; any further normalization could merge distinct servers.
+    """
+    # Pure text, no urlsplit: it strips embedded tab/CR/LF before parsing, which would misalign slices.
+    sep = url.find("//")
+    if sep == -1:
+        return url
+    start = sep + 2
+    end = len(url)
+    for delimiter in "/?#":
+        if (found := url.find(delimiter, start)) != -1:
+            end = min(end, found)
+    authority = url[start:end]
+    if "@" not in authority:
+        return url
+    return url[:start] + authority.rpartition("@")[2] + url[end:]
+
+
+def _evicting_message_handler(cache: ClientResponseCache, user_handler: MessageHandlerFnT | None) -> MessageHandlerFnT:
+    """Wrap the session message handler with cache eviction on server notifications."""
+
+    async def handler(message: IncomingMessage) -> None:
+        if isinstance(message, types.ServerNotification):
+            try:
+                await cache.evict_for_notification(message)
+            except Exception:  # boundary: eviction reaches user store code; a cache fault must not block delivery
+                logger.exception("Response cache eviction failed; the notification is still delivered")
+        if user_handler is not None:
+            await user_handler(message)
+        else:
+            # Mirrors ClientSession's default handler (session._default_message_handler).
+            await anyio.lowlevel.checkpoint()
+
+    return handler
+
+
+def _synthesize_discover(protocol_version: str) -> types.DiscoverResult:
+    return types.DiscoverResult(
+        supported_versions=[protocol_version],
+        capabilities=types.ServerCapabilities(),
+        result_type="complete",
+        ttl_ms=0,
+        cache_scope="public",
+    )
+
+
+async def _no_inbound_client_notifications(_dctx: Any, _method: str, _params: Mapping[str, Any] | None) -> None:
+    """Server-side inbound ``OnNotify`` for the modern in-process path — receives nothing.
+
+    At 2026-07-28 the spec defines no client→server notifications: ``initialized`` and
+    ``roots/list_changed`` are removed, and cancellation is structural (anyio scope cancel
+    through the direct await, not a notify). Server→client notifications (progress, log
+    messages) flow the other way via the per-request ``DispatchContext`` into the client's
+    callbacks, and are not seen here.
+    """
+
+
+@dataclass(frozen=True)
+class _FoldedExtensions:
+    """`Client.extensions` instances folded into the shapes `ClientSession` consumes."""
+
+    ad: dict[str, dict[str, Any]] | None
+    claims: dict[str, tuple[ResultClaim[Any], ...]] | None
+    bindings: tuple[NotificationBinding[Any], ...] | None
+    by_model: Mapping[type[Result], ResultClaim[Any]]
+
+
+def _fold_extensions(extensions: Sequence[ClientExtension] | None) -> _FoldedExtensions:
+    """Fold extension contributions at construction, naming both owners on duplicate tags or methods."""
+    if isinstance(extensions, Mapping):
+        raise TypeError(
+            "extensions= takes a sequence of ClientExtension instances. The mapping form was "
+            "replaced: use advertise(identifier, settings) for advertise-only entries"
+        )
+    if not extensions:
+        return _FoldedExtensions(ad=None, claims=None, bindings=None, by_model={})
+    ad: dict[str, dict[str, Any]] = {}
+    claims: dict[str, tuple[ResultClaim[Any], ...]] = {}
+    bindings: list[NotificationBinding[Any]] = []
+    by_model: dict[type[Result], ResultClaim[Any]] = {}
+    claim_owners: dict[str, str] = {}
+    binding_owners: dict[str, str] = {}
+    for extension in extensions:
+        identifier = getattr(extension, "identifier", None)
+        if identifier is None:
+            raise ValueError(
+                f"{type(extension).__name__} has no `identifier`; a ClientExtension must set the "
+                "`identifier` class attribute (or assign one in `__init__`) before it can be used"
+            )
+        validate_extension_identifier(identifier, owner=type(extension).__name__)
+        if identifier in ad:
+            raise ValueError(f"extension identifier {identifier!r} is passed more than once")
+        ad[identifier] = extension.settings()
+        extension_claims = tuple(extension.claims())
+        for claim in extension_claims:
+            tag = claim.result_type
+            if tag in claim_owners:
+                owner = claim_owners[tag]
+                both = (
+                    f"extension {identifier!r} claims"
+                    if owner == identifier
+                    else (f"extensions {owner!r} and {identifier!r} both claim")
+                )
+                raise ValueError(f"{both} resultType {tag!r}; a wire tag can have only one resolver")
+            claim_owners[tag] = identifier
+            # Each model pins its result_type Literal to one tag, so this index cannot collide.
+            by_model[claim.model] = claim
+        if extension_claims:
+            claims[identifier] = extension_claims
+        for binding in extension.notifications():
+            if binding.method in binding_owners:
+                owner = binding_owners[binding.method]
+                both = (
+                    f"extension {identifier!r} binds"
+                    if owner == identifier
+                    else (f"extensions {owner!r} and {identifier!r} both bind")
+                )
+                raise ValueError(f"{both} notification method {binding.method!r}; a method can have only one observer")
+            binding_owners[binding.method] = identifier
+            bindings.append(binding)
+    return _FoldedExtensions(ad=ad, claims=claims or None, bindings=tuple(bindings) or None, by_model=by_model)
+
+
+@dataclass
+class Client:
+    """A high-level MCP client for connecting to MCP servers.
+
+    Supports in-memory transport for testing (pass a Server or MCPServer instance),
+    Streamable HTTP transport (pass a URL string), or a custom Transport instance.
+
+    Example:
+        ```python
+        from mcp.client import Client
+        from mcp.server.mcpserver import MCPServer
+
+        server = MCPServer("test")
+
+        @server.tool()
+        def add(a: int, b: int) -> int:
+            return a + b
+
+        async def main():
+            async with Client(server) as client:
+                result = await client.call_tool("add", {"a": 1, "b": 2})
+
+        asyncio.run(main())
+        ```
+    """
+
+    server: Server[Any] | MCPServer | Transport | str
+    """The MCP server to connect to.
+
+    If the server is a `Server` or `MCPServer` instance, it will be connected in-process.
+    If the server is a URL string, it will be used as the URL for a `streamable_http_client` transport.
+    If the server is a `Transport` instance, it will be used directly.
+    """
+
+    _: KW_ONLY
+
+    # TODO(Marcelo): When do `raise_exceptions=True` actually raises?
+    raise_exceptions: bool = False
+    """Whether to raise exceptions from the server."""
+
+    read_timeout_seconds: float | None = None
+    """Timeout for read operations."""
+
+    sampling_callback: SamplingFnT | None = None
+    """Callback for handling sampling requests."""
+
+    sampling_capabilities: types.SamplingCapability | None = None
+    """Sampling sub-capabilities (e.g. tools) declared alongside `sampling_callback`; no effect without it."""
+
+    list_roots_callback: ListRootsFnT | None = None
+    """Callback for handling list roots requests."""
+
+    logging_callback: LoggingFnT | None = None
+    """Callback for handling logging notifications."""
+
+    log_level: LoggingLevel | None = None
+    """The log level to opt in to on 2026-07-28+ connections (deprecated logging feature, SEP-2577).
+
+    Modern (2026-07-28+) servers send `notifications/message` only for requests that opt in by
+    carrying `io.modelcontextprotocol/logLevel` in `_meta`, and only at or above that level. Setting
+    this stamps that opt-in on every request; `None` (the default) means no opt-in, so no log
+    messages arrive - a `logging_callback` alone is not an opt-in. No effect on handshake-era
+    connections, where the deprecated `logging/setLevel` request governs delivery instead. A
+    per-request `_meta` entry with the same key overrides this default."""
+
+    # TODO(Marcelo): Why do we have both "callback" and "handler"?
+    message_handler: MessageHandlerFnT | None = None
+    """Callback for handling raw messages."""
+
+    client_info: Implementation | None = None
+    """Client implementation info to send to server."""
+
+    mode: ConnectMode = "auto"
+    """How to negotiate the protocol version.
+
+    'auto' (the default) probes `server/discover` and falls back to the initialize handshake on legacy servers;
+    for an in-process `Server`/`MCPServer` it dispatches directly without JSON-RPC framing. 'legacy' forces the
+    initialize handshake (byte-identical pre-2026 behavior). A modern protocol-version string (e.g. '2026-07-28')
+    adopts that version directly without a probe — supply `prior_discover` to reuse a known DiscoverResult, or
+    omit it to synthesize a minimal one."""
+
+    prior_discover: types.DiscoverResult | None = None
+    """A previously-obtained DiscoverResult to install via .adopt() when mode is a version pin.
+    Ignored when mode='legacy'."""
+
+    elicitation_callback: ElicitationFnT | None = None
+    """Callback for handling elicitation requests."""
+
+    input_required_max_rounds: int = DEFAULT_INPUT_REQUIRED_MAX_ROUNDS
+    """Cap on `InputRequiredResult` retry rounds before `call_tool` / `get_prompt` /
+    `read_resource` give up. Use `client.session.<method>(..., allow_input_required=True)`
+    to drive the loop manually instead."""
+
+    extensions: Sequence[ClientExtension] | None = None
+    """Opt-in client extensions (SEP-2133).
+
+    Each instance contributes its capability ad, its result claims (resolved
+    transparently by `call_tool`), and its notification bindings. For an
+    ad-only entry use `mcp.client.advertise(identifier, settings)`."""
+
+    cache: CacheConfig | None = field(default_factory=CacheConfig)
+    """Client-side response caching for the SEP-2549 cacheable methods (2026-07-28).
+
+    The default `CacheConfig()` honors server `ttlMs`/`cacheScope` hints with a
+    per-client in-memory store; pass a customized `CacheConfig`, or `None` to
+    disable. The cacheable verbs take a per-call `cache_mode` (see `CacheMode`);
+    calls carrying `meta` always reach the server. A `CacheConfig` with a custom
+    `store` requires `target_id` when the server is not a URL (no identity can be
+    derived)."""
+
+    _entered: bool = field(init=False, default=False)
+    _session: ClientSession | None = field(init=False, default=None)
+    _exit_stack: AsyncExitStack | None = field(init=False, default=None)
+    _connect: _Connector = field(init=False, repr=False, compare=False)
+    _response_cache: ClientResponseCache | None = field(init=False, default=None, repr=False, compare=False)
+    _folded_extensions: _FoldedExtensions = field(init=False, repr=False, compare=False)
+
+    def __post_init__(self) -> None:
+        if self.mode not in ("legacy", "auto") and self.mode not in MODERN_PROTOCOL_VERSIONS:
+            hint = (
+                f" ({self.mode!r} is a handshake-era version; use mode='legacy')"
+                if self.mode in HANDSHAKE_PROTOCOL_VERSIONS
+                else ""
+            )
+            raise ValueError(
+                f"mode must be 'legacy', 'auto', or one of {list(MODERN_PROTOCOL_VERSIONS)}; got {self.mode!r}{hint}"
+            )
+
+        self._folded_extensions = _fold_extensions(self.extensions)
+
+        srv = self.server
+        if isinstance(srv, MCPServer):
+            srv = srv._lowlevel_server  # pyright: ignore[reportPrivateUsage]
+        if isinstance(srv, Server):
+            self._connect = _connect_inproc(srv)
+        elif isinstance(srv, str):
+            self._connect = _connect_transport(streamable_http_client(srv))
+        else:
+            self._connect = _connect_transport(srv)
+
+        if self.cache is not None:
+            config = self.cache
+            # Only the hash below leaves this scope - the raw identity may carry credentials; never log or store it.
+            target_id = config.target_id
+            if target_id is None and isinstance(self.server, str):
+                target_id = _strip_userinfo(self.server)
+            if target_id is None:
+                if config.store is not None:
+                    raise ValueError(
+                        "a custom cache store requires CacheConfig.target_id when the server is not a URL: "
+                        "in-process servers and Transport instances get a random per-client identity, so "
+                        "their entries in a shared store could never be served to another client"
+                    )
+                target_id = uuid.uuid4().hex
+            self._response_cache = ClientResponseCache(
+                store=config.store if config.store is not None else InMemoryResponseCacheStore(),
+                partition=config.partition,
+                arm_id=hashlib.sha256(target_id.encode()).hexdigest(),
+                default_ttl_ms=config.default_ttl_ms,
+                clock=config.clock,
+                share_public=config.share_public,
+                # Lazy: the negotiated version is unknown until __aenter__'s handshake.
+                negotiated_version=lambda: self._session.protocol_version if self._session is not None else None,
+            )
+
+    async def _build_session(self, exit_stack: AsyncExitStack) -> ClientSession:
+        """Enter the resolved connector and return an un-entered ClientSession."""
+        dispatcher = await self._connect(exit_stack, self.mode, self.raise_exceptions)
+        message_handler = self.message_handler
+        if self._response_cache is not None:
+            message_handler = _evicting_message_handler(self._response_cache, self.message_handler)
+        return ClientSession(
+            dispatcher=dispatcher,
+            read_timeout_seconds=self.read_timeout_seconds,
+            sampling_callback=self.sampling_callback,
+            sampling_capabilities=self.sampling_capabilities,
+            list_roots_callback=self.list_roots_callback,
+            logging_callback=self.logging_callback,
+            log_level=self.log_level,
+            message_handler=message_handler,
+            client_info=self.client_info,
+            elicitation_callback=self.elicitation_callback,
+            extensions=self._folded_extensions.ad,
+            result_claims=self._folded_extensions.claims,
+            notification_bindings=self._folded_extensions.bindings,
+        )
+
+    async def __aenter__(self) -> Client:
+        """Enter the async context manager."""
+        if self._entered:
+            raise RuntimeError("Client is already entered; cannot reenter")
+        self._entered = True
+
+        async with AsyncExitStack() as exit_stack:
+            session = await self._build_session(exit_stack)
+            session = await exit_stack.enter_async_context(session)
+
+            if self.mode == "legacy":
+                await session.initialize()
+            elif self.mode == "auto":
+                await negotiate_auto(session)
+            else:
+                session.adopt(self.prior_discover or _synthesize_discover(self.mode))
+
+            # Only publish the session after the handshake succeeds, so `_session is not None`
+            # implies the protocol_version/server_capabilities are populated (server_info
+            # stays optional: 2026-era servers may not identify themselves). If the
+            # handshake raised above, the local exit_stack unwinds the transport for us.
+            self._session = session
+            self._exit_stack = exit_stack.pop_all()
+            return self
+
+    async def __aexit__(self, exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: Any) -> None:
+        """Exit the async context manager."""
+        if self._exit_stack:  # pragma: no branch
+            await self._exit_stack.__aexit__(exc_type, exc_val, exc_tb)
+        self._session = None
+
+    @property
+    def session(self) -> ClientSession:
+        """Get the underlying ClientSession.
+
+        This provides access to the full ClientSession API for advanced use cases.
+
+        Raises:
+            RuntimeError: If accessed before entering the context manager.
+        """
+        if self._session is None:
+            raise RuntimeError("Client must be used within an async context manager")
+        return self._session
+
+    # TODO(maxisbey): the by-construction shape is for __aenter__ to return a connected-view
+    # type whose protocol_version/server_capabilities are non-Optional fields,
+    # eliminating these guards (and the one in .session). Same family as resolving the
+    # transport/connector at __post_init__ so the Optional internal fields disappear.
+    # (server_info stays Optional even connected: the 2026-era stamp is optional.)
+    @property
+    def protocol_version(self) -> str:
+        """Negotiated protocol version (set by initialize/discover/adopt during ``__aenter__``)."""
+        return _connected(self.session.protocol_version)
+
+    @property
+    def server_info(self) -> Implementation | None:
+        """Server name/version, or `None` when the server did not identify itself.
+
+        Legacy connections always carry it (`InitializeResult.serverInfo` is
+        required); on 2026-era connections the `_meta` `serverInfo` stamp is
+        optional, so an anonymous server reads as `None`.
+        """
+        return self.session.server_info
+
+    @property
+    def server_capabilities(self) -> ServerCapabilities:
+        """Server capabilities (set by initialize/discover/adopt during ``__aenter__``)."""
+        return _connected(self.session.server_capabilities)
+
+    @property
+    def instructions(self) -> str | None:
+        """Server-provided instructions text, if any."""
+        return self.session.instructions
+
+    @deprecated(
+        "ping is removed as of 2026-07-28; the method only works under mode='legacy'.",
+        category=MCPDeprecationWarning,
+    )
+    async def send_ping(self, *, meta: RequestParamsMeta | None = None) -> EmptyResult:
+        """Send a ping request to the server."""
+        return await self.session.send_ping(meta=meta)
+
+    @deprecated(
+        "Client-to-server progress is deprecated as of 2026-07-28; progress is server-to-client only.",
+        category=MCPDeprecationWarning,
+    )
+    async def send_progress_notification(
+        self,
+        progress_token: str | int,
+        progress: float,
+        total: float | None = None,
+        message: str | None = None,
+    ) -> None:
+        """Send a progress notification to the server."""
+        await self.session.send_progress_notification(  # pyright: ignore[reportDeprecated]
+            progress_token=progress_token,
+            progress=progress,
+            total=total,
+            message=message,
+        )
+
+    @deprecated("The logging capability is deprecated as of 2026-07-28 (SEP-2577).", category=MCPDeprecationWarning)
+    async def set_logging_level(self, level: LoggingLevel, *, meta: RequestParamsMeta | None = None) -> EmptyResult:
+        """Set the logging level on the server."""
+        return await self.session.set_logging_level(level=level, meta=meta)  # pyright: ignore[reportDeprecated]
+
+    async def _cached_fetch(
+        self,
+        method: str,
+        *,
+        cursor: str | None,
+        meta: RequestParamsMeta | None,
+        cache_mode: CacheMode,
+        send: Callable[[], Awaitable[_CacheableT]],
+        absorb: Callable[[_CacheableT], _CacheableT] | None = None,
+    ) -> _CacheableT:
+        """Serve one of the four list verbs through the response cache.
+
+        `absorb` (tools/list only) re-applies session-side derived state to a served cache hit.
+        """
+        cache = self._response_cache
+        if cache is None or cache_mode == "bypass":
+            return await send()
+        # A closed (or never-entered) client must raise, never serve cached entries.
+        _ = self.session
+        if meta is not None and cache_mode == "use":
+            # meta (a progress token, tracing fields) expects a wire request; fetch and replace the entry.
+            cache_mode = "refresh"
+        if cursor is not None:
+            # Continuation pages skip the cache, but an expired cursor means the listing changed (spec SHOULD evict).
+            try:
+                return await send()
+            except MCPError as e:
+                if e.code == INVALID_PARAMS:
+                    await cache.evict_method(method)
+                raise
+        if cache_mode == "use" and (hit := await cache.read(method, "")) is not None:
+            # The hit is a private deep copy, so absorption may mutate it freely.
+            served = cast(_CacheableT, hit)
+            return served if absorb is None else absorb(served)
+        gen = cache.capture(method, "")
+        result = await send()
+        await cache.write(method, "", result, gen, cache_mode)
+        return result
+
+    async def list_resources(
+        self,
+        *,
+        cursor: str | None = None,
+        meta: RequestParamsMeta | None = None,
+        cache_mode: CacheMode = "use",
+    ) -> ListResourcesResult:
+        """List available resources from the server."""
+        return await self._cached_fetch(
+            "resources/list",
+            cursor=cursor,
+            meta=meta,
+            cache_mode=cache_mode,
+            send=lambda: self.session.list_resources(params=PaginatedRequestParams(cursor=cursor, _meta=meta)),
+        )
+
+    async def list_resource_templates(
+        self,
+        *,
+        cursor: str | None = None,
+        meta: RequestParamsMeta | None = None,
+        cache_mode: CacheMode = "use",
+    ) -> ListResourceTemplatesResult:
+        """List available resource templates from the server."""
+        return await self._cached_fetch(
+            "resources/templates/list",
+            cursor=cursor,
+            meta=meta,
+            cache_mode=cache_mode,
+            send=lambda: self.session.list_resource_templates(params=PaginatedRequestParams(cursor=cursor, _meta=meta)),
+        )
+
+    async def read_resource(
+        self,
+        uri: str,
+        *,
+        input_responses: InputResponses | None = None,
+        request_state: str | None = None,
+        meta: RequestParamsMeta | None = None,
+        cache_mode: CacheMode = "use",
+    ) -> ReadResourceResult:
+        """Read a resource from the server.
+
+        If the server returns an `InputRequiredResult`, the embedded input
+        requests are dispatched to this client's sampling / elicitation / roots
+        callbacks and the read is retried automatically (up to
+        `input_required_max_rounds`).
+
+        Args:
+            uri: The URI of the resource to read.
+            input_responses: Responses to seed the first call with (e.g. when
+                resuming from a persisted `InputRequiredResult`).
+            request_state: Opaque state to seed the first call with.
+            meta: Additional metadata for the request.
+            cache_mode: Cache behavior for this call (see `CacheMode`); seeded
+                calls (`input_responses` or `request_state` set) ignore it.
+
+        Returns:
+            The resource content.
+
+        Raises:
+            InputRequiredRoundsExceededError: `input_required_max_rounds` exhausted.
+            MCPError: A callback returned `ErrorData` for an embedded input request.
+            pydantic.ValidationError: The server returned a result that does not
+                conform to the negotiated protocol version.
+        """
+
+        async def retry(r: InputResponses | None, s: str | None) -> ReadResourceResult | InputRequiredResult:
+            return await self.session.read_resource(
+                uri, input_responses=r, request_state=s, meta=meta, allow_input_required=True
+            )
+
+        # Seeded calls resume a specific exchange and must never be cached (spec MUST).
+        seeded = input_responses is not None or request_state is not None
+        cache = None if seeded else self._response_cache
+        if cache is None or cache_mode == "bypass":
+            return await self._drive_input_required(await retry(input_responses, request_state), retry)
+        # A closed (or never-entered) client must raise, never serve cached entries.
+        _ = self.session
+        if meta is not None and cache_mode == "use":
+            # Calls carrying meta always reach the server (mirrors `_cached_fetch`).
+            cache_mode = "refresh"
+        if cache_mode == "use" and (hit := await cache.read("resources/read", uri)) is not None:
+            # Only terminal first-round results are stored, so a hit legitimately skips the driver.
+            return cast(ReadResourceResult, hit)
+        gen = cache.capture("resources/read", uri)
+        first = await retry(None, None)
+        if not isinstance(first, InputRequiredResult):
+            await cache.write("resources/read", uri, first, gen, cache_mode)
+        elif cache_mode == "refresh":
+            # The refresh superseded whatever was cached, but an input_required resolution
+            # cannot be stored: purge the warm entry so it cannot be served again.
+            await cache.evict_key("resources/read", uri)
+        # Driver rounds carry inputResponses, so a terminal result reached through them is never cached (spec MUST).
+        return await self._drive_input_required(first, retry)
+
+    def listen(
+        self,
+        *,
+        tools_list_changed: bool = False,
+        prompts_list_changed: bool = False,
+        resources_list_changed: bool = False,
+        resource_subscriptions: Sequence[str] = (),
+    ) -> AbstractAsyncContextManager[Subscription]:
+        """Open a `subscriptions/listen` stream of typed change events (2026-07-28 only).
+
+        Keyword args mirror the wire `SubscriptionFilter`; entering waits for the ack (honored subset: `sub.honored`):
+
+            async with client.listen(tools_list_changed=True) as sub:
+                async for event in sub:
+                    tools = await client.list_tools()  # refetch on change
+
+        A graceful close ends the loop; an abrupt drop raises `SubscriptionLost`. No replay: re-listen and refetch.
+
+        Raises:
+            ListenNotSupportedError: The negotiated protocol version predates 2026-07-28.
+            MCPError: The server rejected the request or the connection failed first.
+            SubscriptionLost: The stream ended before it was acknowledged.
+            TimeoutError: The read timeout elapsed before the acknowledgment.
+        """
+        return _listen(
+            self.session,
+            tools_list_changed=tools_list_changed,
+            prompts_list_changed=prompts_list_changed,
+            resources_list_changed=resources_list_changed,
+            resource_subscriptions=resource_subscriptions,
+            on_event=self._evict_for_listen_event if self._response_cache is not None else None,
+        )
+
+    async def _evict_for_listen_event(self, event: ServerEvent) -> None:
+        """Finish response-cache eviction before a listen consumer can refetch.
+
+        Without it the iterator wakes first and refetches a still-warm entry, with no
+        corrective wake (events are deduplicated level triggers). The tee path repeats
+        the eviction; deliberate: idempotent, and it covers non-iterating consumers.
+        """
+        cache = self._response_cache
+        assert cache is not None  # installed as the event barrier only when a cache exists
+        try:
+            await cache.evict_for_notification(event_to_notification(event, {}))
+        except Exception:  # boundary: eviction reaches user store code; a cache fault must not block delivery
+            logger.exception("Response cache eviction failed; the event is still delivered")
+
+    @deprecated(
+        "resources/subscribe is removed as of 2026-07-28; use Client.listen() instead.",
+        category=MCPDeprecationWarning,
+    )
+    async def subscribe_resource(self, uri: str, *, meta: RequestParamsMeta | None = None) -> EmptyResult:
+        """Subscribe to resource updates (2025-era servers only)."""
+        return await self.session.subscribe_resource(uri, meta=meta)  # pyright: ignore[reportDeprecated]
+
+    @deprecated(
+        "resources/unsubscribe is removed as of 2026-07-28; use Client.listen() instead.",
+        category=MCPDeprecationWarning,
+    )
+    async def unsubscribe_resource(self, uri: str, *, meta: RequestParamsMeta | None = None) -> EmptyResult:
+        """Unsubscribe from resource updates (2025-era servers only)."""
+        return await self.session.unsubscribe_resource(uri, meta=meta)  # pyright: ignore[reportDeprecated]
+
+    async def call_tool(
+        self,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        read_timeout_seconds: float | None = None,
+        progress_callback: ProgressFnT | None = None,
+        *,
+        input_responses: InputResponses | None = None,
+        request_state: str | None = None,
+        meta: RequestParamsMeta | None = None,
+    ) -> CallToolResult:
+        """Call a tool on the server.
+
+        If the server returns an `InputRequiredResult`, the embedded input
+        requests are dispatched to this client's sampling / elicitation / roots
+        callbacks and the call is retried automatically (up to
+        `input_required_max_rounds`). To drive the loop yourself — e.g. to
+        persist `request_state` across process restarts — use
+        `client.session.call_tool(..., allow_input_required=True)`. Persisted
+        state is still subject to the server's TTL, request binding, and key
+        lifetime; a server on the default process-local key rejects it after a restart.
+
+        Result shapes claimed by this client's `extensions` are finished by the
+        owning claim's resolver, whose `CallToolResult` is returned; resolver
+        exceptions propagate as-is. To receive the claimed shape yourself, use
+        `client.session.call_tool(..., allow_claimed=True)`.
+
+        Args:
+            name: The name of the tool to call.
+            arguments: Arguments to pass to the tool.
+            read_timeout_seconds: Timeout for each underlying `tools/call` round.
+            progress_callback: Callback for progress updates.
+            input_responses: Responses to seed the first call with (e.g. when
+                resuming from a persisted `InputRequiredResult`).
+            request_state: Opaque state to seed the first call with.
+            meta: Additional metadata for the request.
+
+        Returns:
+            The tool result.
+
+        Raises:
+            InputRequiredRoundsExceededError: `input_required_max_rounds` exhausted.
+            MCPError: A callback returned `ErrorData` for an embedded input request.
+            pydantic.ValidationError: The server returned a result that does not
+                conform to the negotiated protocol version.
+        """
+
+        async def retry(r: InputResponses | None, s: str | None) -> CallToolResult | InputRequiredResult | Result:
+            return await self.session.call_tool(
+                name,
+                arguments,
+                read_timeout_seconds=read_timeout_seconds,
+                progress_callback=progress_callback,
+                input_responses=r,
+                request_state=s,
+                meta=meta,
+                allow_input_required=True,
+                # Input rounds resolve before a claimed result, so a claim may end any round.
+                allow_claimed=True,
+            )
+
+        result = await self._drive_input_required(await retry(input_responses, request_state), retry)
+        if isinstance(result, CallToolResult):
+            return result
+        # Only claimed shapes reach this point, so the lookup is total.
+        claim = self._folded_extensions.by_model[type(result)]
+        final = await claim.resolve(
+            result,
+            ClaimContext(session=self.session, tool_name=name, read_timeout_seconds=read_timeout_seconds),
+        )
+        if not final.is_error:
+            # Match the direct path: revalidate the output schema, but never for isError results.
+            await self.session.validate_tool_result(name, final)
+        return final
+
+    async def list_prompts(
+        self,
+        *,
+        cursor: str | None = None,
+        meta: RequestParamsMeta | None = None,
+        cache_mode: CacheMode = "use",
+    ) -> ListPromptsResult:
+        """List available prompts from the server."""
+        return await self._cached_fetch(
+            "prompts/list",
+            cursor=cursor,
+            meta=meta,
+            cache_mode=cache_mode,
+            send=lambda: self.session.list_prompts(params=PaginatedRequestParams(cursor=cursor, _meta=meta)),
+        )
+
+    async def get_prompt(
+        self,
+        name: str,
+        arguments: dict[str, str] | None = None,
+        *,
+        input_responses: InputResponses | None = None,
+        request_state: str | None = None,
+        meta: RequestParamsMeta | None = None,
+    ) -> GetPromptResult:
+        """Get a prompt from the server.
+
+        If the server returns an `InputRequiredResult`, the embedded input
+        requests are dispatched to this client's sampling / elicitation / roots
+        callbacks and the get is retried automatically (up to
+        `input_required_max_rounds`).
+
+        Args:
+            name: The name of the prompt.
+            arguments: Arguments to pass to the prompt.
+            input_responses: Responses to seed the first call with (e.g. when
+                resuming from a persisted `InputRequiredResult`).
+            request_state: Opaque state to seed the first call with.
+            meta: Additional metadata for the request.
+
+        Returns:
+            The prompt content.
+
+        Raises:
+            InputRequiredRoundsExceededError: `input_required_max_rounds` exhausted.
+            MCPError: A callback returned `ErrorData` for an embedded input request.
+            pydantic.ValidationError: The server returned a result that does not
+                conform to the negotiated protocol version.
+        """
+
+        async def retry(r: InputResponses | None, s: str | None) -> GetPromptResult | InputRequiredResult:
+            return await self.session.get_prompt(
+                name, arguments, input_responses=r, request_state=s, meta=meta, allow_input_required=True
+            )
+
+        return await self._drive_input_required(await retry(input_responses, request_state), retry)
+
+    async def _drive_input_required(
+        self,
+        first: _ResultT | InputRequiredResult,
+        retry: Callable[[InputResponses | None, str | None], Awaitable[_ResultT | InputRequiredResult]],
+    ) -> _ResultT:
+        """Hand an `InputRequiredResult` to the SEP-2322 driver, or pass a terminal result through.
+
+        `dispatch` routes each embedded request through the same callback table
+        that serves legacy server→client RPCs, so the two paths stay
+        behaviourally identical by construction.
+        """
+        if not isinstance(first, InputRequiredResult):
+            return first
+        session = self.session
+
+        async def dispatch(key: str, req: InputRequest) -> InputResponse | ErrorData:
+            ctx = ClientRequestContext(session=session, request_id=key, meta=req.params.meta if req.params else None)
+            return await session.dispatch_input_request(ctx, req)
+
+        return await run_input_required_driver(
+            first, dispatch=dispatch, retry=retry, max_rounds=self.input_required_max_rounds
+        )
+
+    async def complete(
+        self,
+        ref: ResourceTemplateReference | PromptReference,
+        argument: dict[str, str],
+        context_arguments: dict[str, str] | None = None,
+    ) -> CompleteResult:
+        """Get completions for a prompt or resource template argument.
+
+        Args:
+            ref: Reference to the prompt or resource template
+            argument: The argument to complete
+            context_arguments: Additional context arguments
+
+        Returns:
+            Completion suggestions.
+        """
+        return await self.session.complete(ref=ref, argument=argument, context_arguments=context_arguments)
+
+    async def list_tools(
+        self,
+        *,
+        cursor: str | None = None,
+        meta: RequestParamsMeta | None = None,
+        cache_mode: CacheMode = "use",
+    ) -> ListToolsResult:
+        """List available tools from the server."""
+        return await self._cached_fetch(
+            "tools/list",
+            cursor=cursor,
+            meta=meta,
+            cache_mode=cache_mode,
+            send=lambda: self.session.list_tools(params=PaginatedRequestParams(cursor=cursor, _meta=meta)),
+            # A cache hit skips session.list_tools, so the session re-absorbs the served
+            # listing to rebuild its derived per-tool state. Hits are cursorless, but a
+            # cached page 1 can carry next_cursor - never prune on a partial listing.
+            absorb=lambda hit: self.session._absorb_tool_listing(  # pyright: ignore[reportPrivateUsage]
+                hit, complete=hit.next_cursor is None
+            ),
+        )
+
+    @deprecated("The roots capability is deprecated as of 2026-07-28 (SEP-2577).", category=MCPDeprecationWarning)
+    async def send_roots_list_changed(self) -> None:
+        """Send a notification that the roots list has changed."""
+        # TODO(Marcelo): Currently, there is no way for the server to handle this. We should add support.
+        await self.session.send_roots_list_changed()  # pyright: ignore[reportDeprecated]

.mcp-venv/lib/python3.13/site-packages/mcp/client/context.py

@@ -0,0 +1,5 @@
+"""Request context for MCP client handlers."""
+
+from mcp.client.session import ClientRequestContext
+
+__all__ = ["ClientRequestContext"]

.mcp-venv/lib/python3.13/site-packages/mcp/client/extension.py

@@ -0,0 +1,196 @@
+"""Opt-in extension interface for MCP clients.
+
+Subclass `ClientExtension`, set `identifier`, override the hooks you need, and
+pass instances to `Client(extensions=[...])`. For an identifier-only
+capability ad, use `advertise()`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Sequence
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Final, Generic, Literal, TypeVar, get_args
+
+from mcp_types import CORE_RESULT_TYPES, CallToolResult, InputRequiredResult, Result
+from mcp_types.version import MODERN_PROTOCOL_VERSIONS
+from pydantic import AliasChoices, AliasPath, BaseModel
+from pydantic.fields import FieldInfo
+
+from mcp.shared.extension import validate_extension_identifier
+
+if TYPE_CHECKING:
+    from mcp.client.session import ClientSession
+
+__all__ = [
+    "ClaimContext",
+    "ClientExtension",
+    "NotificationBinding",
+    "ResultClaim",
+    "UnexpectedClaimedResult",
+    "advertise",
+]
+
+_CLAIM_METHODS: Final[frozenset[str]] = frozenset({"tools/call"})
+"""The closed set of verbs a claim may attach to; widen together with the `method` Literal."""
+
+_RESERVED_WIRE_ALIASES: Final[frozenset[str]] = frozenset({"requestState", "inputRequests"})
+"""Typed optional fields of the core result surface that pre-validates every inbound result."""
+
+
+def _wire_keys(name: str, field: FieldInfo) -> frozenset[str]:
+    """Every top-level wire key this field can read from or write to."""
+    keys = {field.alias or name}
+    if field.serialization_alias:
+        keys.add(field.serialization_alias)
+    validation_alias = field.validation_alias
+    choices = validation_alias.choices if isinstance(validation_alias, AliasChoices) else [validation_alias]
+    for choice in choices:
+        if isinstance(choice, AliasPath):
+            choice = choice.path[0]
+        if isinstance(choice, str):
+            keys.add(choice)
+    return frozenset(keys)
+
+
+ClaimedT = TypeVar("ClaimedT", bound=Result)
+NotifyParamsT = TypeVar("NotifyParamsT", bound=BaseModel)
+
+
+@dataclass(frozen=True, kw_only=True)
+class ClaimContext:
+    """Host-injected context for one `ResultClaim.resolve` call."""
+
+    session: ClientSession
+    tool_name: str
+    read_timeout_seconds: float | None
+
+
+@dataclass(frozen=True, kw_only=True)
+class ResultClaim(Generic[ClaimedT]):
+    """One extra result shape on one spec verb, keyed by the wire `resultType`.
+
+    Active only while the declaring extension is constructed into the client and
+    the negotiated protocol version admits it. `resolve` finishes a claimed
+    result, may send follow-ups through `ctx.session`, and must return the
+    verb's ordinary result. All field constraints are enforced at construction.
+    """
+
+    result_type: str
+    model: type[ClaimedT]
+    resolve: Callable[[ClaimedT, ClaimContext], Awaitable[CallToolResult]]
+    method: Literal["tools/call"] = "tools/call"
+    protocol_versions: frozenset[str] | None = None
+
+    def __post_init__(self) -> None:
+        if self.method not in _CLAIM_METHODS:
+            raise ValueError(f"claims attach to {sorted(_CLAIM_METHODS)} only; got method {self.method!r}")
+        if self.result_type in CORE_RESULT_TYPES:
+            raise ValueError(f"resultType {self.result_type!r} is core protocol vocabulary")
+        if Result not in self.model.__mro__:  # runtime guard; the ClaimedT bound only constrains checked callers
+            raise ValueError(f"{self.model.__name__} must subclass mcp_types.Result")
+        if issubclass(self.model, CallToolResult | InputRequiredResult):
+            raise ValueError("claim models must not subclass core result types")
+        for name, model_field in self.model.model_fields.items():
+            for clash in sorted(_wire_keys(name, model_field) & _RESERVED_WIRE_ALIASES):
+                raise ValueError(
+                    f"{self.model.__name__}.{name} aliases {clash!r}, a typed field of the core "
+                    "result surface; a colliding value would fail core validation before the "
+                    "claim adapter runs"
+                )
+        field = self.model.model_fields.get("result_type")
+        if field is None or get_args(field.annotation) != (self.result_type,):
+            raise ValueError(f"{self.model.__name__}.result_type must be Literal[{self.result_type!r}]")
+        if self.protocol_versions is not None and not self.protocol_versions:
+            raise ValueError("empty protocol_versions could never activate; use None for all")
+        if self.protocol_versions is not None and not self.protocol_versions.issubset(MODERN_PROTOCOL_VERSIONS):
+            unrecognized = sorted(self.protocol_versions.difference(MODERN_PROTOCOL_VERSIONS))
+            raise ValueError(
+                f"protocol_versions {unrecognized} are not modern protocol revisions; claimed shapes "
+                "cannot be delivered on a legacy wire (None means every modern version)"
+            )
+
+
+class UnexpectedClaimedResult(RuntimeError):
+    """A claimed (extension) result arrived on a `call_tool` that did not opt in.
+
+    The parsed value is carried as `result`; the server may already hold state it
+    references. Opt in via `Client(extensions=[...])` or `allow_claimed=True`.
+    """
+
+    def __init__(self, result: Result) -> None:
+        super().__init__(
+            f"Server returned a claimed result ({type(result).__name__}); pass the owning extension to "
+            "Client(extensions=[...]) for transparent resolution, or call with allow_claimed=True "
+            "and handle the shape. The carried result may reference server-side state needing cleanup."
+        )
+        self.result = result
+
+
+@dataclass(frozen=True, kw_only=True)
+class NotificationBinding(Generic[NotifyParamsT]):
+    """Deliver server notifications for `method` (the bare wire name) to `handler`.
+
+    Observation-only: validated params arrive one at a time per binding, in
+    dispatch order, through a bounded queue that drops the oldest with a warning
+    on overflow. Stream transports dispatch each notification independently, so
+    near-simultaneous notifications may be dispatched out of wire order. Methods
+    the negotiated version's core tables handle are never delivered to bindings.
+    """
+
+    method: str
+    params_type: type[NotifyParamsT]
+    handler: Callable[[NotifyParamsT], Awaitable[None]]
+
+
+class ClientExtension:
+    """Base class for an opt-in client extension; override only what you need.
+
+    The surface is declarative, fixed at construction, and never receives the client.
+    """
+
+    #: Reverse-DNS extension identifier, advertised under `ClientCapabilities.extensions`.
+    identifier: str
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        # Per-instance identifiers (assigned in __init__) are validated at consumption instead.
+        if (identifier := cls.__dict__.get("identifier")) is not None:
+            validate_extension_identifier(identifier, owner=cls.__name__)
+
+    def settings(self) -> dict[str, Any]:
+        """Per-extension settings advertised at `ClientCapabilities.extensions[identifier]`.
+
+        Read once at `Client` construction. A claim-bearing extension is
+        advertised only at protocol versions where at least one of its claims
+        is active.
+        """
+        return {}
+
+    def claims(self) -> Sequence[ResultClaim[Any]]:
+        """Extra result shapes this extension claims, with their resolvers."""
+        return ()
+
+    def notifications(self) -> Sequence[NotificationBinding[Any]]:
+        """Server notifications this extension observes."""
+        return ()
+
+
+class _AdvertiseOnly(ClientExtension):
+    """Ad-only extension returned by `advertise()`."""
+
+    def __init__(self, identifier: str, settings: dict[str, Any]) -> None:
+        self.identifier = identifier
+        self._settings = settings
+
+    def settings(self) -> dict[str, Any]:
+        return self._settings
+
+
+def advertise(identifier: str, settings: dict[str, Any] | None = None) -> ClientExtension:
+    """Advertise an extension identifier (with optional settings) and nothing else.
+
+    Advertising an extension you do not implement asserts wire support you do
+    not have; for behavioral extensions construct the real extension instead.
+    """
+    validate_extension_identifier(identifier, owner="advertise")
+    return _AdvertiseOnly(identifier, {} if settings is None else settings)

.mcp-venv/lib/python3.13/site-packages/mcp/client/session.py

@@ -0,0 +1,1462 @@
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+from functools import reduce
+from operator import or_
+from types import TracebackType
+from typing import TYPE_CHECKING, Annotated, Any, Final, Literal, Protocol, TypeAlias, cast, overload
+
+import anyio
+import anyio.abc
+import anyio.lowlevel
+import mcp_types as types
+from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream
+from mcp_types import (
+    CLIENT_CAPABILITIES_META_KEY,
+    CLIENT_INFO_META_KEY,
+    CONNECTION_CLOSED,
+    INTERNAL_ERROR,
+    LOG_LEVEL_META_KEY,
+    METHOD_NOT_FOUND,
+    PROTOCOL_VERSION_META_KEY,
+    SERVER_INFO_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, Discriminator, Tag, TypeAdapter, ValidationError
+from typing_extensions import Self, TypeVar, deprecated
+
+from mcp.client._transport import ReadStream, WriteStream
+from mcp.client.extension import NotificationBinding, ResultClaim, UnexpectedClaimedResult
+from mcp.client.subscriptions import ListenRoute
+from mcp.shared._compat import resync_tracer
+from mcp.shared.dispatcher import CallOptions, DispatchContext, Dispatcher, ProgressFnT, as_request_id
+from mcp.shared.exceptions import MCPDeprecationWarning, MCPError
+from mcp.shared.inbound import (
+    MCP_METHOD_HEADER,
+    MCP_NAME_HEADER,
+    MCP_PROTOCOL_VERSION_HEADER,
+    NAME_BEARING_METHODS,
+    encode_header_value,
+    find_invalid_x_mcp_header,
+    mcp_param_headers,
+    x_mcp_header_map,
+)
+from mcp.shared.jsonrpc_dispatcher import JSONRPCDispatcher, cancelled_request_id_from_params
+from mcp.shared.message import ClientMessageMetadata, SessionMessage
+from mcp.shared.subscriptions import SUBSCRIPTION_ID_META_KEY, event_from_wire
+from mcp.shared.transport_context import TransportContext
+
+if TYPE_CHECKING:
+    # `jsonschema` is imported lazily inside `validate_tool_result`: pulling it (and its
+    # `attrs`/`referencing` tree) in at module scope costs every client that never validates.
+    from jsonschema.protocols import Validator
+
+DEFAULT_CLIENT_INFO = types.Implementation(name="mcp", version="0.1.0")
+DISCOVER_TIMEOUT_SECONDS = 10.0
+_NOTIFICATION_QUEUE_SIZE: Final = 256
+
+logger = logging.getLogger("client")
+
+
+def _clamp_inbound_ttl(raw: dict[str, Any]) -> None:
+    """Floor a negative inbound `ttlMs` to 0 before `ge=0` validation fails the call (2026-07-28 caching SHOULD)."""
+    ttl = raw.get("ttlMs")
+    if isinstance(ttl, int | float) and not isinstance(ttl, bool) and ttl < 0:
+        raw["ttlMs"] = 0
+
+
+def _same_schema(a: dict[str, Any] | None, b: dict[str, Any] | None) -> bool:
+    """JSON equality for two output schemas.
+
+    Python `==` is not JSON equality: it conflates `True`/`1` and `False`/`0`, which JSON
+    Schema keeps distinct (`const: true` vs `const: 1`). Canonical serialization compares as
+    JSON does; where it is stricter (`1` vs `1.0`), erring toward "changed" only costs a
+    recompile, never a stale validator.
+    """
+    return json.dumps(a, sort_keys=True) == json.dumps(b, sort_keys=True)
+
+
+def _preconnect_stamp(data: dict[str, Any], opts: CallOptions) -> None:
+    # initialize/discover forbid cancellation; other pre-handshake requests (lowlevel
+    # ClientSession callers may skip the handshake entirely) keep the courtesy cancel.
+    if data["method"] in ("initialize", "server/discover"):
+        opts["cancel_on_abandon"] = False
+
+
+def _parse_server_info_stamp(result: types.DiscoverResult) -> types.Implementation | None:
+    """The typed identity from a discover result's `_meta` serverInfo stamp.
+
+    The stamp is display-only per the spec, so absent and malformed both read
+    as `None` rather than failing the connection.
+    """
+    raw = (result.meta or {}).get(SERVER_INFO_META_KEY)
+    if raw is None:
+        return None
+    try:
+        return types.Implementation.model_validate(raw)
+    except ValidationError:
+        return None
+
+
+def _make_handshake_stamp(protocol_version: str) -> Callable[[dict[str, Any], CallOptions], None]:
+    def stamp(data: dict[str, Any], opts: CallOptions) -> None:
+        opts.setdefault("headers", {})[MCP_PROTOCOL_VERSION_HEADER] = protocol_version
+
+    return stamp
+
+
+def _make_modern_stamp(
+    protocol_version: str,
+    client_info: dict[str, Any],
+    capabilities: dict[str, Any],
+    resolve_param_headers: Callable[[str, Mapping[str, Any]], dict[str, str]],
+    *,
+    log_level: types.LoggingLevel | None = None,
+) -> Callable[[dict[str, Any], CallOptions], None]:
+    def stamp(data: dict[str, Any], opts: CallOptions) -> None:
+        params = data.setdefault("params", {})
+        meta = params.setdefault("_meta", {})
+        meta[PROTOCOL_VERSION_META_KEY] = protocol_version
+        meta[CLIENT_INFO_META_KEY] = client_info
+        meta[CLIENT_CAPABILITIES_META_KEY] = capabilities
+        # The per-request log-delivery opt-in (2026 logging is opt-in per
+        # request). A default the caller can override on any single call by
+        # supplying the key in that request's `_meta`, hence setdefault.
+        if log_level is not None:
+            meta.setdefault(LOG_LEVEL_META_KEY, log_level)
+        # `cancel_on_abandon` stays at the dispatcher default (True): the
+        # courtesy `notifications/cancelled` is the abandon signal. On the
+        # stream transports it is the 2026 wire's cancellation spelling; the
+        # streamable-HTTP transport translates it into aborting the request's
+        # own POST instead of writing it (the 2026 HTTP wire has no
+        # client-to-server notifications - closing the stream is the signal).
+        # The negotiation methods still opt out, mirroring `_preconnect_stamp`:
+        # the spec forbids cancelling them.
+        if data["method"] in ("initialize", "server/discover"):
+            opts["cancel_on_abandon"] = False
+        headers = opts.setdefault("headers", {})
+        headers[MCP_PROTOCOL_VERSION_HEADER] = protocol_version
+        headers[MCP_METHOD_HEADER] = data["method"]
+        name_key = NAME_BEARING_METHODS.get(data["method"])
+        if name_key is not None and isinstance(name := params.get(name_key), str):
+            headers[MCP_NAME_HEADER] = encode_header_value(name)
+        if data["method"] == "tools/call" and isinstance(name := params.get("name"), str):
+            headers.update(resolve_param_headers(name, params.get("arguments") or {}))
+
+    return stamp
+
+
+ReceiveResultT = TypeVar("ReceiveResultT", bound=BaseModel)
+
+
+@dataclass(kw_only=True)
+class ClientRequestContext:
+    """Context for a server-initiated request, passed to the sampling/elicitation/list-roots callbacks."""
+
+    session: ClientSession
+    request_id: RequestId
+    meta: RequestParamsMeta | None = None
+
+
+class SamplingFnT(Protocol):
+    async def __call__(
+        self,
+        context: ClientRequestContext,
+        params: types.CreateMessageRequestParams,
+    ) -> types.CreateMessageResult | types.CreateMessageResultWithTools | types.ErrorData: ...  # pragma: no branch
+
+
+class ElicitationFnT(Protocol):
+    async def __call__(
+        self,
+        context: ClientRequestContext,
+        params: types.ElicitRequestParams,
+    ) -> types.ElicitResult | types.ErrorData: ...  # pragma: no branch
+
+
+class ListRootsFnT(Protocol):
+    async def __call__(
+        self, context: ClientRequestContext
+    ) -> types.ListRootsResult | types.ErrorData: ...  # pragma: no branch
+
+
+class LoggingFnT(Protocol):
+    async def __call__(self, params: types.LoggingMessageNotificationParams) -> None: ...  # pragma: no branch
+
+
+IncomingMessage: TypeAlias = types.ServerNotification | Exception
+"""What `message_handler` receives: the server notifications the session surfaces, plus transport-level exceptions.
+
+`notifications/cancelled` is applied by the dispatcher and never surfaced, and a
+`notifications/subscriptions/acknowledged` for a live `listen()` stream is consumed by that
+stream, so neither reaches the handler.
+"""
+
+
+class MessageHandlerFnT(Protocol):
+    async def __call__(self, message: IncomingMessage) -> None: ...  # pragma: no branch
+
+
+async def _default_message_handler(message: IncomingMessage) -> None:
+    await anyio.lowlevel.checkpoint()
+
+
+async def _default_sampling_callback(
+    context: ClientRequestContext,
+    params: types.CreateMessageRequestParams,
+) -> types.CreateMessageResult | types.CreateMessageResultWithTools | types.ErrorData:
+    return types.ErrorData(
+        code=types.INVALID_REQUEST,
+        message="Sampling not supported",
+    )
+
+
+async def _default_elicitation_callback(
+    context: ClientRequestContext,
+    params: types.ElicitRequestParams,
+) -> types.ElicitResult | types.ErrorData:
+    return types.ErrorData(
+        code=types.INVALID_REQUEST,
+        message="Elicitation not supported",
+    )
+
+
+async def _default_list_roots_callback(
+    context: ClientRequestContext,
+) -> types.ListRootsResult | types.ErrorData:
+    return types.ErrorData(
+        code=types.INVALID_REQUEST,
+        message="List roots not supported",
+    )
+
+
+async def _default_logging_callback(
+    params: types.LoggingMessageNotificationParams,
+) -> None:
+    pass
+
+
+ClientResponse: TypeAdapter[types.ClientResult | types.ErrorData] = TypeAdapter(types.ClientResult | types.ErrorData)
+
+# Typed against the wide parse union so adopt-built claim adapters share this attribute type.
+_CallToolResultAdapter: TypeAdapter[types.CallToolResult | types.InputRequiredResult | types.Result] = TypeAdapter(
+    types.CallToolResult | types.InputRequiredResult
+)
+_GetPromptResultAdapter: TypeAdapter[types.GetPromptResult | types.InputRequiredResult] = TypeAdapter(
+    types.GetPromptResult | types.InputRequiredResult
+)
+_ReadResourceResultAdapter: TypeAdapter[types.ReadResourceResult | types.InputRequiredResult] = TypeAdapter(
+    types.ReadResourceResult | types.InputRequiredResult
+)
+
+
+def _claim_active(claim: ResultClaim[Any], version: str) -> bool:
+    """A claim is active at modern versions only, narrowed by its optional version subset."""
+    return version in MODERN_PROTOCOL_VERSIONS and (
+        claim.protocol_versions is None or version in claim.protocol_versions
+    )
+
+
+def _active_claims_at(
+    claims_by_extension: Mapping[str, tuple[ResultClaim[Any], ...]], version: str
+) -> dict[str, ResultClaim[Any]]:
+    """Claims active at `version`, keyed by wire tag; empty at any legacy version."""
+    return {
+        claim.result_type: claim
+        for claims in claims_by_extension.values()
+        for claim in claims
+        if _claim_active(claim, version)
+    }
+
+
+def _build_call_tool_adapter(
+    active: Mapping[str, ResultClaim[Any]],
+) -> TypeAdapter[types.CallToolResult | types.InputRequiredResult | types.Result]:
+    """Build a discriminated tools/call adapter: a core arm plus one arm per active claim."""
+    if not active:
+        return _CallToolResultAdapter
+    tags = frozenset(active)
+    core_arm = "core"
+    while core_arm in tags:  # the routing sentinel must never collide with a claimed tag
+        core_arm += "-"
+
+    def _route(value: Any) -> str:
+        # pydantic hands the discriminator either the raw dict or an already-built model.
+        # Unknown or non-string tags route to the core arm and fail core validation there.
+        if isinstance(value, dict):
+            tag = cast("dict[str, Any]", value).get("resultType")
+        else:
+            tag = getattr(value, "result_type", None)
+        return tag if isinstance(tag, str) and tag in tags else core_arm
+
+    arms: list[Any] = [Annotated[types.CallToolResult | types.InputRequiredResult, Tag(core_arm)]]
+    arms += [Annotated[claim.model, Tag(tag)] for tag, claim in active.items()]
+    # reduce(or_) rather than Union star-unpack, which needs py3.11+.
+    return TypeAdapter(Annotated[reduce(or_, arms), Discriminator(_route)])
+
+
+def _index_claims(
+    result_claims: Mapping[str, Sequence[ResultClaim[Any]]] | None,
+    extensions: dict[str, dict[str, Any]] | None,
+) -> dict[str, tuple[ResultClaim[Any], ...]]:
+    """Validate and copy the claims-by-extension mapping."""
+    indexed: dict[str, tuple[ResultClaim[Any], ...]] = {}
+    seen: set[str] = set()
+    for identifier, claims in (result_claims or {}).items():
+        if extensions is None or identifier not in extensions:
+            raise ValueError(
+                f"result_claims key {identifier!r} has no extensions entry; a claim is only "
+                "advertised through its extension's capability ad"
+            )
+        if not claims:
+            raise ValueError(
+                f"result_claims[{identifier!r}] is empty and would drop the extension from "
+                "the capability ad at every version. Omit the key instead"
+            )
+        for claim in claims:
+            if claim.result_type in seen:
+                raise ValueError(f"duplicate result claim for resultType {claim.result_type!r}")
+            seen.add(claim.result_type)
+        indexed[identifier] = tuple(claims)
+    return indexed
+
+
+def _index_bindings(
+    notification_bindings: Sequence[NotificationBinding[Any]] | None,
+) -> dict[str, NotificationBinding[Any]]:
+    """Index bindings by wire method, rejecting duplicates."""
+    indexed: dict[str, NotificationBinding[Any]] = {}
+    for binding in notification_bindings or ():
+        if binding.method in indexed:
+            raise ValueError(f"duplicate notification binding for method {binding.method!r}")
+        indexed[binding.method] = binding
+    return indexed
+
+
+def _input_required_unexpected(method: str) -> RuntimeError:
+    return RuntimeError(
+        "Server returned InputRequiredResult; pass allow_input_required=True to receive it "
+        f"and retry {method}(..., input_responses=..., request_state=result.request_state)."
+    )
+
+
+class ClientSession:
+    """Client half of an MCP connection, running on a `Dispatcher`.
+
+    Construct it over a transport's stream pair (or pass a pre-built
+    `dispatcher=`), enter as an async context manager, then call
+    `initialize()`. The dispatcher owns the receive loop and request
+    correlation; this class owns the typed MCP layer and the constructor
+    callbacks. Transport `Exception` items reach `message_handler` on any
+    stream-backed dispatcher (`JSONRPCDispatcher`), whether built here from a
+    stream pair or supplied without a stream-exception hook of its own; an
+    in-process `DirectDispatcher` carries none.
+
+    Extension `result_claims` fold into tools/call parsing at `adopt()`;
+    `notification_bindings` observe vendor notifications via bounded FIFOs.
+    """
+
+    def __init__(
+        self,
+        read_stream: ReadStream[SessionMessage | Exception] | None = None,
+        write_stream: WriteStream[SessionMessage] | None = None,
+        read_timeout_seconds: float | None = None,
+        sampling_callback: SamplingFnT | None = None,
+        elicitation_callback: ElicitationFnT | None = None,
+        list_roots_callback: ListRootsFnT | None = None,
+        logging_callback: LoggingFnT | None = None,
+        message_handler: MessageHandlerFnT | None = None,
+        client_info: types.Implementation | None = None,
+        *,
+        log_level: types.LoggingLevel | None = None,
+        sampling_capabilities: types.SamplingCapability | None = None,
+        extensions: dict[str, dict[str, Any]] | None = None,
+        result_claims: Mapping[str, Sequence[ResultClaim[Any]]] | None = None,
+        notification_bindings: Sequence[NotificationBinding[Any]] | None = None,
+        dispatcher: Dispatcher[Any] | None = None,
+    ) -> None:
+        self._session_read_timeout_seconds = read_timeout_seconds
+        self._client_info = client_info or DEFAULT_CLIENT_INFO
+        self._sampling_callback = sampling_callback or _default_sampling_callback
+        self._sampling_capabilities = sampling_capabilities
+        self._extensions = dict(extensions) if extensions is not None else None
+        self._result_claims = _index_claims(result_claims, extensions)
+        self._notification_bindings = _index_bindings(notification_bindings)
+        self._active_claims: dict[str, ResultClaim[Any]] = {}
+        self._call_tool_adapter = _CallToolResultAdapter
+        self._binding_queues: dict[
+            str, tuple[MemoryObjectSendStream[BaseModel], MemoryObjectReceiveStream[BaseModel]]
+        ] = {}
+        self._elicitation_callback = elicitation_callback or _default_elicitation_callback
+        self._list_roots_callback = list_roots_callback or _default_list_roots_callback
+        self._logging_callback = logging_callback or _default_logging_callback
+        self._log_level: types.LoggingLevel | None = log_level
+        self._message_handler = message_handler or _default_message_handler
+        self._tool_output_schemas: dict[str, dict[str, Any] | None] = {}
+        # Compiled output-schema validators, derived from `_tool_output_schemas` and owned by
+        # `_absorb_tool_listing`, which evicts a tool's entry whenever its schema changes.
+        self._tool_output_validators: dict[str, Validator] = {}
+        self._x_mcp_header_maps: dict[str, dict[tuple[str, ...], str]] = {}
+        self._initialize_result: types.InitializeResult | None = None
+        self._discover_result: types.DiscoverResult | None = None
+        self._discover_server_info: types.Implementation | None = None
+        self._negotiated_version: str | None = None
+        self._stamp: Callable[[dict[str, Any], CallOptions], None] = _preconnect_stamp
+        self._task_group: anyio.abc.TaskGroup | None = None
+        # subscriptions/listen demux routes; membership decides ack consumption (raw listens are never registered)
+        self._listen_routes: dict[RequestId, ListenRoute] = {}
+        if dispatcher is not None:
+            if read_stream is not None or write_stream is not None:
+                raise ValueError("pass read_stream/write_stream or dispatcher, not both")
+            self._dispatcher: Dispatcher[Any] = dispatcher
+            if isinstance(dispatcher, JSONRPCDispatcher) and dispatcher.on_stream_exception is None:
+                # Route transport-level Exception items into message_handler — only
+                # stream-backed dispatchers carry these; DirectDispatcher has none.
+                # Don't clobber a caller-supplied hook.
+                # TODO(L78): this leaves a bound-method ref on the dispatcher after the
+                # session exits (memory pin) and a second wrap of the same dispatcher would
+                # skip install. The Transport-as-Dispatcher rework (L77) removes this seam.
+                dispatcher.on_stream_exception = self._on_stream_exception
+        else:
+            if read_stream is None or write_stream is None:
+                raise ValueError("read_stream and write_stream are required when no dispatcher is given")
+            # Built eagerly so notifications can be sent before entering the context manager.
+            self._dispatcher = JSONRPCDispatcher(
+                read_stream, write_stream, on_stream_exception=self._on_stream_exception
+            )
+
+    async def __aenter__(self) -> Self:
+        self._task_group = anyio.create_task_group()
+        await self._task_group.__aenter__()
+        try:
+            # Queues must exist before the dispatcher starts: _on_notify enqueues into this dict.
+            for binding in self._notification_bindings.values():
+                send, receive = anyio.create_memory_object_stream[BaseModel](_NOTIFICATION_QUEUE_SIZE)
+                self._binding_queues[binding.method] = (send, receive)
+            await self._task_group.start(
+                self._dispatcher.run, self._on_request, self._on_notify, self._intercept_notification
+            )
+            for binding in self._notification_bindings.values():
+                _, receive = self._binding_queues[binding.method]
+                self._task_group.start_soon(self._deliver_bound_notifications, binding, receive)
+        except BaseException:
+            # Unwind the entered task group before propagating: a cancellation
+            # landing here (e.g. `move_on_after` around connect) would abandon
+            # it and anyio would later raise "exited non-innermost cancel scope".
+            task_group = self._task_group
+            self._task_group = None
+            task_group.cancel_scope.cancel()
+            # Shield the group's own scope (a new one would break LIFO exit)
+            # so a pending outer cancellation cannot re-fire inside __aexit__.
+            task_group.cancel_scope.shield = True
+            try:
+                await task_group.__aexit__(None, None, None)
+            finally:
+                self._close_binding_queues()
+            raise
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> bool | None:
+        # Exit must not block: cancel the dispatcher, binding consumers, and in-flight callbacks.
+        assert self._task_group is not None
+        self._task_group.cancel_scope.cancel()
+        try:
+            result = await self._task_group.__aexit__(exc_type, exc_val, exc_tb)
+        finally:
+            self._close_binding_queues()
+            self._settle_listen_routes_closed()
+        await resync_tracer()
+        return result
+
+    def _close_binding_queues(self) -> None:
+        # Unclosed memory object streams warn at garbage collection; close is idempotent.
+        for send, receive in self._binding_queues.values():
+            send.close()
+            receive.close()
+        self._binding_queues.clear()
+
+    async def _deliver_bound_notifications(
+        self, binding: NotificationBinding[Any], receive: MemoryObjectReceiveStream[BaseModel]
+    ) -> None:
+        """Consume one binding's FIFO, decoupled from the dispatcher so handlers can do session I/O."""
+        while True:
+            params = await receive.receive()
+            try:
+                await binding.handler(params)
+            except Exception:
+                # A raising handler costs only that delivery, as in _on_notify.
+                logger.exception("notification binding handler for %r raised", binding.method)
+
+    async def send_request(
+        self,
+        request: types.ClientRequest | types.Request[Any, Any],
+        result_type: type[ReceiveResultT] | TypeAdapter[ReceiveResultT],
+        request_read_timeout_seconds: float | None = None,
+        metadata: ClientMessageMetadata | None = None,
+        progress_callback: ProgressFnT | None = None,
+    ) -> ReceiveResultT:
+        """Send a request and wait for its typed result.
+
+        Args:
+            metadata: Streamable HTTP resumption hints.
+
+        Raises:
+            MCPError: Error response, read timeout, or connection closed.
+            RuntimeError: Called before entering the context manager.
+            ValueError: The request declares `name_param` but its params carry no string name.
+            pydantic.ValidationError: The server returned a result that does not
+                conform to the negotiated protocol version.
+        """
+        data = request.model_dump(by_alias=True, mode="json", exclude_none=True)
+        method: str = data["method"]
+        opts: CallOptions = {}
+        self._stamp(data, opts)
+        # The stamp runs first, so its NAME_BEARING_METHODS rows win; a missing name fails loud.
+        headers = opts.setdefault("headers", {})
+        if (key := type(request).name_param) is not None and MCP_NAME_HEADER not in headers:
+            params_data: dict[str, Any] = data.get("params") or {}
+            name = params_data.get(key)
+            if not isinstance(name, str):
+                raise ValueError(f"{method} requires params[{key!r}] for Mcp-Name")
+            headers[MCP_NAME_HEADER] = encode_header_value(name)
+        timeout = (
+            request_read_timeout_seconds
+            if request_read_timeout_seconds is not None
+            else self._session_read_timeout_seconds
+        )
+        if timeout is not None:
+            opts["timeout"] = timeout
+        if progress_callback is not None:
+            opts["on_progress"] = progress_callback
+        if metadata is not None:
+            if metadata.resumption_token is not None:
+                opts["resumption_token"] = metadata.resumption_token
+            if metadata.on_resumption_token_update is not None:
+                opts["on_resumption_token"] = metadata.on_resumption_token_update
+        raw = await self._dispatcher.send_raw_request(method, data.get("params"), opts)
+        _clamp_inbound_ttl(raw)
+        # Literal fallback covers pre-handshake and stateless; matches runner.py.
+        version = self._negotiated_version or "2025-11-25"
+        try:
+            _methods.validate_server_result(method, version, raw)
+        except KeyError:
+            pass
+        if isinstance(result_type, TypeAdapter):
+            return result_type.validate_python(raw, by_name=False)
+        return result_type.model_validate(raw, by_name=False)
+
+    async def send_notification(self, notification: types.ClientNotification) -> None:
+        """Send a one-way notification. Usable before entering the context manager.
+
+        Fire-and-forget: after the connection has closed, the notification is
+        dropped with a debug log instead of raising.
+        """
+        data = notification.model_dump(by_alias=True, mode="json", exclude_none=True)
+        opts: CallOptions = {}
+        self._stamp(data, opts)
+        await self._dispatcher.notify(data["method"], data.get("params"), opts)
+
+    def _build_capabilities(self, version: str) -> types.ClientCapabilities:
+        """Build the capability ad for a wire speaking `version`.
+
+        Claim-bearing identifiers whose claims are all inactive at `version` drop, so
+        the client never advertises result shapes it would reject; claim-less
+        identifiers always advertise.
+        """
+        extensions = self._extensions
+        if extensions is not None and self._result_claims:
+            extensions = {
+                identifier: settings
+                for identifier, settings in extensions.items()
+                if identifier not in self._result_claims
+                or any(_claim_active(claim, version) for claim in self._result_claims[identifier])
+            } or None
+        sampling = (
+            (self._sampling_capabilities or types.SamplingCapability())
+            if self._sampling_callback is not _default_sampling_callback
+            else None
+        )
+        elicitation = (
+            types.ElicitationCapability(form=types.FormElicitationCapability(), url=types.UrlElicitationCapability())
+            if self._elicitation_callback is not _default_elicitation_callback
+            else None
+        )
+        roots = (
+            # TODO: Should this be based on whether we
+            # _will_ send notifications, or only whether
+            # they're supported?
+            types.RootsCapability(list_changed=True)
+            if self._list_roots_callback is not _default_list_roots_callback
+            else None
+        )
+        return types.ClientCapabilities(
+            sampling=sampling, elicitation=elicitation, experimental=None, extensions=extensions, roots=roots
+        )
+
+    async def initialize(self) -> types.InitializeResult:
+        if self._initialize_result is not None:
+            return self._initialize_result
+        result = await self.send_request(
+            types.InitializeRequest(
+                params=types.InitializeRequestParams(
+                    protocol_version=LATEST_HANDSHAKE_VERSION,
+                    # The handshake negotiates only legacy versions, where no claim is active.
+                    capabilities=self._build_capabilities(LATEST_HANDSHAKE_VERSION),
+                    client_info=self._client_info,
+                ),
+            ),
+            types.InitializeResult,
+        )
+
+        if result.protocol_version not in HANDSHAKE_PROTOCOL_VERSIONS:
+            raise RuntimeError(f"Unsupported protocol version from the server: {result.protocol_version}")
+
+        self.adopt(result)
+
+        await self.send_notification(types.InitializedNotification())
+
+        return result
+
+    def adopt(self, result: types.InitializeResult | types.DiscoverResult) -> None:
+        """Install negotiated state from a result the caller already holds (no wire traffic).
+
+        Clears the opposite slot, so at most one of `initialize_result` /
+        `discover_result` is ever non-None.
+
+        Raises:
+            RuntimeError: `result` is a `DiscoverResult` whose `supported_versions`
+                shares nothing with this client's `MODERN_PROTOCOL_VERSIONS`.
+        """
+        if isinstance(result, types.DiscoverResult):
+            # ordered oldest→newest via MODERN_PROTOCOL_VERSIONS
+            mutual = [v for v in MODERN_PROTOCOL_VERSIONS if v in result.supported_versions]
+            if not mutual:
+                raise RuntimeError(
+                    f"No mutually supported modern protocol version "
+                    f"(server: {result.supported_versions}, client: {list(MODERN_PROTOCOL_VERSIONS)})"
+                )
+            version = mutual[-1]
+            client_info = self._client_info.model_dump(by_alias=True, mode="json", exclude_none=True)
+            capabilities = self._build_capabilities(version).model_dump(by_alias=True, mode="json", exclude_none=True)
+            self._stamp = _make_modern_stamp(
+                version, client_info, capabilities, self._resolve_param_headers, log_level=self._log_level
+            )
+            self._discover_result = result
+            self._discover_server_info = _parse_server_info_stamp(result)
+            self._initialize_result = None
+        else:
+            version = result.protocol_version
+            self._stamp = _make_handshake_stamp(version)
+            self._initialize_result = result
+            self._discover_result = None
+            self._discover_server_info = None
+        self._negotiated_version = version
+        # Both arms reach here, so re-adoption resets cleanly; legacy versions activate no claims.
+        # Core-vocabulary tags are unconstructible (ResultClaim.__post_init__), so no exclusion needed.
+        self._active_claims = _active_claims_at(self._result_claims, version)
+        self._call_tool_adapter = _build_call_tool_adapter(self._active_claims)
+        for method in self._notification_bindings:
+            # Bindings are consulted only for methods core does not know, so this one can never fire.
+            if (method, version) in _methods.SERVER_NOTIFICATIONS:
+                logger.warning(
+                    "notification binding for %r will never fire at %s: the core protocol defines this method",
+                    method,
+                    version,
+                )
+
+    async def send_discover(self, version: str) -> dict[str, Any]:
+        """Send a single ``server/discover`` at ``version`` and return the raw result dict.
+
+        No retry, no ``adopt()``. The ``_meta`` envelope and the
+        ``Mcp-Protocol-Version`` header are stamped at ``version`` so the
+        server-side era router sees a coherent probe. Used by ``discover()`` and
+        the connect-time auto-negotiation policy.
+
+        Raises:
+            MCPError: The server returned a JSON-RPC error, or the transport
+                bounced the request at its own layer (a bare HTTP 4xx is
+                synthesized into a JSON-RPC error by the transport).
+        """
+        client_info = self._client_info.model_dump(by_alias=True, mode="json", exclude_none=True)
+        capabilities = self._build_capabilities(version).model_dump(by_alias=True, mode="json", exclude_none=True)
+        request = types.DiscoverRequest(
+            params=types.RequestParams(
+                _meta={
+                    PROTOCOL_VERSION_META_KEY: version,
+                    CLIENT_INFO_META_KEY: client_info,
+                    CLIENT_CAPABILITIES_META_KEY: capabilities,
+                }
+            )
+        )
+        data = request.model_dump(by_alias=True, mode="json", exclude_none=True)
+        opts: CallOptions = {
+            "timeout": DISCOVER_TIMEOUT_SECONDS,
+            "cancel_on_abandon": False,
+            "headers": {MCP_PROTOCOL_VERSION_HEADER: version, MCP_METHOD_HEADER: data["method"]},
+        }
+        raw = await self._dispatcher.send_raw_request(data["method"], data.get("params"), opts)
+        # Un-floored, a negative ttl fails the mode='auto' probe's validation and silently downgrades the handshake.
+        _clamp_inbound_ttl(raw)
+        return raw
+
+    async def discover(self) -> types.DiscoverResult:
+        """Probe `server/discover` and adopt the result.
+
+        Sends a single `server/discover` proposing the newest modern protocol
+        version. On `UNSUPPORTED_PROTOCOL_VERSION` (-32022) the server's
+        `supported` list is intersected with `MODERN_PROTOCOL_VERSIONS` and the
+        probe is retried once at the highest mutual version. Any other error —
+        including `METHOD_NOT_FOUND` (-32601) and `REQUEST_TIMEOUT` (-32001) —
+        propagates; the legacy `initialize()` fallback is the caller's policy.
+
+        Raises:
+            MCPError: The server rejected `server/discover`, the probe timed
+                out, or the -32022 retry found no mutual version / failed again.
+            RuntimeError: `adopt()` found no mutual version in the returned
+                `supported_versions`.
+        """
+        if self._discover_result is not None:
+            return self._discover_result
+
+        try:
+            raw = await self.send_discover(LATEST_MODERN_VERSION)
+        except MCPError as e:
+            if e.code != UNSUPPORTED_PROTOCOL_VERSION:
+                raise
+            try:
+                data = types.UnsupportedProtocolVersionErrorData.model_validate(e.error.data)
+            except ValidationError:
+                raise e from None
+            # ordered oldest→newest via MODERN_PROTOCOL_VERSIONS
+            mutual = [v for v in MODERN_PROTOCOL_VERSIONS if v in data.supported]
+            if not mutual:
+                raise
+            raw = await self.send_discover(mutual[-1])
+
+        result = types.DiscoverResult.model_validate(raw)
+        self.adopt(result)
+        return result
+
+    @property
+    def initialize_result(self) -> types.InitializeResult | None:
+        """The server's InitializeResult. None unless `initialize()` ran (or was adopted)."""
+        return self._initialize_result
+
+    @property
+    def discover_result(self) -> types.DiscoverResult | None:
+        """The server's DiscoverResult. None unless `discover()` ran (or was adopted).
+
+        Retained intact (supported_versions, ttl_ms, cache_scope) so callers
+        can round-trip it as ``prior_discover=``.
+        """
+        return self._discover_result
+
+    @property
+    def protocol_version(self) -> str | None:
+        """Negotiated protocol version. None until `initialize()`, `discover()`, or `adopt()`."""
+        return self._negotiated_version
+
+    @property
+    def server_info(self) -> types.Implementation | None:
+        """Server name/version. None until `initialize()`, `discover()`, or `adopt()`.
+
+        On 2026-era connections this is the discover result's optional `_meta`
+        `serverInfo` stamp, parsed once at adopt time; `None` when the server
+        did not identify itself. The stamp is display-only per the spec, so a
+        malformed value reads as absent rather than failing the connection.
+        """
+        if self._discover_result is not None:
+            return self._discover_server_info
+        if self._initialize_result is not None:
+            return self._initialize_result.server_info
+        return None
+
+    @property
+    def server_capabilities(self) -> types.ServerCapabilities | None:
+        """Server capabilities. None until `initialize()`, `discover()`, or `adopt()`."""
+        if self._discover_result is not None:
+            return self._discover_result.capabilities
+        if self._initialize_result is not None:
+            return self._initialize_result.capabilities
+        return None
+
+    @property
+    def instructions(self) -> str | None:
+        """Server-provided instructions text, if any."""
+        if self._discover_result is not None:
+            return self._discover_result.instructions
+        if self._initialize_result is not None:
+            return self._initialize_result.instructions
+        return None
+
+    async def send_ping(self, *, meta: RequestParamsMeta | None = None) -> types.EmptyResult:
+        """Send a ping request."""
+        return await self.send_request(types.PingRequest(params=types.RequestParams(_meta=meta)), types.EmptyResult)
+
+    @deprecated(
+        "Client-to-server progress is deprecated as of 2026-07-28; progress is server-to-client only.",
+        category=MCPDeprecationWarning,
+    )
+    async def send_progress_notification(
+        self,
+        progress_token: str | int,
+        progress: float,
+        total: float | None = None,
+        message: str | None = None,
+        *,
+        meta: RequestParamsMeta | None = None,
+    ) -> None:
+        """Send a progress notification."""
+        await self.send_notification(
+            types.ProgressNotification(
+                params=types.ProgressNotificationParams(
+                    progress_token=progress_token,
+                    progress=progress,
+                    total=total,
+                    message=message,
+                    _meta=meta,
+                ),
+            )
+        )
+
+    @deprecated("The logging capability is deprecated as of 2026-07-28 (SEP-2577).", category=MCPDeprecationWarning)
+    async def set_logging_level(
+        self,
+        level: types.LoggingLevel,
+        *,
+        meta: RequestParamsMeta | None = None,
+    ) -> types.EmptyResult:
+        """Send a logging/setLevel request."""
+        return await self.send_request(
+            types.SetLevelRequest(params=types.SetLevelRequestParams(level=level, _meta=meta)),
+            types.EmptyResult,
+        )
+
+    async def list_resources(self, *, params: types.PaginatedRequestParams | None = None) -> types.ListResourcesResult:
+        """Send a resources/list request.
+
+        Args:
+            params: Full pagination parameters including cursor and any future fields
+        """
+        return await self.send_request(types.ListResourcesRequest(params=params), types.ListResourcesResult)
+
+    async def list_resource_templates(
+        self, *, params: types.PaginatedRequestParams | None = None
+    ) -> types.ListResourceTemplatesResult:
+        """Send a resources/templates/list request.
+
+        Args:
+            params: Full pagination parameters including cursor and any future fields
+        """
+        return await self.send_request(
+            types.ListResourceTemplatesRequest(params=params),
+            types.ListResourceTemplatesResult,
+        )
+
+    @overload
+    async def read_resource(
+        self,
+        uri: str,
+        *,
+        input_responses: types.InputResponses | None = None,
+        request_state: str | None = None,
+        meta: RequestParamsMeta | None = None,
+        allow_input_required: Literal[False] = False,
+    ) -> types.ReadResourceResult: ...
+
+    @overload
+    async def read_resource(
+        self,
+        uri: str,
+        *,
+        input_responses: types.InputResponses | None = None,
+        request_state: str | None = None,
+        meta: RequestParamsMeta | None = None,
+        allow_input_required: bool,
+    ) -> types.ReadResourceResult | types.InputRequiredResult: ...
+
+    async def read_resource(
+        self,
+        uri: str,
+        *,
+        input_responses: types.InputResponses | None = None,
+        request_state: str | None = None,
+        meta: RequestParamsMeta | None = None,
+        allow_input_required: bool = False,
+    ) -> types.ReadResourceResult | types.InputRequiredResult:
+        """Send a resources/read request.
+
+        Args:
+            input_responses: Responses to a prior `InputRequiredResult.input_requests`.
+            request_state: Opaque state echoed from a prior `InputRequiredResult`.
+            allow_input_required: When `False` (default), an `InputRequiredResult`
+                from the server raises `RuntimeError`; when `True`, it is returned
+                so the caller can resolve the requests and retry.
+
+        Raises:
+            RuntimeError: If the server returns an `InputRequiredResult` and
+                `allow_input_required` is `False`.
+        """
+        result = await self.send_request(
+            types.ReadResourceRequest(
+                params=types.ReadResourceRequestParams(
+                    uri=uri,
+                    input_responses=input_responses,
+                    request_state=request_state,
+                    _meta=meta,
+                ),
+            ),
+            _ReadResourceResultAdapter,
+        )
+        if isinstance(result, types.InputRequiredResult) and not allow_input_required:
+            raise _input_required_unexpected("read_resource")
+        return result
+
+    @deprecated(
+        "resources/subscribe is removed as of 2026-07-28; use Client.listen() instead.",
+        category=MCPDeprecationWarning,
+    )
+    async def subscribe_resource(self, uri: str, *, meta: RequestParamsMeta | None = None) -> types.EmptyResult:
+        """Send a resources/subscribe request (2025-era servers only)."""
+        return await self.send_request(
+            types.SubscribeRequest(params=types.SubscribeRequestParams(uri=uri, _meta=meta)),
+            types.EmptyResult,
+        )
+
+    @deprecated(
+        "resources/unsubscribe is removed as of 2026-07-28; use Client.listen() instead.",
+        category=MCPDeprecationWarning,
+    )
+    async def unsubscribe_resource(self, uri: str, *, meta: RequestParamsMeta | None = None) -> types.EmptyResult:
+        """Send a resources/unsubscribe request (2025-era servers only)."""
+        return await self.send_request(
+            types.UnsubscribeRequest(params=types.UnsubscribeRequestParams(uri=uri, _meta=meta)),
+            types.EmptyResult,
+        )
+
+    @overload
+    async def call_tool(
+        self,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        read_timeout_seconds: float | None = None,
+        progress_callback: ProgressFnT | None = None,
+        *,
+        input_responses: types.InputResponses | None = None,
+        request_state: str | None = None,
+        meta: RequestParamsMeta | None = None,
+        allow_input_required: Literal[False] = False,
+        allow_claimed: Literal[False] = False,
+    ) -> types.CallToolResult: ...
+
+    @overload
+    async def call_tool(
+        self,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        read_timeout_seconds: float | None = None,
+        progress_callback: ProgressFnT | None = None,
+        *,
+        input_responses: types.InputResponses | None = None,
+        request_state: str | None = None,
+        meta: RequestParamsMeta | None = None,
+        allow_input_required: bool,
+        allow_claimed: Literal[False] = False,
+    ) -> types.CallToolResult | types.InputRequiredResult: ...
+
+    @overload
+    async def call_tool(
+        self,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        read_timeout_seconds: float | None = None,
+        progress_callback: ProgressFnT | None = None,
+        *,
+        input_responses: types.InputResponses | None = None,
+        request_state: str | None = None,
+        meta: RequestParamsMeta | None = None,
+        allow_input_required: Literal[False] = False,
+        allow_claimed: bool,
+    ) -> types.CallToolResult | types.Result: ...
+
+    @overload
+    async def call_tool(
+        self,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        read_timeout_seconds: float | None = None,
+        progress_callback: ProgressFnT | None = None,
+        *,
+        input_responses: types.InputResponses | None = None,
+        request_state: str | None = None,
+        meta: RequestParamsMeta | None = None,
+        allow_input_required: bool,
+        allow_claimed: bool,
+    ) -> types.CallToolResult | types.InputRequiredResult | types.Result: ...
+
+    async def call_tool(
+        self,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        read_timeout_seconds: float | None = None,
+        progress_callback: ProgressFnT | None = None,
+        *,
+        input_responses: types.InputResponses | None = None,
+        request_state: str | None = None,
+        meta: RequestParamsMeta | None = None,
+        allow_input_required: bool = False,
+        allow_claimed: bool = False,
+    ) -> types.CallToolResult | types.InputRequiredResult | types.Result:
+        """Send a tools/call request with optional progress callback support.
+
+        On a modern (2026-07-28) connection, arguments annotated with `x-mcp-header`
+        in the tool's input schema are mirrored into `Mcp-Param-*` request headers.
+        The annotations are read from the tool's last `list_tools` entry, so list
+        the tool before calling it to enable header emission.
+
+        Args:
+            input_responses: Responses to a prior `InputRequiredResult.input_requests`.
+            request_state: Opaque state echoed from a prior `InputRequiredResult`.
+            allow_input_required: When ``False`` (default), an `InputRequiredResult`
+                from the server raises `RuntimeError`; when ``True``, it is returned
+                so the caller can resolve the requests and retry.
+            allow_claimed: When `False` (default), a claimed extension result raises
+                `UnexpectedClaimedResult`; when `True`, the parsed claim model is returned.
+
+        Raises:
+            RuntimeError: If the server returns an `InputRequiredResult` and
+                ``allow_input_required`` is ``False``.
+            UnexpectedClaimedResult: Claimed result with `allow_claimed` False; carries the parsed value.
+        """
+        result = await self.send_request(
+            types.CallToolRequest(
+                params=types.CallToolRequestParams(
+                    name=name,
+                    arguments=arguments,
+                    input_responses=input_responses,
+                    request_state=request_state,
+                    _meta=meta,
+                ),
+            ),
+            self._call_tool_adapter,
+            request_read_timeout_seconds=read_timeout_seconds,
+            progress_callback=progress_callback,
+        )
+
+        if isinstance(result, types.CallToolResult) and not result.is_error:
+            await self.validate_tool_result(name, result)
+
+        # The input_required arm stays first; a claimed shape is terminal for the multi-round-trip driver.
+        if isinstance(result, types.InputRequiredResult) and not allow_input_required:
+            raise _input_required_unexpected("call_tool")
+        if not isinstance(result, types.CallToolResult | types.InputRequiredResult) and not allow_claimed:
+            raise UnexpectedClaimedResult(result)
+        return result
+
+    def _resolve_param_headers(self, name: str, arguments: Mapping[str, Any]) -> dict[str, str]:
+        """`Mcp-Param-*` headers for a `tools/call`, or empty when the tool was never listed."""
+        header_map = self._x_mcp_header_maps.get(name)
+        if header_map is None:
+            return {}
+        return mcp_param_headers(header_map, arguments)
+
+    async def validate_tool_result(self, name: str, result: types.CallToolResult) -> None:
+        """Revalidate a `CallToolResult` against the tool's declared output schema.
+
+        Raises:
+            RuntimeError: Structured content is missing or does not conform to the schema.
+        """
+        if name not in self._tool_output_schemas:
+            # refresh output schema cache
+            await self.list_tools()
+
+        output_schema = None
+        if name in self._tool_output_schemas:
+            output_schema = self._tool_output_schemas.get(name)
+        else:
+            logger.warning(f"Tool {name} not listed by server, cannot validate any structured content")
+
+        if output_schema is not None:
+            from jsonschema import exceptions as jsonschema_exceptions
+
+            if result.structured_content is None:
+                raise RuntimeError(f"Tool {name} has an output schema but did not return structured content")
+            validator = self._output_schema_validator(name, output_schema)
+            # `best_match` picks the same error the previous `jsonschema.validate()` call raised,
+            # so the message a caller sees is unchanged. It is untyped upstream.
+            errors = validator.iter_errors(result.structured_content)
+            error = cast(
+                "Exception | None",
+                jsonschema_exceptions.best_match(errors),  # pyright: ignore[reportUnknownMemberType]
+            )
+            if error is not None:
+                raise RuntimeError(f"Invalid structured content returned by tool {name}: {error}") from error
+
+    def _output_schema_validator(self, name: str, output_schema: dict[str, Any]) -> Validator:
+        """Compiled validator for the tool's cached output schema, built once per schema value.
+
+        Compiling is ~60x the cost of validating, so a one-shot `jsonschema.validate()` per
+        result dominates `call_tool`; the compiled validator is cached instead. It stays valid
+        because `_absorb_tool_listing` evicts a tool's validator whenever it absorbs a different
+        schema for that tool, so a cached entry always matches `output_schema`.
+
+        Raises:
+            RuntimeError: The schema is not a valid JSON Schema. Raised on every call, since a
+                failed compile is never cached.
+        """
+        from jsonschema import SchemaError
+        from jsonschema.validators import validator_for
+
+        if (validator := self._tool_output_validators.get(name)) is not None:
+            return validator
+
+        validator_cls = validator_for(output_schema)
+        try:
+            validator_cls.check_schema(output_schema)
+        except SchemaError as e:
+            raise RuntimeError(f"Invalid schema for tool {name}: {e}")
+        # jsonschema ships no `py.typed`, so pyright reads typeshed's stub, which declares
+        # `registry` as required (concrete validators default it); cast to a schema-only ctor.
+        validator = cast("Callable[[dict[str, Any]], Validator]", validator_cls)(output_schema)
+        self._tool_output_validators[name] = validator
+        return validator
+
+    async def list_prompts(self, *, params: types.PaginatedRequestParams | None = None) -> types.ListPromptsResult:
+        """Send a prompts/list request.
+
+        Args:
+            params: Full pagination parameters including cursor and any future fields
+        """
+        return await self.send_request(types.ListPromptsRequest(params=params), types.ListPromptsResult)
+
+    @overload
+    async def get_prompt(
+        self,
+        name: str,
+        arguments: dict[str, str] | None = None,
+        *,
+        input_responses: types.InputResponses | None = None,
+        request_state: str | None = None,
+        meta: RequestParamsMeta | None = None,
+        allow_input_required: Literal[False] = False,
+    ) -> types.GetPromptResult: ...
+
+    @overload
+    async def get_prompt(
+        self,
+        name: str,
+        arguments: dict[str, str] | None = None,
+        *,
+        input_responses: types.InputResponses | None = None,
+        request_state: str | None = None,
+        meta: RequestParamsMeta | None = None,
+        allow_input_required: bool,
+    ) -> types.GetPromptResult | types.InputRequiredResult: ...
+
+    async def get_prompt(
+        self,
+        name: str,
+        arguments: dict[str, str] | None = None,
+        *,
+        input_responses: types.InputResponses | None = None,
+        request_state: str | None = None,
+        meta: RequestParamsMeta | None = None,
+        allow_input_required: bool = False,
+    ) -> types.GetPromptResult | types.InputRequiredResult:
+        """Send a prompts/get request.
+
+        Args:
+            input_responses: Responses to a prior `InputRequiredResult.input_requests`.
+            request_state: Opaque state echoed from a prior `InputRequiredResult`.
+            allow_input_required: When `False` (default), an `InputRequiredResult`
+                from the server raises `RuntimeError`; when `True`, it is returned
+                so the caller can resolve the requests and retry.
+
+        Raises:
+            RuntimeError: If the server returns an `InputRequiredResult` and
+                `allow_input_required` is `False`.
+        """
+        result = await self.send_request(
+            types.GetPromptRequest(
+                params=types.GetPromptRequestParams(
+                    name=name,
+                    arguments=arguments,
+                    input_responses=input_responses,
+                    request_state=request_state,
+                    _meta=meta,
+                ),
+            ),
+            _GetPromptResultAdapter,
+        )
+        if isinstance(result, types.InputRequiredResult) and not allow_input_required:
+            raise _input_required_unexpected("get_prompt")
+        return result
+
+    async def complete(
+        self,
+        ref: types.ResourceTemplateReference | types.PromptReference,
+        argument: dict[str, str],
+        context_arguments: dict[str, str] | None = None,
+    ) -> types.CompleteResult:
+        """Send a completion/complete request."""
+        context = None
+        if context_arguments is not None:
+            context = types.CompletionContext(arguments=context_arguments)
+
+        return await self.send_request(
+            types.CompleteRequest(
+                params=types.CompleteRequestParams(
+                    ref=ref,
+                    argument=types.CompletionArgument(**argument),
+                    context=context,
+                ),
+            ),
+            types.CompleteResult,
+        )
+
+    async def list_tools(self, *, params: types.PaginatedRequestParams | None = None) -> types.ListToolsResult:
+        """Send a tools/list request.
+
+        Args:
+            params: Full pagination parameters including cursor and any future fields
+        """
+        result = await self.send_request(
+            types.ListToolsRequest(params=params),
+            types.ListToolsResult,
+        )
+        complete = (params is None or params.cursor is None) and result.next_cursor is None
+        return self._absorb_tool_listing(result, complete=complete)
+
+    def _absorb_tool_listing(self, result: types.ListToolsResult, *, complete: bool) -> types.ListToolsResult:
+        """Filter the listing per the 2026 x-mcp-header MUST and rebuild derived per-tool state, in place.
+
+        Idempotent: cached values are already post-filter, so the response cache can re-absorb a served listing.
+        `complete` (an uncursored single-page listing) prunes per-tool state down to the listing's tools.
+        """
+        if self._negotiated_version in MODERN_PROTOCOL_VERSIONS:
+            # 2026-07-28: clients MUST drop tools whose x-mcp-header annotations are invalid.
+            kept: list[types.Tool] = []
+            for tool in result.tools:
+                if (reason := find_invalid_x_mcp_header(tool.input_schema)) is not None:
+                    logger.warning("dropping tool %r: invalid x-mcp-header (%s)", tool.name, reason)
+                    # Evict any map cached from a prior valid listing so a stale entry can't
+                    # mirror headers for a tool this listing dropped.
+                    self._x_mcp_header_maps.pop(tool.name, None)
+                    continue
+                # Cache the arg→header map so a later tools/call mirrors it into Mcp-Param-* headers.
+                self._x_mcp_header_maps[tool.name] = x_mcp_header_map(tool.input_schema)
+                kept.append(tool)
+            result.tools = kept
+
+        # Cache tool output schemas for future validation; cursor pages only ever add. A
+        # changed schema evicts its compiled validator; an unchanged one (a re-listing, or the
+        # response cache re-absorbing a served hit) keeps it. Only validated tools pay the check.
+        for tool in result.tools:
+            if tool.name in self._tool_output_validators and not _same_schema(
+                self._tool_output_schemas.get(tool.name), tool.output_schema
+            ):
+                del self._tool_output_validators[tool.name]
+            self._tool_output_schemas[tool.name] = tool.output_schema
+
+        if complete:
+            # The listing is the full tool universe, so state for unlisted tools is stale
+            # (the server dropped them, or a shared-cache writer's filter did).
+            names = {tool.name for tool in result.tools}
+            self._x_mcp_header_maps = {k: v for k, v in self._x_mcp_header_maps.items() if k in names}
+            self._tool_output_schemas = {k: v for k, v in self._tool_output_schemas.items() if k in names}
+            self._tool_output_validators = {k: v for k, v in self._tool_output_validators.items() if k in names}
+
+        return result
+
+    @deprecated("The roots capability is deprecated as of 2026-07-28 (SEP-2577).", category=MCPDeprecationWarning)
+    async def send_roots_list_changed(self) -> None:
+        """Send a roots/list_changed notification."""
+        await self.send_notification(types.RootsListChangedNotification())
+
+    async def _on_request(
+        self, dctx: DispatchContext[TransportContext], method: str, params: Mapping[str, Any] | None
+    ) -> dict[str, Any]:
+        """Answer a server-initiated request via the registered callbacks."""
+        # Literal, not LATEST_PROTOCOL_VERSION: the fallback covers the initialize
+        # handshake (which only exists at <=2025) and stateless until the header
+        # is plumbed; its meaning is fixed regardless of LATEST bumps.
+        version = self._negotiated_version or "2025-11-25"
+        try:
+            request = cast(types.ServerRequest, _methods.parse_server_request(method, version, params))
+        except KeyError:
+            raise MCPError(code=METHOD_NOT_FOUND, message="Method not found", data=method) from None
+
+        response: types.ClientResult | types.ErrorData
+        if isinstance(request, types.PingRequest):
+            # Answered without a context: ping has no callback that would need one.
+            response = types.EmptyResult()
+        else:
+            assert dctx.request_id is not None  # the callback-driving dispatchers always assign ids
+            ctx = ClientRequestContext(
+                session=self, request_id=dctx.request_id, meta=request.params.meta if request.params else None
+            )
+            response = await self.dispatch_input_request(ctx, request)
+        client_response = ClientResponse.validate_python(response)
+        if isinstance(client_response, types.ErrorData):
+            raise MCPError.from_error_data(client_response)
+        dumped = client_response.model_dump(by_alias=True, mode="json", exclude_none=True)
+        try:
+            _methods.validate_client_result(method, version, dumped)
+        except ValidationError:
+            logger.exception("client callback for %r returned an invalid result", method)
+            raise MCPError(code=INTERNAL_ERROR, message="Client callback returned an invalid result") from None
+        return dumped
+
+    async def dispatch_input_request(
+        self, ctx: ClientRequestContext, request: types.InputRequest
+    ) -> types.InputResponse | types.ErrorData:
+        """Route an input request through the client's callback table.
+
+        Shared by the legacy server→client RPC path (`_on_request`) and the
+        2026-07-28 multi-round-trip driver, which dispatches the embedded
+        `InputRequiredResult.input_requests` through the same callbacks.
+
+        Returns the callback's `InputResponse`, or `ErrorData` when the callback declines.
+        """
+        match request:
+            case types.CreateMessageRequest(params=p):
+                return await self._sampling_callback(ctx, p)
+            case types.ElicitRequest(params=p):
+                return await self._elicitation_callback(ctx, p)
+            case types.ListRootsRequest():  # pragma: no branch
+                return await self._list_roots_callback(ctx)
+
+    def _register_listen_route(self, request_id: RequestId) -> ListenRoute:
+        """Create the demux route for a listen request id; the caller registers BEFORE sending."""
+        route = ListenRoute()
+        self._listen_routes[request_id] = route
+        return route
+
+    def _unregister_listen_route(self, request_id: RequestId) -> None:
+        """Drop a listen route; the handle owns membership, so a missing key is a no-op."""
+        self._listen_routes.pop(request_id, None)
+
+    def _settle_listen_routes_closed(self) -> None:
+        """Settle all open listen routes as lost on session exit; cancelled driver tasks cannot."""
+        closed = MCPError(code=CONNECTION_CLOSED, message="Connection closed")
+        for route in self._listen_routes.values():
+            route.settle("lost", error=closed)
+        self._listen_routes.clear()
+
+    def _intercept_notification(self, method: str, params: Mapping[str, Any] | None) -> bool:
+        """Wire-order listen demux, run synchronously on the dispatcher's receive path.
+
+        Bookkeeping must advance in receive order with the listen result (resolved on
+        this same path); the spawned `_on_notify` path would race it and drop events.
+        Returns True to consume the frame: a live route's ack is driver state, never surfaced.
+        """
+        if not self._listen_routes:
+            return False
+        if method == "notifications/cancelled":
+            request_id = cancelled_request_id_from_params(params)
+            if request_id is not None and (listen_route := self._listen_routes.get(request_id)) is not None:
+                # a server-sent cancel naming a listen request is that stream's teardown signal
+                listen_route.settle("lost")
+            return False  # _on_notify swallows every cancelled either way (v1 parity)
+        if params is None:
+            return False
+        meta = params.get("_meta")
+        if not isinstance(meta, Mapping):
+            return False
+        # as_request_id is not a tripwire: raw wire _meta can carry a non-id (even unhashable) value
+        subscription_id = as_request_id(cast("Mapping[str, Any]", meta).get(SUBSCRIPTION_ID_META_KEY))
+        if subscription_id is None or (listen_route := self._listen_routes.get(subscription_id)) is None:
+            return False
+        if method == "notifications/subscriptions/acknowledged":
+            raw_filter = params.get("notifications")
+            if raw_filter is None:
+                # malformed, not an empty filter: leave it to the spawned path's validation warning
+                return False
+            try:
+                honored = types.SubscriptionFilter.model_validate(raw_filter)
+            except ValidationError:
+                return False
+            listen_route.set_acked(honored)
+            return True
+        if (event := event_from_wire(method, params)) is not None:
+            listen_route.deliver(event)
+        return False  # events (and any other stamped frame) still tee as usual
+
+    async def _on_notify(
+        self, dctx: DispatchContext[TransportContext], method: str, params: Mapping[str, Any] | None
+    ) -> None:
+        """Route a server notification: validate, run the typed callback, tee to message_handler."""
+        # Same fallback as `_on_request`: covers pre-handshake and stateless.
+        version = self._negotiated_version or "2025-11-25"
+        try:
+            notification = cast(types.ServerNotification, _methods.parse_server_notification(method, version, params))
+        except KeyError:
+            # Only methods unknown to the negotiated version's core tables reach the bindings.
+            binding = self._notification_bindings.get(method)
+            if binding is None:
+                logger.debug("dropped %r: not defined at %s", method, version)
+                return
+            try:
+                bound_params = binding.params_type.model_validate(params or {})
+            except ValidationError:
+                logger.warning("Failed to validate notification: %s", method, exc_info=True)
+                return
+            send, receive = self._binding_queues[method]
+            try:
+                # Must not await: DirectDispatcher calls _on_notify inline; blocking deadlocks in-process servers.
+                send.send_nowait(bound_params)
+            except anyio.WouldBlock:
+                # Evict the oldest event; no checkpoint since the failed send,
+                # so the buffer is still full and the retry cannot block.
+                receive.receive_nowait()
+                logger.warning("notification queue for %r is full; dropped the oldest event", method)
+                send.send_nowait(bound_params)
+            return
+        except ValidationError:
+            logger.warning("Failed to validate notification: %s", method, exc_info=True)
+            return
+        if isinstance(notification, types.CancelledNotification):
+            # Never surfaced (v1 parity): the dispatcher already applied it; listen cancels settled by the intercept.
+            return
+        try:
+            if isinstance(notification, types.LoggingMessageNotification):
+                await self._logging_callback(notification.params)
+            await self._message_handler(notification)
+        except Exception:
+            # Contain here, not in the dispatcher: DirectDispatcher awaits this
+            # handler inline in the peer's notify() call, so a raising callback
+            # would otherwise fail the peer's send. A raising logging_callback
+            # skips the message_handler tee for that notification (v1 parity).
+            logger.exception("notification callback for %r raised", method)
+
+    async def _on_stream_exception(self, exc: Exception) -> None:
+        """Deliver a transport-level fault to message_handler via a spawned task.
+
+        Running the handler inline would park the dispatcher's read loop and
+        deadlock handlers that await session I/O.
+        """
+        assert self._task_group is not None
+        self._task_group.start_soon(self._deliver_stream_exception, exc)
+
+    async def _deliver_stream_exception(self, exc: Exception) -> None:
+        try:
+            await self._message_handler(exc)
+        except Exception:
+            logger.exception("message_handler raised on transport exception")

.mcp-venv/lib/python3.13/site-packages/mcp/client/session_group.py

@@ -0,0 +1,449 @@
+"""SessionGroup concurrently manages multiple MCP session connections.
+
+Tools, resources, and prompts are aggregated across servers. Servers may
+be connected to or disconnected from at any point after initialization.
+
+This abstraction can handle naming collisions using a custom user-provided hook.
+"""
+
+import contextlib
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass
+from types import TracebackType
+from typing import Any, Literal, TypeAlias, overload
+
+import anyio
+import httpx2
+import mcp_types as types
+from pydantic import BaseModel, Field
+from typing_extensions import Self
+
+import mcp
+from mcp.client.session import ElicitationFnT, ListRootsFnT, LoggingFnT, MessageHandlerFnT, SamplingFnT
+from mcp.client.sse import sse_client
+from mcp.client.stdio import StdioServerParameters
+from mcp.client.streamable_http import streamable_http_client
+from mcp.shared._httpx_utils import create_mcp_http_client
+from mcp.shared.dispatcher import ProgressFnT
+from mcp.shared.exceptions import MCPError
+
+
+class SseServerParameters(BaseModel):
+    """Parameters for initializing an sse_client."""
+
+    # The endpoint URL.
+    url: str
+
+    # Optional headers to include in requests.
+    headers: dict[str, Any] | None = None
+
+    # HTTP timeout for regular operations (in seconds).
+    timeout: float = 5.0
+
+    # Timeout for SSE read operations (in seconds).
+    sse_read_timeout: float = 300.0
+
+
+class StreamableHttpParameters(BaseModel):
+    """Parameters for initializing a streamable_http_client."""
+
+    # The endpoint URL.
+    url: str
+
+    # Optional headers to include in requests.
+    headers: dict[str, Any] | None = None
+
+    # HTTP timeout for regular operations (in seconds).
+    timeout: float = 30.0
+
+    # Timeout for SSE read operations (in seconds).
+    sse_read_timeout: float = 300.0
+
+    # Close the client session when the transport closes.
+    terminate_on_close: bool = True
+
+
+ServerParameters: TypeAlias = StdioServerParameters | SseServerParameters | StreamableHttpParameters
+
+
+# Use dataclass instead of Pydantic BaseModel
+# because Pydantic BaseModel cannot handle Protocol fields.
+@dataclass
+class ClientSessionParameters:
+    """Parameters for establishing a client session to an MCP server."""
+
+    read_timeout_seconds: float | None = None
+    sampling_callback: SamplingFnT | None = None
+    elicitation_callback: ElicitationFnT | None = None
+    list_roots_callback: ListRootsFnT | None = None
+    logging_callback: LoggingFnT | None = None
+    message_handler: MessageHandlerFnT | None = None
+    client_info: types.Implementation | None = None
+
+
+class ClientSessionGroup:
+    """Client for managing connections to multiple MCP servers.
+
+    This class is responsible for encapsulating management of server connections.
+    It aggregates tools, resources, and prompts from all connected servers.
+
+    For auxiliary handlers, such as resource subscription, this is delegated to
+    the client and can be accessed via the session.
+
+    Example:
+        ```python
+        name_fn = lambda name, server_info: f"{(server_info.name)}_{name}"
+        async with ClientSessionGroup(component_name_hook=name_fn) as group:
+            for server_param in server_params:
+                await group.connect_to_server(server_param)
+            ...
+        ```
+    """
+
+    class _ComponentNames(BaseModel):
+        """Used for reverse index to find components."""
+
+        prompts: set[str] = Field(default_factory=set)
+        resources: set[str] = Field(default_factory=set)
+        tools: set[str] = Field(default_factory=set)
+
+    # Standard MCP components.
+    _prompts: dict[str, types.Prompt]
+    _resources: dict[str, types.Resource]
+    _tools: dict[str, types.Tool]
+
+    # Client-server connection management.
+    _sessions: dict[mcp.ClientSession, _ComponentNames]
+    _tool_to_session: dict[str, mcp.ClientSession]
+    _exit_stack: contextlib.AsyncExitStack
+    _session_exit_stacks: dict[mcp.ClientSession, contextlib.AsyncExitStack]
+
+    # Optional fn consuming (component_name, server_info) for custom names.
+    # This is to provide a means to mitigate naming conflicts across servers.
+    # Example: (tool_name, server_info) => "{result.server_info.name}.{tool_name}"
+    _ComponentNameHook: TypeAlias = Callable[[str, types.Implementation], str]
+    _component_name_hook: _ComponentNameHook | None
+
+    def __init__(
+        self,
+        exit_stack: contextlib.AsyncExitStack | None = None,
+        component_name_hook: _ComponentNameHook | None = None,
+    ) -> None:
+        """Initializes the MCP client."""
+
+        self._tools = {}
+        self._resources = {}
+        self._prompts = {}
+
+        self._sessions = {}
+        self._tool_to_session = {}
+        if exit_stack is None:
+            self._exit_stack = contextlib.AsyncExitStack()
+            self._owns_exit_stack = True
+        else:
+            self._exit_stack = exit_stack
+            self._owns_exit_stack = False
+        self._session_exit_stacks = {}
+        self._component_name_hook = component_name_hook
+
+    async def __aenter__(self) -> Self:  # pragma: no cover
+        # Enter the exit stack only if we created it ourselves
+        if self._owns_exit_stack:
+            await self._exit_stack.__aenter__()
+        return self
+
+    async def __aexit__(
+        self,
+        _exc_type: type[BaseException] | None,
+        _exc_val: BaseException | None,
+        _exc_tb: TracebackType | None,
+    ) -> bool | None:  # pragma: no cover
+        """Closes session exit stacks and main exit stack upon completion."""
+
+        # Only close the main exit stack if we created it
+        if self._owns_exit_stack:
+            await self._exit_stack.aclose()
+
+        # Concurrently close session stacks.
+        async with anyio.create_task_group() as tg:
+            for exit_stack in self._session_exit_stacks.values():
+                tg.start_soon(exit_stack.aclose)
+
+    @property
+    def sessions(self) -> list[mcp.ClientSession]:
+        """Returns the list of sessions being managed."""
+        return list(self._sessions.keys())  # pragma: no cover
+
+    @property
+    def prompts(self) -> dict[str, types.Prompt]:
+        """Returns the prompts as a dictionary of names to prompts."""
+        return self._prompts
+
+    @property
+    def resources(self) -> dict[str, types.Resource]:
+        """Returns the resources as a dictionary of names to resources."""
+        return self._resources
+
+    @property
+    def tools(self) -> dict[str, types.Tool]:
+        """Returns the tools as a dictionary of names to tools."""
+        return self._tools
+
+    @overload
+    async def call_tool(
+        self,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        read_timeout_seconds: float | None = None,
+        progress_callback: ProgressFnT | None = None,
+        *,
+        input_responses: types.InputResponses | None = None,
+        request_state: str | None = None,
+        meta: types.RequestParamsMeta | None = None,
+        allow_input_required: Literal[False] = False,
+    ) -> types.CallToolResult: ...
+
+    @overload
+    async def call_tool(
+        self,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        read_timeout_seconds: float | None = None,
+        progress_callback: ProgressFnT | None = None,
+        *,
+        input_responses: types.InputResponses | None = None,
+        request_state: str | None = None,
+        meta: types.RequestParamsMeta | None = None,
+        allow_input_required: bool,
+    ) -> types.CallToolResult | types.InputRequiredResult: ...
+
+    async def call_tool(
+        self,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        read_timeout_seconds: float | None = None,
+        progress_callback: ProgressFnT | None = None,
+        *,
+        input_responses: types.InputResponses | None = None,
+        request_state: str | None = None,
+        meta: types.RequestParamsMeta | None = None,
+        allow_input_required: bool = False,
+    ) -> types.CallToolResult | types.InputRequiredResult:
+        """Executes a tool given its name and arguments.
+
+        Raises:
+            RuntimeError: If the server returns an `InputRequiredResult` and
+                ``allow_input_required`` is ``False``.
+        """
+        session = self._tool_to_session[name]
+        session_tool_name = self.tools[name].name
+        return await session.call_tool(
+            session_tool_name,
+            arguments=arguments,
+            read_timeout_seconds=read_timeout_seconds,
+            progress_callback=progress_callback,
+            input_responses=input_responses,
+            request_state=request_state,
+            meta=meta,
+            allow_input_required=allow_input_required,
+        )
+
+    async def disconnect_from_server(self, session: mcp.ClientSession) -> None:
+        """Disconnects from a single MCP server."""
+
+        session_known_for_components = session in self._sessions
+        session_known_for_stack = session in self._session_exit_stacks
+
+        if not session_known_for_components and not session_known_for_stack:
+            raise MCPError(
+                code=types.INVALID_PARAMS,
+                message="Provided session is not managed or already disconnected.",
+            )
+
+        if session_known_for_components:  # pragma: no branch
+            component_names = self._sessions.pop(session)  # Pop from _sessions tracking
+
+            # Remove prompts associated with the session.
+            for name in component_names.prompts:
+                if name in self._prompts:  # pragma: no branch
+                    del self._prompts[name]
+            # Remove resources associated with the session.
+            for name in component_names.resources:
+                if name in self._resources:  # pragma: no branch
+                    del self._resources[name]
+            # Remove tools associated with the session.
+            for name in component_names.tools:
+                if name in self._tools:  # pragma: no branch
+                    del self._tools[name]
+                if name in self._tool_to_session:  # pragma: no branch
+                    del self._tool_to_session[name]
+
+        # Clean up the session's resources via its dedicated exit stack
+        if session_known_for_stack:
+            session_stack_to_close = self._session_exit_stacks.pop(session)  # pragma: no cover
+            await session_stack_to_close.aclose()  # pragma: no cover
+
+    async def connect_with_session(
+        self, server_info: types.Implementation, session: mcp.ClientSession
+    ) -> mcp.ClientSession:
+        """Connects to a single MCP server."""
+        await self._aggregate_components(server_info, session)
+        return session
+
+    async def connect_to_server(
+        self,
+        server_params: ServerParameters,
+        session_params: ClientSessionParameters | None = None,
+    ) -> mcp.ClientSession:
+        """Connects to a single MCP server."""
+        server_info, session = await self._establish_session(server_params, session_params or ClientSessionParameters())
+        return await self.connect_with_session(server_info, session)
+
+    async def _establish_session(
+        self,
+        server_params: ServerParameters,
+        session_params: ClientSessionParameters,
+    ) -> tuple[types.Implementation, mcp.ClientSession]:
+        """Establish a client session to an MCP server."""
+
+        session_stack = contextlib.AsyncExitStack()
+        try:
+            # Create read and write streams that facilitate io with the server.
+            if isinstance(server_params, StdioServerParameters):
+                client = mcp.stdio_client(server_params)
+                read, write = await session_stack.enter_async_context(client)
+            elif isinstance(server_params, SseServerParameters):
+                client = sse_client(
+                    url=server_params.url,
+                    headers=server_params.headers,
+                    timeout=server_params.timeout,
+                    sse_read_timeout=server_params.sse_read_timeout,
+                )
+                read, write = await session_stack.enter_async_context(client)
+            else:
+                httpx_client = create_mcp_http_client(
+                    headers=server_params.headers,
+                    timeout=httpx2.Timeout(
+                        server_params.timeout,
+                        read=server_params.sse_read_timeout,
+                    ),
+                )
+                await session_stack.enter_async_context(httpx_client)
+
+                client = streamable_http_client(
+                    url=server_params.url,
+                    http_client=httpx_client,
+                    terminate_on_close=server_params.terminate_on_close,
+                )
+                read, write = await session_stack.enter_async_context(client)
+
+            session = await session_stack.enter_async_context(
+                mcp.ClientSession(
+                    read,
+                    write,
+                    read_timeout_seconds=session_params.read_timeout_seconds,
+                    sampling_callback=session_params.sampling_callback,
+                    elicitation_callback=session_params.elicitation_callback,
+                    list_roots_callback=session_params.list_roots_callback,
+                    logging_callback=session_params.logging_callback,
+                    message_handler=session_params.message_handler,
+                    client_info=session_params.client_info,
+                )
+            )
+
+            result = await session.initialize()
+
+            # Session successfully initialized.
+            # Store its stack and register the stack with the main group stack.
+            self._session_exit_stacks[session] = session_stack
+            # session_stack itself becomes a resource managed by the
+            # main _exit_stack.
+            await self._exit_stack.enter_async_context(session_stack)
+
+            return result.server_info, session
+        except Exception:  # pragma: no cover
+            # If anything during this setup fails, ensure the session-specific
+            # stack is closed.
+            await session_stack.aclose()
+            raise
+
+    async def _aggregate_components(self, server_info: types.Implementation, session: mcp.ClientSession) -> None:
+        """Aggregates prompts, resources, and tools from a given session."""
+
+        # Create a reverse index so we can find all prompts, resources, and
+        # tools belonging to this session. Used for removing components from
+        # the session group via self.disconnect_from_server.
+        component_names = self._ComponentNames()
+
+        # Temporary components dicts. We do not want to modify the aggregate
+        # lists in case of an intermediate failure.
+        prompts_temp: dict[str, types.Prompt] = {}
+        resources_temp: dict[str, types.Resource] = {}
+        tools_temp: dict[str, types.Tool] = {}
+        tool_to_session_temp: dict[str, mcp.ClientSession] = {}
+
+        # Query the server for its prompts and aggregate to list.
+        try:
+            prompts = (await session.list_prompts()).prompts
+            for prompt in prompts:
+                name = self._component_name(prompt.name, server_info)
+                prompts_temp[name] = prompt
+                component_names.prompts.add(name)
+        except MCPError as err:  # pragma: no cover
+            logging.warning(f"Could not fetch prompts: {err}")
+
+        # Query the server for its resources and aggregate to list.
+        try:
+            resources = (await session.list_resources()).resources
+            for resource in resources:
+                name = self._component_name(resource.name, server_info)
+                resources_temp[name] = resource
+                component_names.resources.add(name)
+        except MCPError as err:  # pragma: no cover
+            logging.warning(f"Could not fetch resources: {err}")
+
+        # Query the server for its tools and aggregate to list.
+        try:
+            tools = (await session.list_tools()).tools
+            for tool in tools:
+                name = self._component_name(tool.name, server_info)
+                tools_temp[name] = tool
+                tool_to_session_temp[name] = session
+                component_names.tools.add(name)
+        except MCPError as err:  # pragma: no cover
+            logging.warning(f"Could not fetch tools: {err}")
+
+        # Clean up exit stack for session if we couldn't retrieve anything
+        # from the server.
+        if not any((prompts_temp, resources_temp, tools_temp)):
+            del self._session_exit_stacks[session]  # pragma: no cover
+
+        # Check for duplicates.
+        matching_prompts = prompts_temp.keys() & self._prompts.keys()
+        if matching_prompts:
+            raise MCPError(  # pragma: no cover
+                code=types.INVALID_PARAMS,
+                message=f"{matching_prompts} already exist in group prompts.",
+            )
+        matching_resources = resources_temp.keys() & self._resources.keys()
+        if matching_resources:
+            raise MCPError(  # pragma: no cover
+                code=types.INVALID_PARAMS,
+                message=f"{matching_resources} already exist in group resources.",
+            )
+        matching_tools = tools_temp.keys() & self._tools.keys()
+        if matching_tools:
+            raise MCPError(code=types.INVALID_PARAMS, message=f"{matching_tools} already exist in group tools.")
+
+        # Aggregate components.
+        self._sessions[session] = component_names
+        self._prompts.update(prompts_temp)
+        self._resources.update(resources_temp)
+        self._tools.update(tools_temp)
+        self._tool_to_session.update(tool_to_session_temp)
+
+    def _component_name(self, name: str, server_info: types.Implementation) -> str:
+        if self._component_name_hook:
+            return self._component_name_hook(name, server_info)
+        return name

.mcp-venv/lib/python3.13/site-packages/mcp/client/sse.py

@@ -0,0 +1,161 @@
+import logging
+from collections.abc import Callable
+from contextlib import asynccontextmanager
+from typing import Any
+from urllib.parse import parse_qs, urljoin, urlparse
+
+import anyio
+import httpx2
+import mcp_types as types
+from anyio.abc import TaskStatus
+from httpx2 import SSEError
+
+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
+from mcp.shared.message import SessionMessage
+
+logger = logging.getLogger(__name__)
+
+
+def remove_request_params(url: str) -> str:
+    return urljoin(url, urlparse(url).path)
+
+
+def _extract_session_id_from_endpoint(endpoint_url: str) -> str | None:
+    query_params = parse_qs(urlparse(endpoint_url).query)
+    return query_params.get("sessionId", [None])[0] or query_params.get("session_id", [None])[0]
+
+
+@asynccontextmanager
+async def sse_client(
+    url: str,
+    headers: dict[str, Any] | None = None,
+    timeout: float = 5.0,
+    sse_read_timeout: float = 300.0,
+    httpx_client_factory: McpHttpClientFactory = create_mcp_http_client,
+    auth: httpx2.Auth | None = None,
+    on_session_created: Callable[[str], None] | None = None,
+):
+    """Client transport for SSE.
+
+    `sse_read_timeout` determines how long (in seconds) the client will wait for a new
+    event before disconnecting. All other HTTP operations are controlled by `timeout`.
+
+    Args:
+        url: The SSE endpoint URL.
+        headers: Optional headers to include in requests.
+        timeout: HTTP timeout for regular operations (in seconds).
+        sse_read_timeout: Timeout for SSE read operations (in seconds).
+        httpx_client_factory: Factory function for creating the httpx2 client.
+        auth: Optional httpx2 authentication handler.
+        on_session_created: Optional callback invoked with the session ID when received.
+    """
+    logger.debug(f"Connecting to SSE endpoint: {remove_request_params(url)}")
+    async with httpx_client_factory(
+        headers=headers, auth=auth, timeout=httpx2.Timeout(timeout, read=sse_read_timeout)
+    ) as client:
+        async with client.sse(url) as event_source:
+            event_source.response.raise_for_status()
+            logger.debug("SSE connection established")
+
+            read_stream_writer, read_stream = create_context_streams[SessionMessage | Exception](0)
+            write_stream, write_stream_reader = create_context_streams[SessionMessage](0)
+
+            async def sse_reader(task_status: TaskStatus[str] = anyio.TASK_STATUS_IGNORED):
+                try:
+                    async for sse in event_source:  # pragma: no branch
+                        logger.debug(f"Received SSE event: {sse.event}")
+                        match sse.event:
+                            case "endpoint":
+                                endpoint_url = urljoin(url, sse.data)
+                                logger.debug(f"Received endpoint URL: {endpoint_url}")
+
+                                url_parsed = urlparse(url)
+                                endpoint_parsed = urlparse(endpoint_url)
+                                if (  # pragma: no cover
+                                    url_parsed.netloc != endpoint_parsed.netloc
+                                    or url_parsed.scheme != endpoint_parsed.scheme
+                                ):
+                                    error_msg = (  # pragma: no cover
+                                        f"Endpoint origin does not match connection origin: {endpoint_url}"
+                                    )
+                                    logger.error(error_msg)  # pragma: no cover
+                                    raise ValueError(error_msg)  # pragma: no cover
+
+                                if on_session_created:
+                                    session_id = _extract_session_id_from_endpoint(endpoint_url)
+                                    if session_id:
+                                        on_session_created(session_id)
+
+                                task_status.started(endpoint_url)
+
+                            case "message":
+                                # Skip empty data (keep-alive pings)
+                                if not sse.data:
+                                    continue
+                                try:
+                                    message = types.jsonrpc_message_adapter.validate_json(sse.data, by_name=False)
+                                    logger.debug(f"Received server message: {message}")
+                                except Exception as exc:  # pragma: no cover
+                                    logger.exception("Error parsing server message")  # pragma: no cover
+                                    await read_stream_writer.send(exc)  # pragma: no cover
+                                    continue  # pragma: no cover
+
+                                session_message = SessionMessage(message)
+                                await read_stream_writer.send(session_message)
+                            case _:  # pragma: no cover
+                                logger.warning(f"Unknown SSE event: {sse.event}")  # pragma: no cover
+                except SSEError as sse_exc:  # pragma: lax no cover
+                    logger.exception("Encountered SSE exception")
+                    raise sse_exc
+                except Exception as exc:  # pragma: lax no cover
+                    logger.exception("Error in sse_reader")
+                    await read_stream_writer.send(exc)
+                finally:
+                    await read_stream_writer.aclose()
+
+            async def post_writer(endpoint_url: str):
+                try:
+                    async with write_stream_reader, write_stream:
+
+                        async def _send_message(session_message: SessionMessage) -> None:
+                            logger.debug(f"Sending client message: {session_message}")
+                            response = await client.post(
+                                endpoint_url,
+                                json=session_message.message.model_dump(
+                                    by_alias=True,
+                                    mode="json",
+                                    exclude_unset=True,
+                                ),
+                            )
+                            response.raise_for_status()
+                            logger.debug(f"Client message sent successfully: {response.status_code}")
+
+                        async for session_message in write_stream_reader:
+                            sender_ctx = write_stream_reader.last_context
+                            if sender_ctx is not None:
+                                async with anyio.create_task_group() as tg:
+                                    sender_ctx.run(tg.start_soon, _send_message, session_message)
+                            else:
+                                await _send_message(session_message)  # pragma: no cover
+                except Exception:  # pragma: lax no cover
+                    logger.exception("Error in post_writer")
+
+            # On Python 3.14, coverage.py reports a phantom branch arc on this
+            # line (->yield) when nested two async-with levels deep. The branch
+            # is the unreachable "did __aexit__ suppress?" arm for memory streams.
+            async with (  # pragma: no branch
+                read_stream_writer,
+                read_stream,
+                write_stream,
+                write_stream_reader,
+                anyio.create_task_group() as tg,
+            ):
+                endpoint_url = await tg.start(sse_reader)
+                logger.debug(f"Starting post writer with endpoint URL: {endpoint_url}")
+                tg.start_soon(post_writer, endpoint_url)
+
+                yield read_stream, write_stream
+                tg.cancel_scope.cancel()
+            await resync_tracer()

.mcp-venv/lib/python3.13/site-packages/mcp/client/stdio.py

@@ -0,0 +1,354 @@
+"""stdio client transport.
+
+Runs an MCP server as a subprocess and exchanges newline-delimited JSON-RPC
+messages with it over stdin/stdout. Two pipe tasks bridge the server's pipes
+to the session's in-memory streams; shutdown follows the MCP spec sequence
+(close stdin, wait, then kill the process tree) inside a cancellation shield
+with every wait bounded, so a cancelled caller can neither leak a live server
+process nor hang on one.
+"""
+
+import logging
+import os
+import sys
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager, suppress
+from pathlib import Path
+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.client._transport import TransportStreams
+from mcp.os.posix.utilities import terminate_posix_process_tree
+from mcp.os.win32.utilities import (
+    ServerProcess,
+    close_process_job,
+    create_windows_process,
+    get_windows_executable_command,
+    terminate_windows_process_tree,
+)
+from mcp.shared.message import SessionMessage
+
+logger = logging.getLogger(__name__)
+
+# Environment variables to inherit by default
+DEFAULT_INHERITED_ENV_VARS = (
+    [
+        "APPDATA",
+        "HOMEDRIVE",
+        "HOMEPATH",
+        "LOCALAPPDATA",
+        "PATH",
+        "PATHEXT",
+        "PROCESSOR_ARCHITECTURE",
+        "SYSTEMDRIVE",
+        "SYSTEMROOT",
+        "TEMP",
+        "USERNAME",
+        "USERPROFILE",
+    ]
+    if sys.platform == "win32"
+    else ["HOME", "LOGNAME", "PATH", "SHELL", "TERM", "USER"]
+)
+
+# Grace period for the server to exit on its own after its stdin closes.
+PROCESS_TERMINATION_TIMEOUT = 2.0
+
+# Extra time after SIGTERM before SIGKILL; POSIX only (Windows kills hard).
+FORCE_KILL_TIMEOUT = 2.0
+
+# Time for the event loop to observe a kill; only an unkillable process runs this out.
+_KILL_REAP_TIMEOUT = 2.0
+
+# Time for the writer to flush accepted messages before stdin closes.
+_WRITER_FLUSH_TIMEOUT = 0.5
+
+# How often to poll returncode while waiting for the process to die.
+_EXIT_POLL_INTERVAL = 0.01
+
+
+def get_default_environment() -> dict[str, str]:
+    """Returns only the environment variables that are safe to inherit."""
+    env: dict[str, str] = {}
+
+    for key in DEFAULT_INHERITED_ENV_VARS:
+        value = os.environ.get(key)
+        if value is None:  # pragma: lax no cover
+            continue
+
+        if value.startswith("()"):  # pragma: no cover
+            # Skip functions, which are a security risk
+            continue  # pragma: no cover
+
+        env[key] = value
+
+    return env
+
+
+class StdioServerParameters(BaseModel):
+    command: str
+    """The executable to run to start the server."""
+
+    args: list[str] = Field(default_factory=list)
+    """Command line arguments to pass to the executable."""
+
+    env: dict[str, str] | None = None
+    """Extra environment variables, merged over get_default_environment()."""
+
+    cwd: str | Path | None = None
+    """The working directory to use when spawning the process."""
+
+    encoding: str = "utf-8"
+    """Text encoding for messages to and from the server."""
+
+    encoding_error_handler: Literal["strict", "ignore", "replace"] = "strict"
+    """Encoding error handler; see https://docs.python.org/3/library/codecs.html#error-handlers."""
+
+
+@asynccontextmanager
+async def stdio_client(
+    server: StdioServerParameters, errlog: TextIO = sys.stderr
+) -> AsyncGenerator[TransportStreams, None]:
+    """Spawns an MCP server subprocess and connects to it over stdin/stdout.
+
+    Raises:
+        OSError: If the server process cannot be spawned.
+        ValueError: If the spawn parameters are invalid (embedded NUL bytes).
+    """
+    command = _get_executable_command(server.command)
+
+    process = await _create_platform_compatible_process(
+        command=command,
+        args=server.args,
+        env=get_default_environment() | (server.env or {}),
+        errlog=errlog,
+        cwd=server.cwd,
+    )
+
+    # The spawn succeeded; no awaits until the task group is entered, or a
+    # cancellation delivered in the gap would leak the live process.
+    read_stream_writer, read_stream = anyio.create_memory_object_stream[SessionMessage | Exception](0)
+    write_stream, write_stream_reader = anyio.create_memory_object_stream[SessionMessage](0)
+
+    shutting_down = False
+    writer_done = anyio.Event()
+
+    async def stdout_reader() -> None:
+        assert process.stdout, "Opened process is missing stdout"
+
+        stdout = TextReceiveStream(process.stdout, encoding=server.encoding, errors=server.encoding_error_handler)
+        try:
+            async with read_stream_writer:
+                try:
+                    # One line at a time; no read-ahead while a delivery is blocked.
+                    buffer = ""
+                    async for chunk in stdout:
+                        lines = (buffer + chunk).split("\n")
+                        buffer = lines.pop()
+                        for line in lines:
+                            try:
+                                await read_stream_writer.send(_parse_line(line))
+                            except (anyio.ClosedResourceError, anyio.BrokenResourceError):
+                                return  # the session is gone; only the drain below remains
+                finally:
+                    await _drain_stdout(process)
+        except anyio.ClosedResourceError:
+            pass  # our own shutdown closed the stdout stream under the read
+        except (anyio.BrokenResourceError, ConnectionError):
+            # Teardown noise during shutdown, a real failure otherwise; either way
+            # the session sees clean closure when the read stream closes.
+            if not shutting_down:
+                logger.exception("Reading from the MCP server's stdout failed mid-session")
+
+    async def stdin_writer() -> None:
+        assert process.stdin, "Opened process is missing stdin"
+
+        try:
+            async with write_stream_reader:
+                async for session_message in write_stream_reader:
+                    json = session_message.message.model_dump_json(by_alias=True, exclude_unset=True)
+                    data = (json + "\n").encode(encoding=server.encoding, errors=server.encoding_error_handler)
+                    await process.stdin.send(data)
+        except (anyio.ClosedResourceError, anyio.BrokenResourceError, OSError):
+            # The server may still be alive: close the read stream so the session
+            # sees the connection end instead of a request hanging forever.
+            await read_stream_writer.aclose()
+        finally:
+            writer_done.set()
+
+    async def shutdown() -> None:
+        """Winds the transport down: stop traffic, flush, stop the server, release the streams."""
+        # Unblock the reader into its drain: a server stuck writing stdout cannot
+        # read its stdin, so draining is what lets the flush below complete.
+        read_stream.close()
+        # Bounded window for the writer to flush already-accepted messages.
+        write_stream.close()
+        with anyio.move_on_after(_WRITER_FLUSH_TIMEOUT) as flush_scope:
+            await writer_done.wait()
+        if flush_scope.cancelled_caught:
+            await anyio.lowlevel.cancel_shielded_checkpoint()  # resync coverage on 3.11 (gh-106749)
+        await _stop_server_process(process)
+        await _aclose_all(read_stream, write_stream, read_stream_writer, write_stream_reader)
+        # One pass so unblocked tasks exit via their except paths before the cancel.
+        await anyio.lowlevel.checkpoint()
+
+    async with anyio.create_task_group() as tg:
+        tg.start_soon(stdout_reader)
+        tg.start_soon(stdin_writer)
+        try:
+            yield read_stream, write_stream
+        finally:
+            shutting_down = True
+            # Shutdown must finish even under caller cancellation, or the server
+            # process would leak; every wait inside is bounded. (Native
+            # task.cancel() and the fallback's worker threads can still defeat it.)
+            with anyio.CancelScope(shield=True):
+                await shutdown()
+            # Unstick pipe tasks a kill survivor's open pipe end could still block.
+            tg.cancel_scope.cancel()
+    # The cancel lands via throw(); one yield resyncs 3.11 coverage (gh-106749).
+    await anyio.lowlevel.cancel_shielded_checkpoint()
+
+
+def _parse_line(line: str) -> SessionMessage | Exception:
+    """Parses one stdout line, returning parse errors as values for the session to surface."""
+    try:
+        message = types.jsonrpc_message_adapter.validate_json(line, by_name=False)
+    except ValueError as exc:
+        logger.exception("Failed to parse JSONRPC message from server")
+        return exc
+    return SessionMessage(message)
+
+
+async def _drain_stdout(process: ServerProcess) -> None:
+    """Consumes and discards the server's remaining stdout.
+
+    Keeps a server flushing buffered output from blocking on a full pipe and
+    missing its chance to exit; shielded, raw bytes, ends when shutdown closes
+    the pipe.
+    """
+    assert process.stdout
+    with anyio.CancelScope(shield=True):
+        with suppress(
+            anyio.EndOfStream,
+            anyio.ClosedResourceError,
+            anyio.BrokenResourceError,
+            ConnectionError,
+            OSError,
+        ):
+            while True:
+                await process.stdout.receive()
+
+
+async def _stop_server_process(process: ServerProcess) -> None:
+    """Closes stdin, waits out the grace period, then kills the whole tree.
+
+    The escalation order is spec text; timeouts and tree-wide scope are SDK policy:
+    https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle#shutdown
+    """
+    assert process.stdin and process.stdout, "server process is spawned with pipes"
+
+    await _close_pipe(process.stdin)
+    if not await _wait_for_process_exit(process, PROCESS_TERMINATION_TIMEOUT):
+        await _terminate_process_tree(process)
+        # Until the event loop observes the death, the transport cannot close.
+        if not await _wait_for_process_exit(process, _KILL_REAP_TIMEOUT):
+            logger.warning("MCP server process %d is still alive after the kill escalation; abandoning it", process.pid)
+
+    # Reaps surviving Windows job members now, not at GC; no-op on POSIX.
+    close_process_job(process)
+    # A kill survivor can hold the stdout pipe open; poison the reader anyway.
+    await _close_pipe(process.stdout)
+    _close_subprocess_transport(process)
+
+
+async def _close_pipe(stream: AsyncResource) -> None:
+    """Closes a pipe stream, tolerating one already closed, broken, or contended."""
+    with suppress(OSError, anyio.BrokenResourceError, anyio.ClosedResourceError):
+        await stream.aclose()
+
+
+async def _wait_for_process_exit(process: ServerProcess, timeout: float) -> bool:
+    """Returns whether the process died within the timeout, by polling returncode.
+
+    Not process.wait(): on asyncio 3.11+ it also waits for pipe EOF, and a
+    child that inherited the pipes makes an exited server look hung.
+    """
+    deadline = anyio.current_time() + timeout
+    while process.returncode is None:
+        if anyio.current_time() >= deadline:
+            return False
+        await anyio.sleep(_EXIT_POLL_INTERVAL)
+    return True
+
+
+async def _terminate_process_tree(process: ServerProcess) -> None:
+    """Kills the process and all its descendants.
+
+    POSIX: SIGTERM to the process group, SIGKILL after FORCE_KILL_TIMEOUT.
+    Windows: immediate Job Object termination (already a hard kill).
+    """
+    if sys.platform == "win32":  # pragma: no cover
+        await terminate_windows_process_tree(process)
+    else:  # pragma: lax no cover
+        # The Windows-only FallbackProcess never reaches the POSIX path.
+        assert isinstance(process, Process)
+        await terminate_posix_process_tree(process, FORCE_KILL_TIMEOUT)
+
+
+def _close_subprocess_transport(process: ServerProcess) -> None:
+    """Closes the asyncio subprocess transport, if there is one.
+
+    The transport otherwise stays open (and warns at GC) while a surviving
+    descendant holds a pipe end; nothing public exposes it, hence the attribute
+    walk. No-op on trio and the Windows fallback.
+    """
+    transport = getattr(getattr(process, "_process", None), "_transport", None)
+    # Duck-typed: uvloop's UVProcessTransport is not an asyncio.SubprocessTransport.
+    close = getattr(transport, "close", None)
+    if callable(close):
+        # close() on <=3.12 can raise PermissionError re-killing a setuid child.
+        with suppress(PermissionError):
+            close()
+
+
+def _get_executable_command(command: str) -> str:
+    """Normalizes the command for the current platform."""
+    if sys.platform == "win32":  # pragma: no cover
+        return get_windows_executable_command(command)
+    else:  # pragma: lax no cover
+        return command
+
+
+async def _create_platform_compatible_process(
+    command: str,
+    args: list[str],
+    env: dict[str, str] | None = None,
+    errlog: TextIO = sys.stderr,
+    cwd: Path | str | None = None,
+) -> ServerProcess:
+    """Spawns the server in its own kill scope.
+
+    A new session/process group on POSIX, a Job Object on Windows.
+    """
+    if sys.platform == "win32":  # pragma: no cover
+        return await create_windows_process(command, args, env, errlog, cwd)
+    else:  # pragma: lax no cover
+        return await anyio.open_process(
+            [command, *args],
+            env=env,
+            stderr=errlog,
+            cwd=cwd,
+            start_new_session=True,
+        )
+
+
+async def _aclose_all(*streams: AsyncResource) -> None:
+    """Closes every given stream."""
+    for stream in streams:
+        await stream.aclose()

.mcp-venv/lib/python3.13/site-packages/mcp/client/streamable_http.py

@@ -0,0 +1,710 @@
+"""Implements StreamableHTTP transport for MCP clients."""
+
+from __future__ import annotations as _annotations
+
+import contextlib
+import logging
+from collections.abc import AsyncGenerator, Awaitable, Callable
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+
+import anyio
+import httpx2
+from anyio.abc import TaskGroup
+from httpx2 import EventSource, ServerSentEvent
+from mcp_types import (
+    CONNECTION_CLOSED,
+    INTERNAL_ERROR,
+    INVALID_REQUEST,
+    METHOD_NOT_FOUND,
+    PARSE_ERROR,
+    ErrorData,
+    JSONRPCError,
+    JSONRPCMessage,
+    JSONRPCNotification,
+    JSONRPCRequest,
+    JSONRPCResponse,
+    RequestId,
+    jsonrpc_message_adapter,
+)
+from mcp_types.version import MODERN_PROTOCOL_VERSIONS
+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.jsonrpc_dispatcher import cancelled_request_id_from_params
+from mcp.shared.message import ClientMessageMetadata, SessionMessage
+
+logger = logging.getLogger(__name__)
+
+
+# TODO(Marcelo): Put the TransportStreams in a module under shared, so we can import here.
+SessionMessageOrError = SessionMessage | Exception
+StreamWriter = ContextSendStream[SessionMessageOrError]
+StreamReader = ContextReceiveStream[SessionMessage]
+
+MCP_SESSION_ID = "mcp-session-id"
+LAST_EVENT_ID = "last-event-id"
+
+# Reconnection defaults
+DEFAULT_RECONNECTION_DELAY_MS = 1000  # 1 second fallback when server doesn't provide retry
+MAX_RECONNECTION_ATTEMPTS = 2  # Max retry attempts before giving up
+
+
+class StreamableHTTPError(Exception):
+    """Base exception for StreamableHTTP transport errors."""
+
+
+class ResumptionError(StreamableHTTPError):
+    """Raised when resumption request is invalid."""
+
+
+@dataclass
+class RequestContext:
+    """Context for a request operation."""
+
+    client: httpx2.AsyncClient
+    session_id: str | None
+    session_message: SessionMessage
+    metadata: ClientMessageMetadata | None
+    read_stream_writer: StreamWriter
+
+
+@dataclass(slots=True)
+class _InFlightPost:
+    """A request POST in flight: its abort scope and the era it was sent under.
+
+    `modern` is the negotiated-version cache as of this request's dequeue, so a
+    later cancel frame is interpreted under the era the request actually ran
+    with, not whatever the cache says by then.
+    """
+
+    scope: anyio.CancelScope
+    modern: bool
+
+
+class StreamableHTTPTransport:
+    """StreamableHTTP client transport implementation."""
+
+    def __init__(self, url: str) -> None:
+        """Initialize the StreamableHTTP transport.
+
+        Args:
+            url: The endpoint URL.
+        """
+        self.url = url
+        self.session_id: str | None = None
+        # Captured from each stamped message's metadata, synchronously in the
+        # post_writer loop so the cache always reflects wire order (a POST task's
+        # scheduling is arbitrary). Reused on outbound HTTP that carries no
+        # per-message header (transport-internal GET/DELETE, and dispatcher-written
+        # response/error POSTs that bypass the session's stamp), and consulted by
+        # `_consume_modern_cancellation`. Cleared when an `initialize` message is
+        # dequeued so a probe-stamped value cannot leak onto the handshake.
+        self._protocol_version_header: str | None = None
+        # Every request's POST runs inside one of these so an outbound
+        # `notifications/cancelled` at 2026 can abort it; see
+        # `_consume_modern_cancellation`. Keys are verbatim-typed ("1" is not 1).
+        self._in_flight_posts: dict[RequestId, _InFlightPost] = {}
+
+    def _prepare_headers(self) -> dict[str, str]:
+        """Build MCP-specific request headers for any outbound HTTP request.
+
+        These are merged with the ``httpx2.AsyncClient`` defaults (these take
+        precedence). The cached ``MCP-Protocol-Version`` is included whenever
+        present so messages that don't pass through the session's stamp —
+        response/error POSTs, legacy cancel frames, transport-internal
+        GET/DELETE — still carry the negotiated version. Per-message headers
+        are layered on top by the caller.
+        """
+        headers: dict[str, str] = {
+            "accept": "application/json, text/event-stream",
+            "content-type": "application/json",
+        }
+        if self.session_id:
+            headers[MCP_SESSION_ID] = self.session_id
+        if self._protocol_version_header:
+            headers[MCP_PROTOCOL_VERSION_HEADER] = self._protocol_version_header
+        return headers
+
+    def _is_initialization_request(self, message: JSONRPCMessage) -> bool:
+        """Check if the message is an initialization request."""
+        return isinstance(message, JSONRPCRequest) and message.method == "initialize"
+
+    def _is_initialized_notification(self, message: JSONRPCMessage) -> bool:
+        """Check if the message is an initialized notification."""
+        return isinstance(message, JSONRPCNotification) and message.method == "notifications/initialized"
+
+    def _maybe_extract_session_id_from_response(self, response: httpx2.Response) -> None:
+        """Extract and store session ID from response headers."""
+        new_session_id = response.headers.get(MCP_SESSION_ID)
+        if new_session_id:
+            self.session_id = new_session_id
+            logger.info(f"Received session ID: {self.session_id}")
+
+    async def _handle_sse_event(
+        self,
+        sse: ServerSentEvent,
+        read_stream_writer: StreamWriter,
+        original_request_id: RequestId | None = None,
+        resumption_callback: Callable[[str], Awaitable[None]] | None = None,
+    ) -> bool:
+        """Handle an SSE event, returning True if the response is complete."""
+        if sse.event == "message":
+            # Handle priming events (empty data with ID) for resumability
+            if not sse.data:
+                # Call resumption callback for priming events that have an ID
+                if sse.id and resumption_callback:
+                    await resumption_callback(sse.id)
+                return False
+            try:
+                message = jsonrpc_message_adapter.validate_json(sse.data, by_name=False)
+                logger.debug(f"SSE message: {message}")
+
+                # If this is a response and we have original_request_id, replace it
+                if original_request_id is not None and isinstance(message, JSONRPCResponse | JSONRPCError):
+                    message.id = original_request_id
+
+                session_message = SessionMessage(message)
+                await read_stream_writer.send(session_message)
+
+                # Call resumption token callback if we have an ID
+                if sse.id and resumption_callback:
+                    await resumption_callback(sse.id)
+
+                # If this is a response or error return True indicating completion
+                # Otherwise, return False to continue listening
+                return isinstance(message, JSONRPCResponse | JSONRPCError)
+
+            # Forwarding to a closed read stream lands here when the caller cancels mid-SSE
+            # (BrokenResourceError, not a parse failure); coverage is timing-dependent in the
+            # streaming story's modern HTTP cancellation leg.
+            except Exception as exc:  # pragma: lax no cover
+                logger.exception("Error parsing SSE message")
+                if original_request_id is not None:
+                    error_data = ErrorData(code=PARSE_ERROR, message=f"Failed to parse SSE message: {exc}")
+                    error_msg = SessionMessage(JSONRPCError(jsonrpc="2.0", id=original_request_id, error=error_data))
+                    await read_stream_writer.send(error_msg)
+                    return True
+                await read_stream_writer.send(exc)
+                return False
+        else:  # pragma: no cover
+            logger.warning(f"Unknown SSE event: {sse.event}")
+            return False
+
+    async def handle_get_stream(self, client: httpx2.AsyncClient, read_stream_writer: StreamWriter) -> None:
+        """Handle GET stream for server-initiated messages with auto-reconnect."""
+        last_event_id: str | None = None
+        retry_interval_ms: int | None = None
+        attempt: int = 0
+
+        while attempt < MAX_RECONNECTION_ATTEMPTS:  # pragma: no branch
+            try:
+                if not self.session_id:
+                    return
+
+                headers = self._prepare_headers()
+                if last_event_id:
+                    headers[LAST_EVENT_ID] = last_event_id
+
+                async with client.sse(self.url, headers=headers) as event_source:
+                    event_source.response.raise_for_status()
+                    logger.debug("GET SSE connection established")
+
+                    async for sse in event_source:
+                        # Track last event ID for reconnection
+                        if sse.id:
+                            last_event_id = sse.id
+                        # Track retry interval from server
+                        if sse.retry is not None:
+                            retry_interval_ms = sse.retry
+
+                        await self._handle_sse_event(sse, read_stream_writer)
+
+                    # Stream ended normally (server closed) - reset attempt counter
+                    attempt = 0
+
+            except Exception:
+                logger.debug("GET stream error", exc_info=True)
+                attempt += 1
+
+            if attempt >= MAX_RECONNECTION_ATTEMPTS:  # pragma: no cover
+                logger.debug(f"GET stream max reconnection attempts ({MAX_RECONNECTION_ATTEMPTS}) exceeded")
+                return
+
+            # Wait before reconnecting
+            delay_ms = retry_interval_ms if retry_interval_ms is not None else DEFAULT_RECONNECTION_DELAY_MS
+            logger.info(f"GET stream disconnected, reconnecting in {delay_ms}ms...")
+            await anyio.sleep(delay_ms / 1000.0)
+
+    async def _handle_resumption_request(self, ctx: RequestContext) -> None:
+        """Handle a resumption request using GET with SSE."""
+        headers = self._prepare_headers()
+        if ctx.metadata and ctx.metadata.resumption_token:
+            headers[LAST_EVENT_ID] = ctx.metadata.resumption_token
+        else:
+            raise ResumptionError("Resumption request requires a resumption token")  # pragma: no cover
+
+        # Extract original request ID to map responses
+        original_request_id = None
+        if isinstance(ctx.session_message.message, JSONRPCRequest):  # pragma: no branch
+            original_request_id = ctx.session_message.message.id
+
+        async with ctx.client.sse(self.url, headers=headers) as event_source:
+            event_source.response.raise_for_status()
+            logger.debug("Resumption GET SSE connection established")
+
+            async for sse in event_source:  # pragma: no branch
+                is_complete = await self._handle_sse_event(
+                    sse,
+                    ctx.read_stream_writer,
+                    original_request_id,
+                    ctx.metadata.on_resumption_token_update if ctx.metadata else None,
+                )
+                if is_complete:
+                    await event_source.response.aclose()
+                    break
+
+    def _consume_modern_cancellation(self, session_message: SessionMessage) -> bool:
+        """Translate an outbound `notifications/cancelled` at 2026; True means "do not POST".
+
+        The 2026 wire defines no client-to-server notifications over streamable
+        HTTP: closing a request's response stream IS its cancellation signal.
+        The dispatcher still emits the courtesy frame as its abandon signal
+        (every outbound cancel names one of our own request ids - the spec
+        forbids cancelling a request the sender did not issue), so this
+        transport translates it: when the named request's POST is in flight,
+        that POST's own recorded era decides - abort-and-swallow at 2026, POST
+        the frame below it (where the frame is the signal and a disconnect
+        explicitly is not). With no POST to consult, the cached negotiated
+        version decides; at 2026 the frame is swallowed even unmatched, so a
+        late cancel racing the response cannot leak onto the wire.
+        """
+        message = session_message.message
+        if not (isinstance(message, JSONRPCNotification) and message.method == "notifications/cancelled"):
+            return False
+        request_id = cancelled_request_id_from_params(message.params)
+        post = self._in_flight_posts.get(request_id) if request_id is not None else None
+        if post is not None:
+            if not post.modern:
+                return False
+            logger.debug("aborting in-flight POST for cancelled request %r", request_id)
+            post.scope.cancel()
+            return True
+        return self._protocol_version_header in MODERN_PROTOCOL_VERSIONS
+
+    async def _run_request_post(
+        self,
+        post_fn: Callable[[], Awaitable[None]],
+        post: _InFlightPost,
+        request_id: RequestId,
+    ) -> None:
+        """Run one request's POST inside its abort scope (see `_consume_modern_cancellation`)."""
+        try:
+            with post.scope:
+                await post_fn()
+        finally:
+            # Identity-guarded: a reused id may already have a successor
+            # registered while this task unwinds - popping by key alone would
+            # evict the live entry and leave the new POST unabortable.
+            if self._in_flight_posts.get(request_id) is post:
+                del self._in_flight_posts[request_id]
+
+    async def _handle_post_request(self, ctx: RequestContext) -> None:
+        """Handle a POST request with response processing."""
+        message = ctx.session_message.message
+        headers = self._prepare_headers()
+        if ctx.metadata is not None and ctx.metadata.headers is not None:
+            headers.update(ctx.metadata.headers)
+
+        async with ctx.client.stream(
+            "POST",
+            self.url,
+            json=message.model_dump(by_alias=True, mode="json", exclude_unset=True),
+            headers=headers,
+        ) as response:
+            if response.status_code == 202:
+                logger.debug("Received 202 Accepted")
+                if isinstance(message, JSONRPCRequest):
+                    # A request's response arrives on this POST's body; 202 says
+                    # none will follow. Resolve rather than park the caller forever.
+                    await self._resolve_abandoned_request(
+                        ctx.read_stream_writer,
+                        message.id,
+                        "server answered a request with 202 Accepted",
+                        code=INVALID_REQUEST,
+                    )
+                return
+
+            if response.status_code >= 400:
+                if isinstance(message, JSONRPCRequest):
+                    # A spec-correct server may return the JSON-RPC error in the
+                    # body at a non-2xx status (e.g. 400 for INVALID_PARAMS, 404
+                    # for METHOD_NOT_FOUND). Surface that error rather than the
+                    # status-derived stand-in below.
+                    if response.headers.get("content-type", "").lower().startswith("application/json"):
+                        try:
+                            body = await response.aread()
+                            parsed = jsonrpc_message_adapter.validate_json(body, by_name=False)
+                            if isinstance(parsed, JSONRPCError):
+                                # The server may have set `id: null` (request rejected before its
+                                # id was parsed); use this request's id so correlation works.
+                                reply = JSONRPCError(jsonrpc="2.0", id=message.id, error=parsed.error)
+                                await ctx.read_stream_writer.send(SessionMessage(reply))
+                                return
+                        except (httpx2.StreamError, ValidationError):
+                            pass
+                        logger.debug("Non-2xx body was not a JSON-RPC error; using fallback")
+                    if response.status_code == 404:
+                        if self.session_id is None:
+                            # No session yet → 404 is the HTTP-level spelling of
+                            # METHOD_NOT_FOUND (gateway / legacy server doesn't know
+                            # this method); "Session terminated" would be a lie here.
+                            error_data = ErrorData(code=METHOD_NOT_FOUND, message="Not Found")
+                        else:
+                            error_data = ErrorData(code=INVALID_REQUEST, message="Session terminated")
+                    else:
+                        error_data = ErrorData(code=INTERNAL_ERROR, message="Server returned an error response")
+                    session_message = SessionMessage(JSONRPCError(jsonrpc="2.0", id=message.id, error=error_data))
+                    await ctx.read_stream_writer.send(session_message)
+                return
+
+            if self._is_initialization_request(message):
+                self._maybe_extract_session_id_from_response(response)
+
+            # Per https://modelcontextprotocol.io/specification/2025-06-18/basic#notifications:
+            # The server MUST NOT send a response to notifications.
+            if isinstance(message, JSONRPCRequest):
+                content_type = response.headers.get("content-type", "").lower()
+                if content_type.startswith("application/json"):
+                    await self._handle_json_response(response, ctx.read_stream_writer, request_id=message.id)
+                elif content_type.startswith("text/event-stream"):
+                    await self._handle_sse_response(response, ctx)
+                else:
+                    logger.error(f"Unexpected content type: {content_type}")
+                    error_data = ErrorData(code=INVALID_REQUEST, message=f"Unexpected content type: {content_type}")
+                    error_msg = SessionMessage(JSONRPCError(jsonrpc="2.0", id=message.id, error=error_data))
+                    await ctx.read_stream_writer.send(error_msg)
+
+    async def _handle_json_response(
+        self,
+        response: httpx2.Response,
+        read_stream_writer: StreamWriter,
+        *,
+        request_id: RequestId,
+    ) -> None:
+        """Handle JSON response from the server."""
+        try:
+            content = await response.aread()
+            message = jsonrpc_message_adapter.validate_json(content, by_name=False)
+            session_message = SessionMessage(message)
+            await read_stream_writer.send(session_message)
+        except (httpx2.StreamError, ValidationError) as exc:
+            logger.exception("Error parsing JSON response")
+            error_data = ErrorData(code=PARSE_ERROR, message=f"Failed to parse JSON response: {exc}")
+            error_msg = SessionMessage(JSONRPCError(jsonrpc="2.0", id=request_id, error=error_data))
+            await read_stream_writer.send(error_msg)
+
+    async def _handle_sse_response(
+        self,
+        response: httpx2.Response,
+        ctx: RequestContext,
+    ) -> None:
+        """Handle SSE response from the server."""
+        last_event_id: str | None = None
+        retry_interval_ms: int | None = None
+
+        # The caller (_handle_post_request) only reaches here inside
+        # isinstance(message, JSONRPCRequest), so this is always a JSONRPCRequest.
+        assert isinstance(ctx.session_message.message, JSONRPCRequest)
+        original_request_id = ctx.session_message.message.id
+
+        try:
+            event_source = EventSource(response)
+            async for sse in event_source:  # pragma: no branch
+                # Track last event ID for potential reconnection
+                if sse.id:
+                    last_event_id = sse.id
+
+                # Track retry interval from server
+                if sse.retry is not None:
+                    retry_interval_ms = sse.retry
+
+                is_complete = await self._handle_sse_event(
+                    sse,
+                    ctx.read_stream_writer,
+                    original_request_id=original_request_id,
+                    resumption_callback=(ctx.metadata.on_resumption_token_update if ctx.metadata else None),
+                )
+                # If the SSE event indicates completion, like returning response/error
+                # break the loop
+                if is_complete:
+                    await response.aclose()
+                    return  # Normal completion, no reconnect needed
+        except Exception:
+            logger.debug("SSE stream ended", exc_info=True)  # pragma: lax no cover
+
+        # Stream ended without response - reconnect if we received an event with ID
+        if last_event_id is not None:
+            logger.info("SSE stream disconnected, reconnecting...")
+            await self._handle_reconnection(ctx, last_event_id, retry_interval_ms)
+        else:
+            # Not resumable: resolve the waiter, else a listen stream's consumer
+            # would hang forever instead of learning the subscription is lost.
+            await self._resolve_abandoned_request(
+                ctx.read_stream_writer, original_request_id, "SSE stream ended without a response"
+            )
+
+    async def _resolve_abandoned_request(
+        self, read_stream_writer: StreamWriter, request_id: RequestId, message: str, *, code: int = CONNECTION_CLOSED
+    ) -> None:
+        """Resolve a request whose response can never arrive with a synthesized error.
+
+        Best-effort: a closed read stream means the session is tearing down.
+        """
+        error_data = ErrorData(code=code, message=message)
+        error_msg = SessionMessage(JSONRPCError(jsonrpc="2.0", id=request_id, error=error_data))
+        try:
+            await read_stream_writer.send(error_msg)
+        except (anyio.BrokenResourceError, anyio.ClosedResourceError):
+            logger.debug("read stream closed before request %r could be resolved", request_id)
+
+    async def _handle_reconnection(
+        self,
+        ctx: RequestContext,
+        last_event_id: str,
+        retry_interval_ms: int | None = None,
+        attempt: int = 0,
+    ) -> None:
+        """Reconnect with Last-Event-ID to resume stream after server disconnect."""
+        # Only requests reconnect: every caller arrives from a request's response stream.
+        assert isinstance(ctx.session_message.message, JSONRPCRequest)
+        original_request_id = ctx.session_message.message.id
+
+        if attempt >= MAX_RECONNECTION_ATTEMPTS:
+            # Resolve on give-up: a request with no read timeout (a listen
+            # stream) would otherwise hang its caller forever.
+            logger.debug(f"Max reconnection attempts ({MAX_RECONNECTION_ATTEMPTS}) exceeded")
+            await self._resolve_abandoned_request(
+                ctx.read_stream_writer, original_request_id, "SSE stream ended and reconnection attempts were exhausted"
+            )
+            return
+
+        # Always wait - use server value or default
+        delay_ms = retry_interval_ms if retry_interval_ms is not None else DEFAULT_RECONNECTION_DELAY_MS
+        await anyio.sleep(delay_ms / 1000.0)
+
+        headers = self._prepare_headers()
+        headers[LAST_EVENT_ID] = last_event_id
+
+        try:
+            async with ctx.client.sse(self.url, headers=headers) as event_source:
+                event_source.response.raise_for_status()
+                logger.info("Reconnected to SSE stream")
+
+                # Track for potential further reconnection
+                reconnect_last_event_id: str = last_event_id
+                reconnect_retry_ms = retry_interval_ms
+
+                async for sse in event_source:
+                    if sse.id:  # pragma: no branch
+                        reconnect_last_event_id = sse.id
+                    if sse.retry is not None:
+                        reconnect_retry_ms = sse.retry
+
+                    is_complete = await self._handle_sse_event(
+                        sse,
+                        ctx.read_stream_writer,
+                        original_request_id,
+                        ctx.metadata.on_resumption_token_update if ctx.metadata else None,
+                    )
+                    if is_complete:
+                        await event_source.response.aclose()
+                        return
+
+                # Stream ended again without response - reconnect again (reset attempt counter)
+                logger.info("SSE stream disconnected, reconnecting...")
+                await self._handle_reconnection(ctx, reconnect_last_event_id, reconnect_retry_ms, 0)
+        except Exception as e:  # pragma: no cover
+            logger.debug(f"Reconnection failed: {e}")
+            # Try to reconnect again if we still have an event ID
+            await self._handle_reconnection(ctx, last_event_id, retry_interval_ms, attempt + 1)
+
+    async def post_writer(
+        self,
+        client: httpx2.AsyncClient,
+        write_stream_reader: StreamReader,
+        read_stream_writer: StreamWriter,
+        write_stream: ContextSendStream[SessionMessage],
+        start_get_stream: Callable[[], None],
+        tg: TaskGroup,
+    ) -> None:
+        """Handle writing requests to the server."""
+        try:
+            async with write_stream_reader, read_stream_writer, write_stream:
+
+                async def _handle_message(session_message: SessionMessage) -> None:
+                    message = session_message.message
+                    if self._consume_modern_cancellation(session_message):
+                        return
+                    metadata = (
+                        session_message.metadata
+                        if isinstance(session_message.metadata, ClientMessageMetadata)
+                        else None
+                    )
+
+                    # Check if this is a resumption request
+                    is_resumption = bool(metadata and metadata.resumption_token)
+
+                    logger.debug(f"Sending client message: {message}")
+
+                    # Handle initialized notification
+                    if self._is_initialized_notification(message):
+                        start_get_stream()
+
+                    if self._is_initialization_request(message):
+                        # `initialize` is the negotiation, not a "subsequent request" — discard any
+                        # probe-stamped value so the discover→fallback path can't leak it onto the handshake.
+                        self._protocol_version_header = None
+                    elif metadata is not None and metadata.headers is not None:
+                        stamped_version = metadata.headers.get(MCP_PROTOCOL_VERSION_HEADER)
+                        if stamped_version is not None:
+                            self._protocol_version_header = stamped_version
+
+                    ctx = RequestContext(
+                        client=client,
+                        session_id=self.session_id,
+                        session_message=session_message,
+                        metadata=metadata,
+                        read_stream_writer=read_stream_writer,
+                    )
+
+                    async def handle_request_async():
+                        if is_resumption:
+                            await self._handle_resumption_request(ctx)
+                        else:
+                            await self._handle_post_request(ctx)
+
+                    # If this is a request, start a new task to handle it
+                    if isinstance(message, JSONRPCRequest):
+                        # Register the abort scope before the spawn: the next
+                        # message through this loop can already be the abandon
+                        # signal for this id, ahead of the task ever running.
+                        post = _InFlightPost(
+                            scope=anyio.CancelScope(),
+                            modern=self._protocol_version_header in MODERN_PROTOCOL_VERSIONS,
+                        )
+                        superseded = self._in_flight_posts.get(message.id)
+                        if superseded is not None:
+                            # A reused id means the waiter belongs to this attempt now:
+                            # sever the old POST so its zombie stream cannot answer,
+                            # fail, or resolve the successor's request.
+                            superseded.scope.cancel()
+                        self._in_flight_posts[message.id] = post
+                        tg.start_soon(self._run_request_post, handle_request_async, post, message.id)
+                    else:
+                        await handle_request_async()
+
+                async for session_message in write_stream_reader:
+                    sender_ctx = write_stream_reader.last_context
+                    if sender_ctx is not None:
+                        async with anyio.create_task_group() as tg_local:
+                            sender_ctx.run(tg_local.start_soon, _handle_message, session_message)
+                    else:
+                        await _handle_message(session_message)  # pragma: no cover
+
+        except Exception:  # pragma: lax no cover
+            logger.exception("Error in post_writer")
+
+    async def terminate_session(self, client: httpx2.AsyncClient) -> None:
+        """Terminate the session by sending a DELETE request."""
+        if not self.session_id:
+            return  # pragma: no cover
+
+        try:
+            headers = self._prepare_headers()
+            response = await client.delete(self.url, headers=headers)
+
+            if response.status_code == 405:
+                logger.debug("Server does not allow session termination")
+            elif response.status_code not in (200, 204):
+                logger.warning(f"Session termination failed: {response.status_code}")  # pragma: no cover
+        except Exception as exc:  # pragma: no cover
+            logger.warning(f"Session termination failed: {exc}")
+
+
+@asynccontextmanager
+async def streamable_http_client(
+    url: str,
+    *,
+    http_client: httpx2.AsyncClient | None = None,
+    terminate_on_close: bool = True,
+) -> AsyncGenerator[TransportStreams, None]:
+    """Client transport for StreamableHTTP.
+
+    Args:
+        url: The MCP server endpoint URL.
+        http_client: Optional pre-configured httpx2.AsyncClient. If None, a default
+            client with recommended MCP timeouts will be created. To configure headers,
+            authentication, or other HTTP settings, create an httpx2.AsyncClient and pass it here.
+        terminate_on_close: If True, send a DELETE request to terminate the session when the context exits.
+
+    Yields:
+        Tuple containing:
+            - read_stream: Stream for reading messages from the server
+            - write_stream: Stream for sending messages to the server
+
+    Example:
+        See examples/snippets/clients/ for usage patterns.
+    """
+    # Determine if we need to create and manage the client
+    client_provided = http_client is not None
+    client = http_client
+
+    if client is None:
+        # Create default client with recommended MCP timeouts
+        client = create_mcp_http_client()
+
+    transport = StreamableHTTPTransport(url)
+
+    logger.debug(f"Connecting to StreamableHTTP endpoint: {url}")
+
+    async with contextlib.AsyncExitStack() as stack:
+        # Only manage client lifecycle if we created it
+        if not client_provided:
+            await stack.enter_async_context(client)
+
+        read_stream_writer, read_stream = create_context_streams[SessionMessage | Exception](0)
+        write_stream, write_stream_reader = create_context_streams[SessionMessage](0)
+
+        async with (
+            read_stream_writer,
+            read_stream,
+            write_stream,
+            write_stream_reader,
+            anyio.create_task_group() as tg,
+        ):
+
+            def start_get_stream() -> None:
+                tg.start_soon(transport.handle_get_stream, client, read_stream_writer)
+
+            tg.start_soon(
+                transport.post_writer,
+                client,
+                write_stream_reader,
+                read_stream_writer,
+                write_stream,
+                start_get_stream,
+                tg,
+            )
+
+            try:
+                yield read_stream, write_stream
+            finally:
+                if transport.session_id and terminate_on_close:
+                    await transport.terminate_session(client)
+                tg.cancel_scope.cancel()
+        await resync_tracer()

.mcp-venv/lib/python3.13/site-packages/mcp/client/subscriptions.py

@@ -0,0 +1,282 @@
+"""Client-side `subscriptions/listen` driver (2026-07-28, SEP-2575).
+
+`listen()` opens the stream as an async context manager: entering waits for
+the server's acknowledgment, iteration yields typed change events, a graceful
+server close ends the loop, and an abrupt drop raises `SubscriptionLost`.
+There is no replay and no automatic re-listen: a client that re-opens a
+subscription refetches what it depends on.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Awaitable, Callable, Sequence
+from contextlib import asynccontextmanager
+from itertools import count
+from typing import TYPE_CHECKING, Literal
+
+import anyio
+import mcp_types as types
+from mcp_types.version import MODERN_PROTOCOL_VERSIONS
+
+from mcp.shared.dispatcher import CallOptions
+from mcp.shared.exceptions import MCPError
+from mcp.shared.subscriptions import (
+    PromptsListChanged,
+    ResourcesListChanged,
+    ResourceUpdated,
+    ServerEvent,
+    ToolsListChanged,
+    event_matches,
+)
+
+if TYPE_CHECKING:
+    from mcp.client.session import ClientSession
+
+__all__ = [
+    "ListenNotSupportedError",
+    "OnEvent",
+    "PromptsListChanged",
+    "ResourceUpdated",
+    "ResourcesListChanged",
+    "ServerEvent",
+    "Subscription",
+    "SubscriptionLost",
+    "ToolsListChanged",
+    "listen",
+]
+
+_listen_ids = count(1)
+"""Process-wide `listen-N` sequence: string ids can never collide with a dispatcher's minted ints."""
+
+_MAX_PENDING_EVENTS = 1024
+"""Backlog backstop: the spec allows sub-resource URIs, so distinct pending
+`ResourceUpdated` events are unbounded; overflowing this cap settles the
+subscription lost rather than growing client memory."""
+
+_SubscriptionEnd = Literal["graceful", "lost", "local"]
+
+
+class ListenNotSupportedError(RuntimeError):
+    """`subscriptions/listen` requires a 2026-07-28 connection."""
+
+    def __init__(self, negotiated_version: str | None) -> None:
+        self.negotiated_version = negotiated_version
+        super().__init__(
+            f"subscriptions/listen is not available at protocol version {negotiated_version!r}; it requires "
+            "2026-07-28. On earlier versions use subscribe_resource() and the change notifications delivered "
+            "through message_handler."
+        )
+
+
+class SubscriptionLost(RuntimeError):
+    """The stream ended without the server's graceful close; re-listen and refetch."""
+
+
+class ListenRoute:
+    """Package-internal demux state for one listen stream, fed synchronously in receive order by the session."""
+
+    def __init__(self) -> None:
+        self.honored: types.SubscriptionFilter | None = None
+        self.acked = anyio.Event()
+        self.error: MCPError | None = None
+        self.end: _SubscriptionEnd | None = None
+        self._honored_uris: frozenset[str] = frozenset()
+        self._pending: dict[ServerEvent, None] = {}
+        self._wake = anyio.Event()
+
+    def set_acked(self, honored: types.SubscriptionFilter) -> None:
+        """Record the acknowledged filter; the first ack wins."""
+        if not self.acked.is_set():
+            self.honored = honored
+            self._honored_uris = frozenset(honored.resource_subscriptions or ())
+            self.acked.set()
+
+    def deliver(self, event: ServerEvent) -> None:
+        """Queue an event within the honored filter, deduplicated against the backlog.
+
+        Any `ResourceUpdated` is admitted once URI subscriptions were honored at
+        all: the spec allows the stamped URI to be a sub-resource of a subscribed one.
+        """
+        if self.end is not None or self.honored is None:
+            return
+        if isinstance(event, ResourceUpdated):
+            admitted = bool(self._honored_uris)
+        else:
+            admitted = event_matches(self.honored, self._honored_uris, event)
+        if not admitted or event in self._pending:
+            return
+        if len(self._pending) >= _MAX_PENDING_EVENTS:
+            self.settle(
+                "lost",
+                error=MCPError(
+                    types.INTERNAL_ERROR,
+                    f"subscription backlog exceeded {_MAX_PENDING_EVENTS} unconsumed events; re-listen and refetch",
+                ),
+            )
+            return
+        self._pending[event] = None
+        self._wake.set()
+
+    def settle(self, end: _SubscriptionEnd, error: MCPError | None = None) -> None:
+        """Record the stream's end; the first reason wins and wakes both waiters."""
+        if self.end is None:
+            self.end = end
+            self.error = error
+            self.acked.set()
+            self._wake.set()
+
+    async def next_event(self) -> ServerEvent | _SubscriptionEnd:
+        """Peek the next pending event, or the stream's end once the backlog drains.
+
+        A "local" end short-circuits the backlog; the other endings drain it first,
+        so a graceful close never swallows events that preceded it.
+        """
+        while True:
+            # Snapshot the wake event before checking state so a deliver landing after the checks cannot be missed.
+            wake = self._wake
+            if self.end == "local":
+                return self.end
+            if self._pending:
+                return next(iter(self._pending))
+            if self.end is not None:
+                return self.end
+            await wake.wait()
+            self._wake = anyio.Event()
+
+    def consume(self, event: ServerEvent) -> None:
+        """Remove a peeked event from the backlog."""
+        self._pending.pop(event, None)
+
+
+OnEvent = Callable[[ServerEvent], Awaitable[None]]
+"""Per-event barrier awaited before a `Subscription` returns each event to its consumer."""
+
+
+class Subscription:
+    """One open `subscriptions/listen` stream: an async iterator of typed events.
+
+    Produced by `listen()` / `Client.listen()`, not constructed directly.
+    """
+
+    def __init__(
+        self,
+        route: ListenRoute,
+        subscription_id: types.RequestId,
+        honored: types.SubscriptionFilter,
+        on_event: OnEvent | None = None,
+    ):
+        self._route = route
+        self._on_event = on_event
+        self.subscription_id = subscription_id
+        """The listen request's JSON-RPC id, stamped into every frame's `_meta`."""
+        self.honored = honored
+        """The subset of the requested filter the server agreed to deliver."""
+
+    def __aiter__(self) -> Subscription:
+        return self
+
+    async def __anext__(self) -> ServerEvent:
+        """Yield the next change event; the loop ends when the stream does.
+
+        Raises:
+            SubscriptionLost: the stream dropped without the server's graceful close.
+        """
+        outcome = await self._route.next_event()
+        if isinstance(outcome, str):
+            if outcome == "lost":
+                raise SubscriptionLost(
+                    f"subscription {self.subscription_id!r} ended without the server's graceful close;"
+                    " re-listen and refetch"
+                ) from self._route.error
+            raise StopAsyncIteration
+        if self._on_event is not None:
+            # The event stays pending while the barrier runs: a cancellation or a
+            # raising barrier leaves it for the next anext instead of dropping it.
+            await self._on_event(outcome)
+        self._route.consume(outcome)
+        return outcome
+
+
+@asynccontextmanager
+async def listen(
+    session: ClientSession,
+    *,
+    tools_list_changed: bool = False,
+    prompts_list_changed: bool = False,
+    resources_list_changed: bool = False,
+    resource_subscriptions: Sequence[str] = (),
+    on_event: OnEvent | None = None,
+) -> AsyncIterator[Subscription]:
+    """Open one `subscriptions/listen` stream on `session` (2026-07-28 only).
+
+    Entering sends the request and returns once the server's acknowledgment
+    arrives; exiting ends the subscription. `on_event` is awaited before each
+    event is returned - the seam `Client.listen` uses to finish cache eviction
+    before the consumer can refetch.
+
+    Raises:
+        ListenNotSupportedError: negotiated version predates 2026-07-28.
+        MCPError: the server rejected the request, or the connection failed pre-ack.
+        SubscriptionLost: the stream ended before it was acknowledged.
+        TimeoutError: the session's read timeout elapsed before the acknowledgment.
+    """
+    if session.protocol_version not in MODERN_PROTOCOL_VERSIONS:
+        raise ListenNotSupportedError(session.protocol_version)
+    if isinstance(resource_subscriptions, str):
+        raise TypeError("resource_subscriptions takes a sequence of URIs, not a bare string")
+    request = types.SubscriptionsListenRequest(
+        params=types.SubscriptionsListenRequestParams(
+            notifications=types.SubscriptionFilter(
+                tools_list_changed=tools_list_changed or None,
+                prompts_list_changed=prompts_list_changed or None,
+                resources_list_changed=resources_list_changed or None,
+                resource_subscriptions=list(resource_subscriptions) or None,
+            )
+        )
+    )
+    task_group = session._task_group  # pyright: ignore[reportPrivateUsage]
+    if task_group is None:
+        raise RuntimeError("listen() requires an entered session")
+    request_id: types.RequestId = f"listen-{next(_listen_ids)}"
+    data = request.model_dump(by_alias=True, mode="json", exclude_none=True)
+    opts: CallOptions = {"request_id": request_id}
+    session._stamp(data, opts)  # pyright: ignore[reportPrivateUsage]
+    driver_scope = anyio.CancelScope()
+
+    async def drive() -> None:
+        # Deliberately no result timeout: the response arrives when the stream ends.
+        with driver_scope:
+            try:
+                await session._dispatcher.send_raw_request(  # pyright: ignore[reportPrivateUsage]
+                    data["method"], data.get("params"), opts
+                )
+            except MCPError as error:
+                route.settle("lost", error=error)
+                return
+            except ValueError as error:
+                # A raw request id collided with our minted listen id: fail this subscription
+                # and release the route in this same slice, so it cannot consume the raw caller's ack.
+                session._unregister_listen_route(request_id)  # pyright: ignore[reportPrivateUsage]
+                route.settle("lost", error=MCPError(types.INTERNAL_ERROR, str(error)))
+                return
+            # A result, whatever its body, is the spec's graceful close; with no prior ack
+            # it opens the subscription already closed.
+            route.set_acked(types.SubscriptionFilter())
+            route.settle("graceful")
+
+    # Register the demux route before the request is written so the ack cannot race it.
+    route = session._register_listen_route(request_id)  # pyright: ignore[reportPrivateUsage]
+    try:
+        task_group.start_soon(drive)
+        with anyio.fail_after(session._session_read_timeout_seconds):  # pyright: ignore[reportPrivateUsage]
+            await route.acked.wait()
+        if route.honored is None:
+            # Only reachable on failure paths: a graceful no-ack result acked an empty filter in drive().
+            if route.error is not None:
+                raise route.error
+            raise SubscriptionLost(f"subscription {request_id!r} ended before it was acknowledged")
+        yield Subscription(route, request_id, route.honored, on_event)
+    finally:
+        route.settle("local")
+        driver_scope.cancel()
+        session._unregister_listen_route(request_id)  # pyright: ignore[reportPrivateUsage]

.mcp-venv/lib/python3.13/site-packages/mcp/os/__init__.py

@@ -0,0 +1 @@
+"""Platform-specific utilities for MCP."""

.mcp-venv/lib/python3.13/site-packages/mcp/os/posix/__init__.py

@@ -0,0 +1 @@
+"""POSIX-specific utilities for MCP."""

.mcp-venv/lib/python3.13/site-packages/mcp/os/posix/utilities.py

@@ -0,0 +1,63 @@
+"""POSIX-specific functionality for stdio client operations."""
+
+import logging
+import os
+import signal
+from contextlib import suppress
+
+import anyio
+from anyio.abc import Process
+
+logger = logging.getLogger(__name__)
+
+# How often to probe for surviving group members between SIGTERM and SIGKILL.
+_GROUP_POLL_INTERVAL = 0.01
+
+
+async def terminate_posix_process_tree(process: Process, timeout_seconds: float = 2.0) -> None:
+    """Terminates a process and all its descendants on POSIX.
+
+    SIGTERMs the process group, waits up to timeout_seconds for it to
+    disappear, then SIGKILLs whatever remains. killpg reaches every descendant
+    atomically, even ones whose parent already exited; daemonizers that left
+    the group escape by design. A group only disappears once every member is
+    dead and reaped, so a client running as PID 1 should reap orphans (e.g.
+    docker run --init) or the wait below runs its full timeout.
+    """
+    # The leader's pid is the pgid (start_new_session). Never use getpgid():
+    # it fails once the leader is reaped, even with live members left.
+    pgid = process.pid
+
+    try:
+        os.killpg(pgid, signal.SIGTERM)
+    except ProcessLookupError:
+        return  # the whole group is already gone
+    except PermissionError:
+        # EPERM never proves the group is gone (macOS raises it for zombie or
+        # foreign-euid members), so keep waiting and escalating.
+        logger.warning(
+            "No permission to signal some of process group %d; waiting for it to exit anyway", pgid, exc_info=True
+        )
+
+    with anyio.move_on_after(timeout_seconds):
+        while _group_alive(pgid):
+            # Reading returncode reaps the leader on trio; a zombie leader would
+            # otherwise keep the group alive for the full timeout.
+            _ = process.returncode
+            await anyio.sleep(_GROUP_POLL_INTERVAL)
+        return
+
+    # ESRCH: died since the last probe. EPERM: we killed what we were allowed to.
+    with suppress(ProcessLookupError, PermissionError):
+        os.killpg(pgid, signal.SIGKILL)
+
+
+def _group_alive(pgid: int) -> bool:
+    """Probes the group with signal 0; only ESRCH proves it is gone."""
+    try:
+        os.killpg(pgid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        pass  # unsignalable survivors or unreaped zombies; EPERM is ambiguous
+    return True

.mcp-venv/lib/python3.13/site-packages/mcp/os/win32/__init__.py

@@ -0,0 +1 @@
+"""Windows-specific utilities for MCP."""

.mcp-venv/lib/python3.13/site-packages/mcp/os/win32/utilities.py

@@ -0,0 +1,292 @@
+"""Windows-specific functionality for stdio transport operations."""
+
+import logging
+import shutil
+import subprocess
+import sys
+import weakref
+from contextlib import suppress
+from pathlib import Path
+from typing import BinaryIO, TextIO, TypeAlias, cast
+
+import anyio
+from anyio.abc import Process
+from anyio.streams.file import FileReadStream, FileWriteStream
+
+logger = logging.getLogger(__name__)
+
+# Windows-specific imports for Job Objects
+if sys.platform == "win32":
+    import msvcrt
+
+    import pywintypes
+    import win32api
+    import win32con
+    import win32job
+else:
+    # Type stubs for non-Windows platforms
+    win32api = None
+    win32con = None
+    msvcrt = None
+    win32job = None
+    pywintypes = None
+
+
+def rebind_std_handle_to_fd(fd: int) -> None:
+    """Points the Win32 standard-handle slot for fd 0, 1, or 2 at fd's current OS handle.
+
+    os.dup2 updates only the CRT descriptor table; subprocess handle inheritance
+    reads the Win32 slot, so it must be repointed too.
+
+    Raises:
+        OSError: The slot could not be set.
+    """
+    if sys.platform != "win32" or not win32api or not msvcrt or not pywintypes:
+        return
+    std_ids = {0: win32api.STD_INPUT_HANDLE, 1: win32api.STD_OUTPUT_HANDLE, 2: win32api.STD_ERROR_HANDLE}
+    try:
+        win32api.SetStdHandle(std_ids[fd], msvcrt.get_osfhandle(fd))
+    except pywintypes.error as exc:
+        # Normalized so callers' OSError-based best-effort handling covers it.
+        raise OSError(f"SetStdHandle failed for fd {fd}") from exc
+
+
+# How often FallbackProcess polls the underlying Popen for exit.
+_EXIT_POLL_INTERVAL = 0.01
+
+# Job Object handle per spawned process, for tree termination at shutdown.
+# Values stay pywin32 PyHANDLEs: if no pop site ever runs, the dying weak entry
+# drops the last reference and the PyHANDLE destructor closes the handle, which
+# is what makes KILL_ON_JOB_CLOSE reap an abandoned tree.
+_process_jobs: "weakref.WeakKeyDictionary[Process | FallbackProcess, object]" = weakref.WeakKeyDictionary()
+
+
+def get_windows_executable_command(command: str) -> str:
+    """Resolves the command to a Windows executable path.
+
+    Tries the bare name first, then the common script extensions (.cmd, .bat,
+    .exe, .ps1).
+    """
+    try:
+        if command_path := shutil.which(command):
+            return command_path
+
+        for ext in [".cmd", ".bat", ".exe", ".ps1"]:
+            ext_version = f"{command}{ext}"
+            if ext_path := shutil.which(ext_version):
+                return ext_path
+
+        return command
+    except OSError:
+        return command  # path probing failed (permissions, broken symlinks)
+
+
+class FallbackProcess:
+    """Async wrapper around subprocess.Popen for SelectorEventLoop.
+
+    Windows event loops without async subprocess support get this Popen-backed
+    fallback, with anyio file streams wrapping the pipes.
+    """
+
+    def __init__(self, popen_obj: subprocess.Popen[bytes]) -> None:
+        self.popen: subprocess.Popen[bytes] = popen_obj
+        stdin = popen_obj.stdin
+        stdout = popen_obj.stdout
+
+        self.stdin = FileWriteStream(cast(BinaryIO, stdin)) if stdin else None
+        self.stdout = FileReadStream(cast(BinaryIO, stdout)) if stdout else None
+
+    async def wait(self) -> int:
+        """Waits for exit by polling the Popen.
+
+        A thread blocked in Popen.wait() cannot be cancelled by anyio, which
+        would defeat every timeout placed around this call.
+        """
+        while (returncode := self.popen.poll()) is None:
+            await anyio.sleep(_EXIT_POLL_INTERVAL)
+        return returncode
+
+    def terminate(self) -> None:
+        """Terminates the subprocess."""
+        self.popen.terminate()
+
+    def kill(self) -> None:
+        """Kills the subprocess (on Windows the same hard kill as terminate)."""
+        self.popen.kill()
+
+    @property
+    def pid(self) -> int:
+        """Returns the process ID."""
+        return self.popen.pid
+
+    @property
+    def returncode(self) -> int | None:
+        """The exit code, or None while the process is still running.
+
+        Polls the Popen so death is observable without anyone calling wait().
+        """
+        return self.popen.poll()
+
+
+# The process handle stdio_client drives: anyio's Process, or the Popen-backed
+# fallback used on Windows event loops without async subprocess support.
+ServerProcess: TypeAlias = Process | FallbackProcess
+
+
+async def create_windows_process(
+    command: str,
+    args: list[str],
+    env: dict[str, str] | None = None,
+    errlog: TextIO | None = sys.stderr,
+    cwd: Path | str | None = None,
+) -> Process | FallbackProcess:
+    """Creates a subprocess with Job Object support for tree termination.
+
+    Spawns via anyio's open_process; event loops without async subprocess
+    support (notably the SelectorEventLoop) raise NotImplementedError, in which
+    case the spawn falls back to a Popen-backed FallbackProcess. Either way the
+    process is then assigned to a Job Object so its children can be terminated
+    with it; children spawned before the assignment completes are not captured
+    (see the inline note below).
+
+    Returns:
+        Process | FallbackProcess: The spawned process with async stdin/stdout streams.
+    """
+    try:
+        process = await anyio.open_process(
+            [command, *args],
+            env=env,
+            # Ensure we don't create console windows for each process
+            creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0),
+            stderr=errlog,
+            cwd=cwd,
+        )
+    except NotImplementedError:
+        # Windows event loops without async subprocess support (SelectorEventLoop)
+        process = await _create_windows_fallback_process(command, args, env, errlog, cwd)
+
+    # Children spawned before the assignment completes land outside the job
+    # (membership is inherited at CreateProcess, never acquired retroactively);
+    # if that ever bites, the fix is a CREATE_SUSPENDED spawn -> assign -> resume.
+    job = _create_job_object()
+    _maybe_assign_process_to_job(process, job)
+    return process
+
+
+async def _create_windows_fallback_process(
+    command: str,
+    args: list[str],
+    env: dict[str, str] | None = None,
+    errlog: TextIO | None = sys.stderr,
+    cwd: Path | str | None = None,
+) -> FallbackProcess:
+    """Spawns via subprocess.Popen and wraps it in FallbackProcess."""
+    popen_obj = subprocess.Popen(
+        [command, *args],
+        stdin=subprocess.PIPE,
+        stdout=subprocess.PIPE,
+        stderr=errlog,
+        env=env,
+        cwd=cwd,
+        bufsize=0,  # Unbuffered output
+        creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0),
+    )
+    return FallbackProcess(popen_obj)
+
+
+def _create_job_object() -> object | None:
+    """Creates a Windows Job Object configured to terminate all its processes when closed."""
+    if sys.platform != "win32" or not win32api or not win32job:
+        return None
+
+    job = None
+    try:
+        job = win32job.CreateJobObject(None, "")
+        extended_info = win32job.QueryInformationJobObject(job, win32job.JobObjectExtendedLimitInformation)
+
+        extended_info["BasicLimitInformation"]["LimitFlags"] |= win32job.JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE
+        win32job.SetInformationJobObject(job, win32job.JobObjectExtendedLimitInformation, extended_info)
+        return job
+    except pywintypes.error:
+        logger.warning("Failed to create Job Object for process tree management", exc_info=True)
+        # If creation succeeded but configuration failed, close the handle now.
+        if job is not None:
+            _close_job_handle(job)
+        return None
+
+
+def _maybe_assign_process_to_job(process: Process | FallbackProcess, job: object | None) -> None:
+    """Assigns the process to the job and records it for tree termination.
+
+    On any failure the job handle is closed instead.
+    """
+    if job is None:
+        return
+
+    if sys.platform != "win32" or not win32api or not win32con or not win32job:
+        return
+
+    try:
+        process_handle = win32api.OpenProcess(
+            win32con.PROCESS_SET_QUOTA | win32con.PROCESS_TERMINATE, False, process.pid
+        )
+        if not process_handle:
+            raise pywintypes.error(0, "OpenProcess", "Failed to open process handle")
+
+        try:
+            win32job.AssignProcessToJobObject(job, process_handle)
+        finally:
+            win32api.CloseHandle(process_handle)
+        # Record only after the CloseHandle above succeeded: had it failed, the
+        # except below would close the job and KILL_ON_JOB_CLOSE takes the server.
+        _process_jobs[process] = job
+    except pywintypes.error:
+        logger.warning("Failed to assign process %d to Job Object", process.pid, exc_info=True)
+        _close_job_handle(job)
+
+
+def close_process_job(process: Process | FallbackProcess) -> None:
+    """Closes the process's Job Object handle, if it still has one.
+
+    KILL_ON_JOB_CLOSE makes the close also kill any members still alive,
+    deterministically rather than at GC time; a deliberate divergence from
+    POSIX, where a graceful server's children are left alive.
+    """
+    if sys.platform != "win32":
+        return
+
+    job = _process_jobs.pop(process, None)
+    if job is not None:
+        _close_job_handle(job)
+
+
+async def terminate_windows_process_tree(process: Process | FallbackProcess) -> None:
+    """Terminates the process's job, or just the process if it has no job.
+
+    Job termination is an immediate hard kill of every member. Windows has no
+    tree-wide SIGTERM; the stdin-close grace period is the server's chance to
+    exit cleanly.
+    """
+    if sys.platform != "win32":
+        return
+
+    job = _process_jobs.pop(process, None)
+    if job is not None and win32job:
+        try:
+            with suppress(pywintypes.error):  # the job might already be terminated
+                win32job.TerminateJobObject(job, 1)
+        finally:
+            _close_job_handle(job)
+
+    # The process may have no job (creation or assignment failed); kill it directly too.
+    try:
+        process.terminate()
+    except OSError:
+        pass
+
+
+def _close_job_handle(job: object) -> None:
+    """Closes a Job Object handle, tolerating one that is already closed."""
+    if win32api and pywintypes:
+        with suppress(pywintypes.error):
+            win32api.CloseHandle(job)

.mcp-venv/lib/python3.13/site-packages/mcp/server/__init__.py

@@ -0,0 +1,7 @@
+from .caching import CacheHint
+from .context import ServerRequestContext
+from .lowlevel import NotificationOptions, Server
+from .mcpserver import MCPServer
+from .models import InitializationOptions
+
+__all__ = ["CacheHint", "Server", "ServerRequestContext", "MCPServer", "NotificationOptions", "InitializationOptions"]

.mcp-venv/lib/python3.13/site-packages/mcp/server/__main__.py

@@ -0,0 +1,24 @@
+import logging
+import sys
+import warnings
+
+import anyio
+
+from mcp.server.lowlevel.server import Server
+from mcp.server.stdio import stdio_server
+
+if not sys.warnoptions:
+    warnings.simplefilter("ignore")
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger("server")
+
+
+async def main() -> None:
+    server: Server[dict[str, object]] = Server("mcp")
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(read_stream, write_stream, server.create_initialization_options())
+
+
+if __name__ == "__main__":
+    anyio.run(main, backend="trio")

.mcp-venv/lib/python3.13/site-packages/mcp/server/_otel.py

@@ -0,0 +1,72 @@
+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
+
+
+class OpenTelemetryMiddleware(ServerMiddleware[Any]):
+    """Context-tier middleware that wraps each inbound message in an OpenTelemetry span."""
+
+    async def __call__(self, ctx: ServerRequestContext[Any, Any], call_next: CallNext) -> HandlerResult:
+        name = ctx.params.get("name") if ctx.params else None
+        target = name if isinstance(name, str) else None
+
+        attributes: dict[str, Any] = {
+            "mcp.method.name": ctx.method,
+            "mcp.protocol.version": ctx.protocol_version,
+        }
+        if ctx.request_id is not None:
+            attributes["jsonrpc.request.id"] = str(ctx.request_id)
+
+        if ctx.method == "tools/call":
+            attributes["gen_ai.operation.name"] = "execute_tool"
+            if target is not None:
+                attributes["gen_ai.tool.name"] = target
+        elif ctx.method == "prompts/get" and target is not None:
+            attributes["gen_ai.prompt.name"] = target
+
+        with otel_span(
+            name=f"{ctx.method}{f' {target}' if target else ''}",
+            kind=SpanKind.SERVER,
+            attributes=attributes,
+            context=extract_trace_context(ctx.meta),
+            record_exception=False,
+            set_status_on_exception=False,
+        ) as span:
+            try:
+                result = await call_next(ctx)
+            except MCPError as e:
+                code = str(e.error.code)
+                span.set_attributes({"error.type": code, "rpc.response.status_code": code})
+                span.set_status(StatusCode.ERROR, e.error.message)
+                raise
+            except ValidationError:
+                # Mirror the sanitized wire response; pydantic messages carry client input.
+                code = str(INVALID_PARAMS)
+                span.set_attributes({"error.type": code, "rpc.response.status_code": code})
+                span.set_status(StatusCode.ERROR, "Invalid request parameters")
+                raise
+            except Exception as e:
+                span.set_attribute("error.type", type(e).__qualname__)
+                span.record_exception(e)
+                span.set_status(StatusCode.ERROR, str(e))
+                raise
+            if ctx.method == "tools/call":
+                # Tool errors are detected pre-serialization, so only shapes that reach the wire as an error
+                # count: the model, or the camelCase alias (`is_error` is dropped by the alias-only wire
+                # validation). A raw-dict `isError` is matched as a literal bool only - non-bool coercible
+                # values (1, "true") would serialize to an error but are rare enough to leave undetected.
+                match result:
+                    case CallToolResult(is_error=True) | {"isError": True}:
+                        span.set_attribute("error.type", "tool_error")
+                        span.set_status(StatusCode.ERROR)
+                    case _:
+                        pass
+            return result

.mcp-venv/lib/python3.13/site-packages/mcp/server/_streamable_http_modern.py

@@ -0,0 +1,464 @@
+"""Single-exchange HTTP serving for protocol version 2026-07-28.
+
+Private module — entry is via `StreamableHTTPSessionManager.handle_request`.
+The legacy streamable-HTTP transport is untouched and remains the supported
+path for earlier protocol revisions.
+
+A 2026-07-28 request is a self-contained POST: no `initialize` handshake, no
+`Mcp-Session-Id`, one JSON-RPC request in, one JSON-RPC response out. JSON
+mode handles the request directly in the ASGI task. SSE mode runs the handler
+as a sibling task and defers committing to `text/event-stream` until the
+handler emits a notification or `_SSE_PING_INTERVAL` elapses, whichever
+comes first: a handler that completes (or raises) within that window without
+emitting still gets a JSON response with the table-mapped HTTP status, so
+the spec's `404`/`400` MUSTs hold for kernel-dispatch errors; a handler that
+runs silent past the window commits SSE so the keepalive ping can keep the
+connection open behind a proxy idle-read timeout.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import Awaitable, Mapping
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Final, cast
+
+import anyio
+from anyio.streams.memory import MemoryObjectSendStream
+from mcp_types import (
+    CLIENT_CAPABILITIES_META_KEY,
+    CLIENT_INFO_META_KEY,
+    HEADER_MISMATCH,
+    INVALID_REQUEST,
+    PARSE_ERROR,
+    PROTOCOL_VERSION_META_KEY,
+    ErrorData,
+    JSONRPCError,
+    JSONRPCNotification,
+    JSONRPCRequest,
+    JSONRPCResponse,
+    ProgressToken,
+    RequestId,
+)
+from mcp_types import methods as _methods
+from pydantic import ValidationError
+from starlette.requests import Request
+from starlette.responses import Response
+from starlette.types import Receive, Scope, Send
+
+from mcp.server.connection import Connection
+from mcp.server.runner import modern_error_data, serve_one
+from mcp.server.streamable_http import check_accept_headers
+from mcp.server.transport_security import TransportSecurityMiddleware, TransportSecuritySettings
+from mcp.shared.dispatcher import CallOptions
+from mcp.shared.exceptions import NoBackChannelError
+from mcp.shared.inbound import (
+    ERROR_CODE_HTTP_STATUS,
+    MCP_PARAM_HEADER_PREFIX,
+    InboundLadderRejection,
+    InboundModernRoute,
+    classify_inbound_request,
+    find_duplicated_routing_header,
+    validate_mcp_param_headers,
+)
+from mcp.shared.jsonrpc_dispatcher import progress_token_from_params
+from mcp.shared.message import MessageMetadata, ServerMessageMetadata
+from mcp.shared.transport_context import TransportContext
+
+if TYPE_CHECKING:
+    from mcp.server.lowlevel.server import Server
+
+logger = logging.getLogger(__name__)
+
+
+_OK_STATUS = 200
+
+
+@dataclass
+class _SingleExchangeDispatchContext:
+    """`DispatchContext` for one inbound HTTP request.
+
+    Structurally satisfies `mcp.shared.dispatcher.DispatchContext`. The
+    back-channel is closed by construction: a 2026-07-28 server cannot send
+    requests to the client. The SSE sink, when present, carries request-scoped
+    notifications onto this request's response stream.
+    """
+
+    transport: TransportContext
+    request_id: RequestId
+    message_metadata: MessageMetadata
+    progress_token: ProgressToken | None = None
+    sink: MemoryObjectSendStream[bytes] | None = None
+    cancel_requested: anyio.Event = field(default_factory=anyio.Event)
+    can_send_request: bool = field(default=False, init=False)
+
+    async def send_raw_request(
+        self,
+        method: str,
+        params: Mapping[str, Any] | None,
+        opts: CallOptions | None = None,
+    ) -> dict[str, Any]:
+        raise NoBackChannelError(method)
+
+    async def notify(self, method: str, params: Mapping[str, Any] | None, opts: CallOptions | None = None) -> None:
+        if self.sink is None:
+            return
+        body = dict(params) if params is not None else None
+        try:
+            await self.sink.send(_sse_event(JSONRPCNotification(jsonrpc="2.0", method=method, params=body)))
+        except (anyio.ClosedResourceError, anyio.BrokenResourceError):
+            logger.debug("dropped %s: response stream closed", method)
+
+    async def progress(self, progress: float, total: float | None = None, message: str | None = None) -> None:
+        if self.progress_token is None:
+            return
+        params: dict[str, Any] = {"progressToken": self.progress_token, "progress": progress}
+        if total is not None:
+            params["total"] = total
+        if message is not None:
+            params["message"] = message
+        await self.notify("notifications/progress", params)
+
+
+async def _to_jsonrpc_response(
+    request_id: RequestId, coro: Awaitable[dict[str, Any]]
+) -> JSONRPCResponse | JSONRPCError:
+    """Await ``coro`` and wrap its outcome as the JSON-RPC reply for ``request_id``.
+
+    The exception-to-wire boundary for the modern HTTP entry, composed around
+    `serve_one`: `modern_error_data` maps the shared ladder and surfaces
+    anything else as a generic `INTERNAL_ERROR` so handler internals never
+    reach the wire.
+    """
+    try:
+        result = await coro
+    except Exception as exc:
+        return JSONRPCError(jsonrpc="2.0", id=request_id, error=modern_error_data(exc))
+    return JSONRPCResponse(jsonrpc="2.0", id=request_id, result=result)
+
+
+_SSE_PING_INTERVAL: float = 15.0
+"""Seconds between SSE comment-line keepalives once `text/event-stream` has committed."""
+
+_SSE_HEADERS: Final[list[tuple[bytes, bytes]]] = [
+    (b"content-type", b"text/event-stream"),
+    (b"cache-control", b"no-cache, no-transform"),
+    (b"connection", b"keep-alive"),
+    (b"x-accel-buffering", b"no"),
+]
+
+
+def _sse_event(msg: JSONRPCResponse | JSONRPCError | JSONRPCNotification) -> bytes:
+    """Serialise a JSON-RPC message as one SSE `event: message` frame.
+
+    SSE mode begins after the handler has emitted, so a `JSONRPCError` here
+    always carries the request's id; the `id: null` case lives in `_write`.
+    """
+    body = msg.model_dump(mode="json", by_alias=True, exclude_none=True)
+    data = json.dumps(body, separators=(",", ":"))
+    return f"event: message\r\ndata: {data}\r\n\r\n".encode()
+
+
+async def _write_rejection(
+    rejection: InboundLadderRejection,
+    request_id: RequestId,
+    scope: Scope,
+    receive: Receive,
+    send: Send,
+) -> None:
+    """Send a ladder rejection as its JSON-RPC error with the table-mapped HTTP status."""
+    rej = JSONRPCError(
+        jsonrpc="2.0",
+        id=request_id,
+        error=ErrorData(code=rejection.code, message=rejection.message, data=rejection.data),
+    )
+    await _write(rej, scope, receive, send)
+
+
+async def _write(
+    msg: JSONRPCResponse | JSONRPCError,
+    scope: Scope,
+    receive: Receive,
+    send: Send,
+) -> None:
+    """Serialise a JSON-RPC reply with the table-mapped HTTP status."""
+    status = ERROR_CODE_HTTP_STATUS.get(msg.error.code, _OK_STATUS) if isinstance(msg, JSONRPCError) else _OK_STATUS
+    body = msg.model_dump(mode="json", by_alias=True, exclude_none=True)
+    if isinstance(msg, JSONRPCError) and msg.id is None:
+        # JSON-RPC requires `id: null` to appear on the wire when the request
+        # id couldn't be parsed; `exclude_none` would otherwise drop it.
+        body["id"] = None
+    await Response(
+        json.dumps(body, separators=(",", ":")),
+        status_code=status,
+        media_type="application/json",
+    )(scope, receive, send)
+
+
+_MCP_PARAM_PREFIX_LOWER: Final = MCP_PARAM_HEADER_PREFIX.lower()
+
+_MCP_PARAM_LIST_PAGE_CAP: Final = 100
+"""Page cap for the schema-resolving tools/list walk: a buggy paginator degrades to a logged skip, not a hang."""
+
+
+async def _tool_input_schema(
+    app: Server[Any],
+    request: Request,
+    request_id: RequestId,
+    verdict: InboundModernRoute,
+    lifespan_state: Any,
+    name: str,
+) -> Any | None:
+    """Resolve `name`'s inputSchema from the server's own registered `tools/list` handler.
+
+    The listing runs through the normal `serve_one` path, so a visibility-scoped
+    catalog yields exactly what *this* caller was advertised. Returns None
+    (caller skips validation) when the listing fails or never advertises the tool.
+    """
+    meta = {
+        PROTOCOL_VERSION_META_KEY: verdict.protocol_version,
+        CLIENT_CAPABILITIES_META_KEY: verdict.client_capabilities,
+    }
+    if verdict.client_info is not None:
+        # Optional key: a conforming pair-only caller omits it rather than sending null.
+        meta[CLIENT_INFO_META_KEY] = verdict.client_info
+    list_params: dict[str, Any] = {"_meta": meta}
+    try:
+        _methods.validate_client_request("tools/list", verdict.protocol_version, list_params)
+    except ValidationError:
+        # Client-fault envelope: the real dispatch produces the INVALID_PARAMS
+        # reply, and anything above a debug line would let clients flood the log.
+        logger.debug("Mcp-Param header validation skipped: the request envelope fails tools/list validation")
+        return None
+    seen_cursors: set[str] = set()
+    dctx = _SingleExchangeDispatchContext(
+        transport=TransportContext(kind="streamable-http", can_send_request=False, headers=request.headers),
+        request_id=request_id,
+        message_metadata=ServerMessageMetadata(request_context=request),
+    )
+    for _ in range(_MCP_PARAM_LIST_PAGE_CAP):
+        # Fresh Connection per page: serve_one tears down the connection's exit stack on the way out.
+        connection = Connection.from_envelope(
+            verdict.protocol_version, verdict.client_info, verdict.client_capabilities
+        )
+        try:
+            result = await serve_one(
+                app, dctx, "tools/list", list_params, connection=connection, lifespan_state=lifespan_state
+            )
+            for tool in result.get("tools", []):
+                if tool.get("name") == name:
+                    return tool.get("inputSchema")
+            cursor = result.get("nextCursor")
+        except Exception:
+            # Fail-open boundary by design: header validation must never break a
+            # working call path. Loud, precisely because the skip is fail-open.
+            logger.exception("Mcp-Param header validation skipped: the tools/list listing failed")
+            return None
+        if not isinstance(cursor, str):
+            # Listing exhausted without advertising `name`; dispatch owns rejecting an unknown tool.
+            return None
+        if cursor in seen_cursors:
+            logger.warning("Mcp-Param header validation skipped: the tools/list handler returned a cursor cycle")
+            return None
+        seen_cursors.add(cursor)
+        list_params = {"_meta": meta, "cursor": cursor}
+    logger.warning(
+        "Mcp-Param header validation skipped: tools/list pagination did not terminate within %d pages",
+        _MCP_PARAM_LIST_PAGE_CAP,
+    )
+    return None
+
+
+async def _mcp_param_rejection(
+    app: Server[Any],
+    request: Request,
+    req: JSONRPCRequest,
+    verdict: InboundModernRoute,
+    lifespan_state: Any,
+) -> InboundLadderRejection | None:
+    """Validate a `tools/call` request's `Mcp-Param-*` headers against the called tool's schema.
+
+    Runs pre-dispatch, before any SSE machinery, so a rejection is always a
+    plain `application/json` 400 (the spec's MUST). With no `tools/list` handler
+    the catalog is undiscoverable and there is no recognized header to validate.
+    """
+    if req.method != "tools/call" or app.get_request_handler("tools/list") is None:
+        return None
+    params = req.params or {}
+    name = params.get("name")
+    if not isinstance(name, str):
+        return None
+    raw_arguments = params.get("arguments")
+    if raw_arguments is not None and not isinstance(raw_arguments, Mapping):
+        return None
+    arguments: Mapping[str, Any] = cast("Mapping[str, Any]", raw_arguments) if raw_arguments is not None else {}
+    # ASGI guarantees lowercase header names, so no case-folding here.
+    if not arguments and not any(header.startswith(_MCP_PARAM_PREFIX_LOWER) for header in request.headers):
+        # No argument values and no `Mcp-Param-*` headers: no declaration can be violated either way.
+        return None
+    input_schema = await _tool_input_schema(app, request, req.id, verdict, lifespan_state, name)
+    if input_schema is None:
+        return None
+    return validate_mcp_param_headers(input_schema, arguments, request.headers)
+
+
+async def handle_modern_request(
+    app: Server[Any],
+    security_settings: TransportSecuritySettings | None,
+    json_response: bool,
+    lifespan_state: Any,
+    scope: Scope,
+    receive: Receive,
+    send: Send,
+) -> None:
+    """ASGI handler for a single stateless-era POST.
+
+    Called from `StreamableHTTPSessionManager.handle_request` when the
+    `MCP-Protocol-Version` header names a modern revision; the manager enters
+    `app.lifespan` once at startup and passes the state in. Never sets
+    `Mcp-Session-Id`.
+    """
+    request = Request(scope, receive)
+
+    security = TransportSecurityMiddleware(security_settings)
+    err = await security.validate_request(request, is_post=(request.method == "POST"))
+    if err is not None:
+        await err(scope, receive, send)
+        return
+
+    if request.method != "POST":
+        # HTTP-layer rejection (Allow accompanies 405 per RFC 9110) — happens
+        # before JSON-RPC parsing, so it doesn't go through `_write`.
+        await Response(status_code=405, headers={"Allow": "POST"})(scope, receive, send)
+        return
+
+    has_json, has_sse = check_accept_headers(request)
+    if not has_json or (not json_response and not has_sse):
+        await Response(status_code=406)(scope, receive, send)
+        return
+
+    body = await request.body()
+    try:
+        decoded = json.loads(body)
+    except (ValueError, RecursionError):
+        # Not just JSONDecodeError: oversized integer literals raise bare ValueError, deep nesting RecursionError.
+        rej = JSONRPCError(jsonrpc="2.0", id=None, error=ErrorData(code=PARSE_ERROR, message="Parse error"))
+        await _write(rej, scope, receive, send)
+        return
+    try:
+        req = JSONRPCRequest.model_validate(decoded)
+    except ValidationError:
+        # Well-formed JSON that isn't a single request object. The transport
+        # spec permits notification POSTs and gives the server two responses
+        # (202 accept / 4xx cannot-accept; streamable-http §Sending Messages
+        # item 5). The core protocol defines no client→server notifications
+        # over HTTP at 2026-07-28 (cancellation is SSE-stream close), so this
+        # entry takes the cannot-accept branch. TODO(L57): S4 owns the
+        # strict-vs-lenient choice.
+        rej = JSONRPCError(
+            jsonrpc="2.0",
+            id=None,
+            error=ErrorData(code=INVALID_REQUEST, message="Body must be a single JSON-RPC request object"),
+        )
+        await _write(rej, scope, receive, send)
+        return
+
+    if req.method == "subscriptions/listen" and not has_sse:
+        # A listen response IS a notification stream, never JSON (the
+        # json_response carve-out below), so this one method requires the
+        # SSE accept even in JSON-response mode; SSE mode gated it above.
+        await Response(status_code=406)(scope, receive, send)
+        return
+
+    duplicated = find_duplicated_routing_header(request.headers.items())
+    if duplicated is not None:
+        # The raw carrier is the only place duplicates are visible; the classifier sees a folded mapping.
+        rejection = InboundLadderRejection(code=HEADER_MISMATCH, message=f"{duplicated} header appears more than once")
+        await _write_rejection(rejection, req.id, scope, receive, send)
+        return
+
+    verdict = classify_inbound_request(decoded, headers=dict(request.headers))
+    if isinstance(verdict, InboundLadderRejection):
+        await _write_rejection(verdict, req.id, scope, receive, send)
+        return
+
+    mcp_param_rejection = await _mcp_param_rejection(app, request, req, verdict, lifespan_state)
+    if mcp_param_rejection is not None:
+        await _write_rejection(mcp_param_rejection, req.id, scope, receive, send)
+        return
+
+    connection = Connection.from_envelope(
+        verdict.protocol_version,
+        verdict.client_info,
+        verdict.client_capabilities,
+    )
+    dctx = _SingleExchangeDispatchContext(
+        transport=TransportContext(kind="streamable-http", can_send_request=False, headers=request.headers),
+        request_id=req.id,
+        message_metadata=ServerMessageMetadata(request_context=request),
+        progress_token=progress_token_from_params(req.params),
+    )
+
+    if json_response and req.method != "subscriptions/listen":
+        # A listen response IS a notification stream, so it always takes the
+        # SSE path below regardless of the JSON-response preference (the
+        # TypeScript and Go SDKs route it the same way).
+        msg = await _to_jsonrpc_response(
+            req.id, serve_one(app, dctx, req.method, req.params, connection=connection, lifespan_state=lifespan_state)
+        )
+        await _write(msg, scope, receive, send)
+        return
+
+    send_ch, recv_ch = anyio.create_memory_object_stream[bytes](0)
+    dctx.sink = send_ch
+    result: list[JSONRPCResponse | JSONRPCError] = []
+
+    async def run_handler() -> None:
+        async with send_ch:
+            result.append(
+                await _to_jsonrpc_response(
+                    req.id,
+                    serve_one(app, dctx, req.method, req.params, connection=connection, lifespan_state=lifespan_state),
+                )
+            )
+
+    async def watch_disconnect(cancel_scope: anyio.CancelScope) -> None:
+        while (await receive()).get("type") != "http.disconnect":
+            pass  # pragma: no cover
+        cancel_scope.cancel()
+
+    async with recv_ch, anyio.create_task_group() as tg:
+        tg.start_soon(run_handler)
+        tg.start_soon(watch_disconnect, tg.cancel_scope)
+
+        event: bytes | None = None
+        done = False
+        with anyio.move_on_after(_SSE_PING_INTERVAL):
+            try:
+                event = await recv_ch.receive()
+            except anyio.EndOfStream:
+                done = True
+
+        if done:
+            # Handler completed within the deferral window without emitting:
+            # `application/json` with the table-mapped status. Kernel-dispatch
+            # errors (METHOD_NOT_FOUND, missing-capability, INVALID_PARAMS)
+            # resolve here in practice.
+            await _write(result[0], scope, receive, send)
+        else:
+            # First notification arrived, or the deferral window elapsed: commit
+            # `text/event-stream` and start pinging so a proxy idle-read timeout
+            # cannot close the stream (which on this path cancels the handler).
+            await send({"type": "http.response.start", "status": _OK_STATUS, "headers": _SSE_HEADERS})
+            while not done:
+                await send({"type": "http.response.body", "body": event or b": ping\r\n\r\n", "more_body": True})
+                event = None
+                with anyio.move_on_after(_SSE_PING_INTERVAL):
+                    try:
+                        event = await recv_ch.receive()
+                    except anyio.EndOfStream:
+                        done = True
+            await send({"type": "http.response.body", "body": _sse_event(result[0]), "more_body": False})
+
+        tg.cancel_scope.cancel()

.mcp-venv/lib/python3.13/site-packages/mcp/server/apps.py

@@ -0,0 +1,241 @@
+"""MCP Apps extension (`io.modelcontextprotocol/ui`).
+
+MCP Apps lets a tool carry a reference to an interactive UI: the tool's
+`_meta.ui.resourceUri` points at a `ui://` resource (an HTML document served
+with the `text/html;profile=mcp-app` MIME type) that the host renders in a
+sandboxed iframe. See https://modelcontextprotocol.io/specification/draft/extensions/apps
+and the ext-apps spec for the wire format, and SEP-2133 for the extension framework.
+
+This is a self-contained, additive `Extension`: it contributes tools and
+resources and advertises the capability, but does not intercept any core method.
+A server opts in by passing an `Apps` instance to `MCPServer(extensions=[...])`.
+
+    apps = Apps()
+
+    @apps.tool(resource_uri="ui://clock/app.html", description="Current time")
+    def get_time(ctx: Context) -> str:
+        return datetime.now(timezone.utc).isoformat()
+
+    apps.add_html_resource("ui://clock/app.html", CLOCK_HTML)
+
+    mcp = MCPServer("clock", extensions=[apps])
+
+Per SEP-2133, an extension MUST degrade gracefully: a UI-enabled tool should
+still return meaningful text for clients that did not negotiate Apps. Use
+`client_supports_apps(ctx)` to branch on the client's advertised support. (The SDK
+keeps Apps in-core under `mcp.server.apps` rather than a separate package; the
+TypeScript and C# SDKs ship it as a standalone package.)
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from typing import Any, Literal, TypeVar
+
+from pydantic import BaseModel, ConfigDict
+from pydantic.alias_generators import to_camel
+
+from mcp.server.context import ServerRequestContext
+from mcp.server.extension import Extension, ResourceBinding, ToolBinding
+from mcp.server.mcpserver.context import Context
+from mcp.server.mcpserver.resources import Resource, TextResource
+
+EXTENSION_ID = "io.modelcontextprotocol/ui"
+"""The MCP Apps extension identifier (the shipped TS/C# constant)."""
+
+APP_MIME_TYPE = "text/html;profile=mcp-app"
+"""MIME type for a `ui://` app resource."""
+
+Visibility = Literal["model", "app"]
+"""Where a UI-bound tool is surfaced (`_meta.ui.visibility`)."""
+
+_CallableT = TypeVar("_CallableT", bound=Callable[..., Any])
+
+
+class ResourcePermissions(BaseModel):
+    """Iframe permissions a `ui://` resource requests (`_meta.ui.permissions`)."""
+
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+
+    camera: dict[str, Any] | None = None
+    microphone: dict[str, Any] | None = None
+    geolocation: dict[str, Any] | None = None
+    clipboard_write: dict[str, Any] | None = None
+
+
+class ResourceCsp(BaseModel):
+    """Content-Security-Policy domains for a `ui://` resource (`_meta.ui.csp`)."""
+
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+
+    connect_domains: list[str] | None = None
+    resource_domains: list[str] | None = None
+    frame_domains: list[str] | None = None
+    base_uri_domains: list[str] | None = None
+
+
+class Apps(Extension):
+    """The MCP Apps extension: bind tools to `ui://` UI resources.
+
+    Register UI-bound tools with `@apps.tool(resource_uri=...)` and their HTML
+    with `add_html_resource(...)`, then pass the instance to
+    `MCPServer(extensions=[apps])`.
+    """
+
+    identifier = EXTENSION_ID
+
+    def __init__(self) -> None:
+        self._tools: list[tuple[ToolBinding, str]] = []  # (binding, bound resource_uri)
+        self._resources: list[ResourceBinding] = []
+
+    def tool(
+        self,
+        *,
+        resource_uri: str,
+        visibility: Sequence[Visibility] | None = None,
+        meta: dict[str, Any] | None = None,
+        **tool_kwargs: Any,
+    ) -> Callable[[_CallableT], _CallableT]:
+        """Decorator registering a tool bound to a `ui://` resource.
+
+        Stamps `_meta.ui.resourceUri` (and `_meta.ui.visibility` when given) on the
+        tool. `tool_kwargs` are forwarded to `MCPServer.add_tool` (name, title,
+        description, annotations, ...); pass `meta=` to merge extra `_meta` keys
+        alongside the `ui` entry.
+
+        Args:
+            resource_uri: The `ui://` URI of the UI resource this tool renders.
+            visibility: Where the tool is surfaced (`["model", "app"]`).
+            meta: Additional `_meta` keys to merge with the `ui` entry.
+
+        Raises:
+            ValueError: If `resource_uri` does not use the `ui://` scheme, or
+                `meta` carries a `"ui"` key (the decorator owns `_meta["ui"]`).
+        """
+        _require_ui_scheme(resource_uri)
+        if meta and "ui" in meta:
+            raise ValueError("Apps.tool() owns _meta['ui']; pass resource_uri=/visibility= instead of a 'ui' meta key")
+        ui: dict[str, Any] = {"resourceUri": resource_uri}
+        if visibility is not None:
+            ui["visibility"] = list(visibility)
+
+        def decorator(fn: _CallableT) -> _CallableT:
+            binding = ToolBinding(fn=fn, meta={**(meta or {}), "ui": ui}, kwargs=tool_kwargs)
+            self._tools.append((binding, resource_uri))
+            return fn
+
+        return decorator
+
+    def add_html_resource(
+        self,
+        uri: str,
+        html: str,
+        *,
+        name: str | None = None,
+        title: str | None = None,
+        description: str | None = None,
+        csp: ResourceCsp | None = None,
+        permissions: ResourcePermissions | None = None,
+        domain: str | None = None,
+        prefers_border: bool | None = None,
+    ) -> None:
+        """Register a `ui://` HTML resource served as `text/html;profile=mcp-app`.
+
+        `csp`, `permissions`, `domain`, and `prefers_border` populate the
+        resource's `_meta.ui` per the ext-apps spec.
+
+        Args:
+            uri: The `ui://` URI; a tool references it via `resource_uri`.
+            html: The HTML document the host renders.
+
+        Raises:
+            ValueError: If `uri` does not use the `ui://` scheme.
+        """
+        ui: dict[str, Any] = {}
+        if csp is not None:
+            ui["csp"] = csp.model_dump(by_alias=True, exclude_none=True)
+        if permissions is not None:
+            ui["permissions"] = permissions.model_dump(by_alias=True, exclude_none=True)
+        if domain is not None:
+            ui["domain"] = domain
+        if prefers_border is not None:
+            ui["prefersBorder"] = prefers_border
+        self.add_resource(
+            TextResource(
+                uri=uri,
+                name=name or uri,
+                title=title,
+                description=description,
+                mime_type=APP_MIME_TYPE,
+                meta={"ui": ui} if ui else None,
+                text=html,
+            )
+        )
+
+    def add_resource(self, resource: Resource) -> None:
+        """Register a pre-built `ui://` resource.
+
+        The escape hatch for resources `add_html_resource` cannot express (e.g. a
+        `FileResource` serving HTML from disk). A resource without an explicit
+        `mime_type` is served as `text/html;profile=mcp-app` — hosts will not
+        render a `ui://` resource under any other MIME type, so an explicit
+        mismatch is rejected.
+
+        Raises:
+            ValueError: If the resource URI does not use the `ui://` scheme, or
+                its explicit `mime_type` is not `text/html;profile=mcp-app`.
+        """
+        _require_ui_scheme(resource.uri)
+        if "mime_type" not in resource.model_fields_set:
+            resource = resource.model_copy(update={"mime_type": APP_MIME_TYPE})
+        elif resource.mime_type != APP_MIME_TYPE:
+            raise ValueError(f"MCP Apps resources are served as {APP_MIME_TYPE!r}, got {resource.mime_type!r}")
+        self._resources.append(ResourceBinding(resource=resource))
+
+    def tools(self) -> Sequence[ToolBinding]:
+        """The bound tools.
+
+        Raises:
+            ValueError: If a tool's `resource_uri` has no matching resource
+                registered on this instance — a tool advertising a
+                `_meta.ui.resourceUri` that 404s on `resources/read` is a
+                misconfiguration, caught when the server consumes the extension.
+        """
+        registered = {binding.resource.uri for binding in self._resources}
+        for tool, uri in self._tools:
+            if uri not in registered:
+                raise ValueError(
+                    f"Apps tool {tool.fn.__name__!r} binds resource_uri {uri!r}, but no such resource "
+                    "is registered; add it with add_html_resource() or add_resource()"
+                )
+        return [tool for tool, _ in self._tools]
+
+    def resources(self) -> Sequence[ResourceBinding]:
+        return self._resources
+
+
+def client_supports_apps(ctx: Context[Any] | ServerRequestContext[Any, Any]) -> bool:
+    """Whether the connected client negotiated MCP Apps support.
+
+    Returns `True` only when the client advertised the extension AND listed the
+    `text/html;profile=mcp-app` MIME type in its settings, so a UI-enabled tool
+    can fall back to text-only output otherwise.
+    """
+    capabilities = _client_capabilities(ctx)
+    extensions = capabilities.extensions if capabilities else None
+    settings = extensions.get(EXTENSION_ID) if extensions else None
+    if settings is None:
+        return False
+    mime_types = settings.get("mimeTypes")
+    return isinstance(mime_types, list | tuple) and APP_MIME_TYPE in mime_types
+
+
+def _client_capabilities(ctx: Context[Any] | ServerRequestContext[Any, Any]) -> Any:
+    if isinstance(ctx, Context):
+        return ctx.client_capabilities
+    return ctx.session.client_capabilities
+
+
+def _require_ui_scheme(uri: str) -> None:
+    if not uri.startswith("ui://"):
+        raise ValueError(f"MCP Apps URIs must use the ui:// scheme, got {uri!r}")

.mcp-venv/lib/python3.13/site-packages/mcp/server/auth/__init__.py

@@ -0,0 +1 @@
+"""MCP OAuth server authorization components."""

.mcp-venv/lib/python3.13/site-packages/mcp/server/auth/errors.py

@@ -0,0 +1,5 @@
+from pydantic import ValidationError
+
+
+def stringify_pydantic_error(validation_error: ValidationError) -> str:
+    return "\n".join(f"{'.'.join(str(loc) for loc in e['loc'])}: {e['msg']}" for e in validation_error.errors())

.mcp-venv/lib/python3.13/site-packages/mcp/server/auth/handlers/__init__.py

@@ -0,0 +1 @@
+"""Request handlers for MCP authorization endpoints."""

.mcp-venv/lib/python3.13/site-packages/mcp/server/auth/handlers/authorize.py

@@ -0,0 +1,225 @@
+import logging
+from dataclasses import dataclass
+from typing import Any, Literal
+
+# TODO(Marcelo): We should drop the `RootModel`.
+from pydantic import AnyUrl, BaseModel, Field, RootModel, ValidationError  # noqa: TID251
+from starlette.datastructures import FormData, QueryParams
+from starlette.requests import Request
+from starlette.responses import RedirectResponse, Response
+
+from mcp.server.auth.errors import stringify_pydantic_error
+from mcp.server.auth.json_response import PydanticJSONResponse
+from mcp.server.auth.provider import (
+    AuthorizationErrorCode,
+    AuthorizationParams,
+    AuthorizeError,
+    OAuthAuthorizationServerProvider,
+    construct_redirect_uri,
+)
+from mcp.shared.auth import InvalidRedirectUriError, InvalidScopeError
+
+logger = logging.getLogger(__name__)
+
+
+class AuthorizationRequest(BaseModel):
+    # See https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.1
+    client_id: str = Field(..., description="The client ID")
+    redirect_uri: AnyUrl | None = Field(None, description="URL to redirect to after authorization")
+
+    # see OAuthClientMetadata; we only support `code`
+    response_type: Literal["code"] = Field(..., description="Must be 'code' for authorization code flow")
+    code_challenge: str = Field(..., description="PKCE code challenge")
+    code_challenge_method: Literal["S256"] = Field("S256", description="PKCE code challenge method, must be S256")
+    state: str | None = Field(None, description="Optional state parameter")
+    scope: str | None = Field(
+        None,
+        description="Optional scope; if specified, should be a space-separated list of scope strings",
+    )
+    resource: str | None = Field(
+        None,
+        description="RFC 8707 resource indicator - the MCP server this token will be used with",
+    )
+
+
+class AuthorizationErrorResponse(BaseModel):
+    error: AuthorizationErrorCode
+    error_description: str | None
+    error_uri: AnyUrl | None = None
+    # must be set if provided in the request
+    state: str | None = None
+
+
+def best_effort_extract_string(key: str, params: None | FormData | QueryParams) -> str | None:
+    if params is None:  # pragma: no cover
+        return None
+    value = params.get(key)
+    if isinstance(value, str):
+        return value
+    return None
+
+
+class AnyUrlModel(RootModel[AnyUrl]):
+    root: AnyUrl
+
+
+@dataclass
+class AuthorizationHandler:
+    provider: OAuthAuthorizationServerProvider[Any, Any, Any]
+
+    async def handle(self, request: Request) -> Response:
+        # implements authorization requests for grant_type=code;
+        # see https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.1
+
+        state = None
+        redirect_uri = None
+        client = None
+        params = None
+
+        async def error_response(
+            error: AuthorizationErrorCode,
+            error_description: str | None,
+            attempt_load_client: bool = True,
+        ):
+            # Error responses take two different formats:
+            # 1. The request has a valid client ID & redirect_uri: we issue a redirect
+            #    back to the redirect_uri with the error response fields as query
+            #    parameters. This allows the client to be notified of the error.
+            # 2. Otherwise, we return an error response directly to the end user;
+            #     we choose to do so in JSON, but this is left undefined in the
+            #     specification.
+            # See https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1
+            #
+            # This logic is a bit awkward to handle, because the error might be thrown
+            # very early in request validation, before we've done the usual Pydantic
+            # validation, loaded the client, etc. To handle this, error_response()
+            # contains fallback logic which attempts to load the parameters directly
+            # from the request.
+
+            nonlocal client, redirect_uri, state
+            if client is None and attempt_load_client:
+                # make last-ditch attempt to load the client
+                client_id = best_effort_extract_string("client_id", params)
+                client = await self.provider.get_client(client_id) if client_id else None
+            if redirect_uri is None and client:
+                # make last-ditch effort to load the redirect uri
+                try:
+                    if params is not None and "redirect_uri" not in params:
+                        raw_redirect_uri = None
+                    else:
+                        raw_redirect_uri = AnyUrlModel.model_validate(
+                            best_effort_extract_string("redirect_uri", params)
+                        ).root
+                    redirect_uri = client.validate_redirect_uri(raw_redirect_uri)
+                except (ValidationError, InvalidRedirectUriError):
+                    # if the redirect URI is invalid, ignore it & just return the
+                    # initial error
+                    pass
+
+            # the error response MUST contain the state specified by the client, if any
+            if state is None:
+                # make last-ditch effort to load state
+                state = best_effort_extract_string("state", params)
+
+            error_resp = AuthorizationErrorResponse(
+                error=error,
+                error_description=error_description,
+                state=state,
+            )
+
+            if redirect_uri and client:
+                return RedirectResponse(
+                    url=construct_redirect_uri(str(redirect_uri), **error_resp.model_dump(exclude_none=True)),
+                    status_code=302,
+                    headers={"Cache-Control": "no-store"},
+                )
+            else:
+                return PydanticJSONResponse(
+                    status_code=400,
+                    content=error_resp,
+                    headers={"Cache-Control": "no-store"},
+                )
+
+        try:
+            # Parse request parameters
+            if request.method == "GET":
+                # Convert query_params to dict for pydantic validation
+                params = request.query_params
+            else:
+                # Parse form data for POST requests
+                params = await request.form()
+
+            # Save state if it exists, even before validation
+            state = best_effort_extract_string("state", params)
+
+            try:
+                auth_request = AuthorizationRequest.model_validate(params)
+                state = auth_request.state  # Update with validated state
+            except ValidationError as validation_error:
+                error: AuthorizationErrorCode = "invalid_request"
+                for e in validation_error.errors():
+                    if e["loc"] == ("response_type",) and e["type"] == "literal_error":
+                        error = "unsupported_response_type"
+                        break
+                return await error_response(error, stringify_pydantic_error(validation_error))
+
+            # Get client information
+            client = await self.provider.get_client(
+                auth_request.client_id,
+            )
+            if not client:
+                # For client_id validation errors, return direct error (no redirect)
+                return await error_response(
+                    error="invalid_request",
+                    error_description=f"Client ID '{auth_request.client_id}' not found",
+                    attempt_load_client=False,
+                )
+
+            # Validate redirect_uri against client's registered URIs
+            try:
+                redirect_uri = client.validate_redirect_uri(auth_request.redirect_uri)
+            except InvalidRedirectUriError as validation_error:
+                # For redirect_uri validation errors, return direct error (no redirect)
+                return await error_response(
+                    error="invalid_request",
+                    error_description=validation_error.message,
+                )
+
+            # Validate scope - for scope errors, we can redirect
+            try:
+                scopes = client.validate_scope(auth_request.scope)
+            except InvalidScopeError as validation_error:
+                # For scope errors, redirect with error parameters
+                return await error_response(
+                    error="invalid_scope",
+                    error_description=validation_error.message,
+                )
+
+            # Setup authorization parameters
+            auth_params = AuthorizationParams(
+                state=state,
+                scopes=scopes,
+                code_challenge=auth_request.code_challenge,
+                redirect_uri=redirect_uri,
+                redirect_uri_provided_explicitly=auth_request.redirect_uri is not None,
+                resource=auth_request.resource,  # RFC 8707
+            )
+
+            try:
+                # Let the provider pick the next URI to redirect to
+                return RedirectResponse(
+                    url=await self.provider.authorize(
+                        client,
+                        auth_params,
+                    ),
+                    status_code=302,
+                    headers={"Cache-Control": "no-store"},
+                )
+            except AuthorizeError as e:
+                # Handle authorization errors as defined in RFC 6749 Section 4.1.2.1
+                return await error_response(error=e.error, error_description=e.error_description)
+
+        except Exception as validation_error:  # pragma: no cover
+            # Catch-all for unexpected errors
+            logger.exception("Unexpected error in authorization_handler", exc_info=validation_error)
+            return await error_response(error="server_error", error_description="An unexpected error occurred")

.mcp-venv/lib/python3.13/site-packages/mcp/server/auth/handlers/metadata.py

@@ -0,0 +1,29 @@
+from dataclasses import dataclass
+
+from starlette.requests import Request
+from starlette.responses import Response
+
+from mcp.server.auth.json_response import PydanticJSONResponse
+from mcp.shared.auth import OAuthMetadata, ProtectedResourceMetadata
+
+
+@dataclass
+class MetadataHandler:
+    metadata: OAuthMetadata
+
+    async def handle(self, request: Request) -> Response:
+        return PydanticJSONResponse(
+            content=self.metadata,
+            headers={"Cache-Control": "public, max-age=3600"},  # Cache for 1 hour
+        )
+
+
+@dataclass
+class ProtectedResourceMetadataHandler:
+    metadata: ProtectedResourceMetadata
+
+    async def handle(self, request: Request) -> Response:
+        return PydanticJSONResponse(
+            content=self.metadata,
+            headers={"Cache-Control": "public, max-age=3600"},  # Cache for 1 hour
+        )

.mcp-venv/lib/python3.13/site-packages/mcp/server/auth/handlers/register.py

@@ -0,0 +1,154 @@
+import secrets
+import time
+from dataclasses import dataclass
+from typing import Any
+from uuid import uuid4
+
+from pydantic import BaseModel, ValidationError
+from starlette.requests import Request
+from starlette.responses import Response
+
+from mcp.server.auth.errors import stringify_pydantic_error
+from mcp.server.auth.json_response import PydanticJSONResponse
+from mcp.server.auth.provider import OAuthAuthorizationServerProvider, RegistrationError, RegistrationErrorCode
+from mcp.server.auth.settings import ClientRegistrationOptions
+from mcp.shared.auth import JWT_BEARER_GRANT_TYPE, OAuthClientInformationFull, OAuthClientMetadata
+
+# this alias is a no-op; it's just to separate out the types exposed to the
+# provider from what we use in the HTTP handler
+RegistrationRequest = OAuthClientMetadata
+
+
+class RegistrationErrorResponse(BaseModel):
+    error: RegistrationErrorCode
+    error_description: str | None
+
+
+@dataclass
+class RegistrationHandler:
+    provider: OAuthAuthorizationServerProvider[Any, Any, Any]
+    options: ClientRegistrationOptions
+
+    async def handle(self, request: Request) -> Response:
+        # Implements dynamic client registration as defined in https://datatracker.ietf.org/doc/html/rfc7591#section-3.1
+        try:
+            body = await request.body()
+            client_metadata = OAuthClientMetadata.model_validate_json(body)
+
+            # Scope validation is handled below
+        except ValidationError as validation_error:
+            return PydanticJSONResponse(
+                content=RegistrationErrorResponse(
+                    error="invalid_client_metadata",
+                    error_description=stringify_pydantic_error(validation_error),
+                ),
+                status_code=400,
+            )
+
+        client_id = str(uuid4())
+
+        # If auth method is None, default to client_secret_post
+        if client_metadata.token_endpoint_auth_method is None:
+            client_metadata.token_endpoint_auth_method = "client_secret_post"
+        # This server authenticates token requests with the client secret it mints; it holds
+        # no client key to verify a private_key_jwt assertion, so confirming that method would
+        # register a client whose every token request is then rejected. Refuse it instead
+        # (RFC 7591 §3.2.2), before minting credentials the client could never use.
+        if client_metadata.token_endpoint_auth_method == "private_key_jwt":
+            return PydanticJSONResponse(
+                content=RegistrationErrorResponse(
+                    error="invalid_client_metadata",
+                    error_description="token_endpoint_auth_method 'private_key_jwt' is not supported",
+                ),
+                status_code=400,
+            )
+
+        client_secret = None
+        if client_metadata.token_endpoint_auth_method != "none":  # pragma: no branch
+            # cryptographically secure random 32-byte hex string
+            client_secret = secrets.token_hex(32)
+
+        if client_metadata.scope is None and self.options.default_scopes is not None:
+            client_metadata.scope = " ".join(self.options.default_scopes)
+        elif client_metadata.scope is not None and self.options.valid_scopes is not None:
+            requested_scopes = set(client_metadata.scope.split())
+            valid_scopes = set(self.options.valid_scopes)
+            if not requested_scopes.issubset(valid_scopes):  # pragma: no branch
+                return PydanticJSONResponse(
+                    content=RegistrationErrorResponse(
+                        error="invalid_client_metadata",
+                        error_description="Requested scopes are not valid: "
+                        f"{', '.join(requested_scopes - valid_scopes)}",
+                    ),
+                    status_code=400,
+                )
+        if "authorization_code" not in client_metadata.grant_types:
+            return PydanticJSONResponse(
+                content=RegistrationErrorResponse(
+                    error="invalid_client_metadata",
+                    error_description="grant_types must include 'authorization_code'",
+                ),
+                status_code=400,
+            )
+
+        # SEP-990 §5.1 / draft-ietf-oauth-identity-assertion-authz-grant §8.1: the ID-JAG flow is
+        # for confidential clients provisioned out of band. Refuse to grant it through DCR so a
+        # self-registered client cannot reach the identity-assertion provider hook.
+        if JWT_BEARER_GRANT_TYPE in client_metadata.grant_types:
+            return PydanticJSONResponse(
+                content=RegistrationErrorResponse(
+                    error="invalid_client_metadata",
+                    error_description=(
+                        f"grant_types must not include '{JWT_BEARER_GRANT_TYPE}'; "
+                        "the identity-assertion grant requires a pre-registered client"
+                    ),
+                ),
+                status_code=400,
+            )
+
+        # The MCP spec requires servers to use the authorization `code` flow
+        # with PKCE
+        if "code" not in client_metadata.response_types:
+            return PydanticJSONResponse(
+                content=RegistrationErrorResponse(
+                    error="invalid_client_metadata",
+                    error_description="response_types must include 'code' for authorization_code grant",
+                ),
+                status_code=400,
+            )
+
+        client_id_issued_at = int(time.time())
+        # RFC 7591 §3.2.1: client_secret_expires_at is REQUIRED whenever a client_secret is
+        # issued, with 0 (not omission) meaning it never expires; a public client gets none.
+        client_secret_expires_at = None
+        if client_secret is not None:
+            client_secret_expires_at = (
+                client_id_issued_at + self.options.client_secret_expiry_seconds
+                if self.options.client_secret_expiry_seconds is not None
+                else 0
+            )
+
+        # RFC 7591 §3.2.1: the response returns all registered metadata about the client, so
+        # the record is the whole validated request plus the credentials minted here - built
+        # from the request's dump so no metadata field can be silently omitted from the echo.
+        client_info = OAuthClientInformationFull.model_validate(
+            {
+                **client_metadata.model_dump(),
+                "client_id": client_id,
+                "client_id_issued_at": client_id_issued_at,
+                "client_secret": client_secret,
+                "client_secret_expires_at": client_secret_expires_at,
+            }
+        )
+        try:
+            # Register client
+            await self.provider.register_client(client_info)
+
+            # Return client information
+            return PydanticJSONResponse(content=client_info, status_code=201)
+        except RegistrationError as e:
+            # Handle registration errors as defined in RFC 7591 Section 3.2.2
+            return PydanticJSONResponse(
+                content=RegistrationErrorResponse(error=e.error, error_description=e.error_description),
+                status_code=400,
+            )

.mcp-venv/lib/python3.13/site-packages/mcp/server/auth/handlers/revoke.py

@@ -0,0 +1,87 @@
+from dataclasses import dataclass
+from functools import partial
+from typing import Any, Literal
+
+from pydantic import BaseModel, ValidationError
+from starlette.requests import Request
+from starlette.responses import Response
+
+from mcp.server.auth.errors import (
+    stringify_pydantic_error,
+)
+from mcp.server.auth.json_response import PydanticJSONResponse
+from mcp.server.auth.middleware.client_auth import AuthenticationError, ClientAuthenticator
+from mcp.server.auth.provider import AccessToken, OAuthAuthorizationServerProvider, RefreshToken
+
+
+class RevocationRequest(BaseModel):
+    """See https://datatracker.ietf.org/doc/html/rfc7009#section-2.1"""
+
+    token: str
+    token_type_hint: Literal["access_token", "refresh_token"] | None = None
+    client_id: str
+    client_secret: str | None
+
+
+class RevocationErrorResponse(BaseModel):
+    error: Literal["invalid_request", "unauthorized_client"]
+    error_description: str | None = None
+
+
+@dataclass
+class RevocationHandler:
+    provider: OAuthAuthorizationServerProvider[Any, Any, Any]
+    client_authenticator: ClientAuthenticator
+
+    async def handle(self, request: Request) -> Response:
+        """Handler for the OAuth 2.0 Token Revocation endpoint."""
+        try:
+            client = await self.client_authenticator.authenticate_request(request)
+        except AuthenticationError as e:  # pragma: no cover
+            return PydanticJSONResponse(
+                status_code=401,
+                content=RevocationErrorResponse(
+                    error="unauthorized_client",
+                    error_description=e.message,
+                ),
+            )
+
+        try:
+            form_data = await request.form()
+            revocation_request = RevocationRequest.model_validate(dict(form_data))
+        except ValidationError as e:
+            return PydanticJSONResponse(
+                status_code=400,
+                content=RevocationErrorResponse(
+                    error="invalid_request",
+                    error_description=stringify_pydantic_error(e),
+                ),
+            )
+
+        loaders = [
+            self.provider.load_access_token,
+            partial(self.provider.load_refresh_token, client),
+        ]
+        if revocation_request.token_type_hint == "refresh_token":  # pragma: no cover
+            loaders = reversed(loaders)
+
+        token: None | AccessToken | RefreshToken = None
+        for loader in loaders:
+            token = await loader(revocation_request.token)
+            if token is not None:
+                break
+
+        # if token is not found, just return HTTP 200 per the RFC
+        if token and token.client_id == client.client_id:
+            # Revoke token; provider is not meant to be able to do validation
+            # at this point that would result in an error
+            await self.provider.revoke_token(token)
+
+        # Return successful empty response
+        return Response(
+            status_code=200,
+            headers={
+                "Cache-Control": "no-store",
+                "Pragma": "no-cache",
+            },
+        )

.mcp-venv/lib/python3.13/site-packages/mcp/server/auth/handlers/token.py

@@ -0,0 +1,275 @@
+import base64
+import hashlib
+import time
+from dataclasses import dataclass
+from typing import Annotated, Any, Literal
+
+from pydantic import AnyHttpUrl, AnyUrl, BaseModel, Field, TypeAdapter, ValidationError
+from starlette.requests import Request
+
+from mcp.server.auth.errors import stringify_pydantic_error
+from mcp.server.auth.json_response import PydanticJSONResponse
+from mcp.server.auth.middleware.client_auth import AuthenticationError, ClientAuthenticator
+from mcp.server.auth.provider import (
+    IdentityAssertionParams,
+    OAuthAuthorizationServerProvider,
+    TokenError,
+    TokenErrorCode,
+)
+from mcp.shared.auth import OAuthToken
+
+
+class AuthorizationCodeRequest(BaseModel):
+    # See https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.3
+    grant_type: Literal["authorization_code"]
+    code: str = Field(..., description="The authorization code")
+    redirect_uri: AnyUrl | None = Field(None, description="Must be the same as redirect URI provided in /authorize")
+    client_id: str
+    # we use the client_secret param, per https://datatracker.ietf.org/doc/html/rfc6749#section-2.3.1
+    client_secret: str | None = None
+    # See https://datatracker.ietf.org/doc/html/rfc7636#section-4.5
+    code_verifier: str = Field(..., description="PKCE code verifier")
+    # RFC 8707 resource indicator
+    resource: str | None = Field(None, description="Resource indicator for the token")
+
+
+class RefreshTokenRequest(BaseModel):
+    # See https://datatracker.ietf.org/doc/html/rfc6749#section-6
+    grant_type: Literal["refresh_token"]
+    refresh_token: str = Field(..., description="The refresh token")
+    scope: str | None = Field(None, description="Optional scope parameter")
+    client_id: str
+    # we use the client_secret param, per https://datatracker.ietf.org/doc/html/rfc6749#section-2.3.1
+    client_secret: str | None = None
+    # RFC 8707 resource indicator
+    resource: str | None = Field(None, description="Resource indicator for the token")
+
+
+class JwtBearerRequest(BaseModel):
+    # RFC 7523 §2.1 JWT bearer authorization grant. SEP-990 leg 2: the client presents the
+    # enterprise IdP-issued ID-JAG to the MCP authorization server as the `assertion`.
+    grant_type: Literal["urn:ietf:params:oauth:grant-type:jwt-bearer"]
+    # See https://datatracker.ietf.org/doc/html/rfc7523#section-2.1
+    assertion: str = Field(..., description="The ID-JAG (a signed JWT) being presented as the grant")
+    scope: str | None = Field(None, description="Optional scope parameter")
+    client_id: str
+    # we use the client_secret param, per https://datatracker.ietf.org/doc/html/rfc6749#section-2.3.1
+    client_secret: str | None = None
+    # RFC 8707 resource indicator
+    resource: str | None = Field(None, description="Resource indicator for the token")
+
+
+TokenRequest = Annotated[
+    AuthorizationCodeRequest | RefreshTokenRequest | JwtBearerRequest,
+    Field(discriminator="grant_type"),
+]
+token_request_adapter = TypeAdapter[TokenRequest](TokenRequest)
+
+
+class TokenErrorResponse(BaseModel):
+    """See https://datatracker.ietf.org/doc/html/rfc6749#section-5.2"""
+
+    error: TokenErrorCode
+    error_description: str | None = None
+    error_uri: AnyHttpUrl | None = None
+
+
+# this is just an alias over OAuthToken; the only reason we do this
+# is to have some separation between the HTTP response type, and the
+# type returned by the provider
+TokenSuccessResponse = OAuthToken
+
+
+@dataclass
+class TokenHandler:
+    provider: OAuthAuthorizationServerProvider[Any, Any, Any]
+    client_authenticator: ClientAuthenticator
+    identity_assertion_enabled: bool = False
+
+    def response(self, obj: TokenSuccessResponse | TokenErrorResponse):
+        status_code = 200
+        if isinstance(obj, TokenErrorResponse):
+            status_code = 400
+
+        return PydanticJSONResponse(
+            content=obj,
+            status_code=status_code,
+            headers={
+                "Cache-Control": "no-store",
+                "Pragma": "no-cache",
+            },
+        )
+
+    async def handle(self, request: Request):
+        try:
+            client_info = await self.client_authenticator.authenticate_request(request)
+        except AuthenticationError as e:
+            # Authentication failures should return 401
+            return PydanticJSONResponse(
+                content=TokenErrorResponse(
+                    error="invalid_client",
+                    error_description=e.message,
+                ),
+                status_code=401,
+                headers={
+                    "Cache-Control": "no-store",
+                    "Pragma": "no-cache",
+                },
+            )
+
+        try:
+            form_data = await request.form()
+            # TODO(Marcelo): Can someone check if this `dict()` wrapper is necessary?
+            token_request = token_request_adapter.validate_python(dict(form_data))
+        except ValidationError as validation_error:
+            return self.response(
+                TokenErrorResponse(
+                    error="invalid_request",
+                    error_description=stringify_pydantic_error(validation_error),
+                )
+            )
+
+        if token_request.grant_type not in client_info.grant_types:
+            return self.response(
+                TokenErrorResponse(
+                    error="unsupported_grant_type",
+                    error_description=(f"Unsupported grant type (supported grant types are {client_info.grant_types})"),
+                )
+            )
+
+        tokens: OAuthToken
+
+        match token_request:
+            case AuthorizationCodeRequest():
+                auth_code = await self.provider.load_authorization_code(client_info, token_request.code)
+                if auth_code is None or auth_code.client_id != token_request.client_id:
+                    # if code belongs to different client, pretend it doesn't exist
+                    return self.response(
+                        TokenErrorResponse(
+                            error="invalid_grant",
+                            error_description="authorization code does not exist",
+                        )
+                    )
+
+                # make auth codes expire after a deadline
+                # see https://datatracker.ietf.org/doc/html/rfc6749#section-10.5
+                if auth_code.expires_at < time.time():
+                    return self.response(
+                        TokenErrorResponse(
+                            error="invalid_grant",
+                            error_description="authorization code has expired",
+                        )
+                    )
+
+                # verify redirect_uri doesn't change between /authorize and /tokens
+                # see https://datatracker.ietf.org/doc/html/rfc6749#section-10.6
+                if auth_code.redirect_uri_provided_explicitly:
+                    authorize_request_redirect_uri = auth_code.redirect_uri
+                else:  # pragma: no cover
+                    authorize_request_redirect_uri = None
+
+                # Convert both sides to strings for comparison to handle AnyUrl vs string issues
+                token_redirect_str = str(token_request.redirect_uri) if token_request.redirect_uri is not None else None
+                auth_redirect_str = (
+                    str(authorize_request_redirect_uri) if authorize_request_redirect_uri is not None else None
+                )
+
+                if token_redirect_str != auth_redirect_str:
+                    return self.response(
+                        TokenErrorResponse(
+                            error="invalid_request",
+                            error_description=("redirect_uri did not match the one used when creating auth code"),
+                        )
+                    )
+
+                # Verify PKCE code verifier
+                sha256 = hashlib.sha256(token_request.code_verifier.encode()).digest()
+                hashed_code_verifier = base64.urlsafe_b64encode(sha256).decode().rstrip("=")
+
+                if hashed_code_verifier != auth_code.code_challenge:
+                    # see https://datatracker.ietf.org/doc/html/rfc7636#section-4.6
+                    return self.response(
+                        TokenErrorResponse(
+                            error="invalid_grant",
+                            error_description="incorrect code_verifier",
+                        )
+                    )
+
+                try:
+                    # Exchange authorization code for tokens
+                    tokens = await self.provider.exchange_authorization_code(client_info, auth_code)
+                except TokenError as e:
+                    return self.response(TokenErrorResponse(error=e.error, error_description=e.error_description))
+
+            case RefreshTokenRequest():
+                refresh_token = await self.provider.load_refresh_token(client_info, token_request.refresh_token)
+                if refresh_token is None or refresh_token.client_id != token_request.client_id:
+                    # if token belongs to different client, pretend it doesn't exist
+                    return self.response(
+                        TokenErrorResponse(
+                            error="invalid_grant",
+                            error_description="refresh token does not exist",
+                        )
+                    )
+
+                if refresh_token.expires_at and refresh_token.expires_at < time.time():
+                    # if the refresh token has expired, pretend it doesn't exist
+                    return self.response(
+                        TokenErrorResponse(
+                            error="invalid_grant",
+                            error_description="refresh token has expired",
+                        )
+                    )
+
+                # Parse scopes if provided
+                scopes = token_request.scope.split(" ") if token_request.scope else refresh_token.scopes
+
+                for scope in scopes:
+                    if scope not in refresh_token.scopes:
+                        return self.response(
+                            TokenErrorResponse(
+                                error="invalid_scope",
+                                error_description=(f"cannot request scope `{scope}` not provided by refresh token"),
+                            )
+                        )
+
+                try:
+                    # Exchange refresh token for new tokens
+                    tokens = await self.provider.exchange_refresh_token(client_info, refresh_token, scopes)
+                except TokenError as e:
+                    return self.response(TokenErrorResponse(error=e.error, error_description=e.error_description))
+
+            case JwtBearerRequest():  # pragma: no branch
+                if not self.identity_assertion_enabled:
+                    return self.response(
+                        TokenErrorResponse(
+                            error="unsupported_grant_type",
+                            error_description="The JWT bearer grant is not supported by this authorization server",
+                        )
+                    )
+
+                # SEP-990 §5.1: only confidential clients may present an ID-JAG. ClientAuthenticator
+                # already rejects a secret-based method with no stored secret; this additionally
+                # rejects the public `none` method so an unauthenticated client never reaches the
+                # provider hook.
+                if not client_info.client_secret:
+                    # RFC 6749 §5.2: the client authenticated but is not permitted this grant, so
+                    # unauthorized_client (not invalid_client, which is for failed authentication).
+                    return self.response(
+                        TokenErrorResponse(
+                            error="unauthorized_client",
+                            error_description="The JWT bearer grant requires a confidential client",
+                        )
+                    )
+
+                params = IdentityAssertionParams(
+                    assertion=token_request.assertion,
+                    scopes=token_request.scope.split(" ") if token_request.scope else None,
+                    resource=token_request.resource,
+                )
+                try:
+                    tokens = await self.provider.exchange_identity_assertion(client_info, params)
+                except TokenError as e:
+                    return self.response(TokenErrorResponse(error=e.error, error_description=e.error_description))
+
+        return self.response(tokens)

.mcp-venv/lib/python3.13/site-packages/mcp/server/auth/json_response.py

@@ -0,0 +1,10 @@
+from typing import Any
+
+from starlette.responses import JSONResponse
+
+
+class PydanticJSONResponse(JSONResponse):
+    # use pydantic json serialization instead of the stock `json.dumps`,
+    # so that we can handle serializing pydantic models like AnyHttpUrl
+    def render(self, content: Any) -> bytes:
+        return content.model_dump_json(exclude_none=True).encode("utf-8")

.mcp-venv/lib/python3.13/site-packages/mcp/server/auth/middleware/__init__.py

@@ -0,0 +1 @@
+"""Middleware for MCP authorization."""

.mcp-venv/lib/python3.13/site-packages/mcp/server/auth/middleware/auth_context.py

@@ -0,0 +1,46 @@
+import contextvars
+
+from starlette.types import ASGIApp, Receive, Scope, Send
+
+from mcp.server.auth.middleware.bearer_auth import AuthenticatedUser
+from mcp.server.auth.provider import AccessToken
+
+# Create a contextvar to store the authenticated user
+# The default is None, indicating no authenticated user is present
+auth_context_var = contextvars.ContextVar[AuthenticatedUser | None]("auth_context", default=None)
+
+
+def get_access_token() -> AccessToken | None:
+    """Get the access token from the current context.
+
+    Returns:
+        The access token if an authenticated user is available, None otherwise.
+    """
+    auth_user = auth_context_var.get()
+    return auth_user.access_token if auth_user else None
+
+
+class AuthContextMiddleware:
+    """Middleware that extracts the authenticated user from the request
+    and sets it in a contextvar for easy access throughout the request lifecycle.
+
+    This middleware should be added after the AuthenticationMiddleware in the
+    middleware stack to ensure that the user is properly authenticated before
+    being stored in the context.
+    """
+
+    def __init__(self, app: ASGIApp):
+        self.app = app
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send):
+        user = scope.get("user")
+        if isinstance(user, AuthenticatedUser):
+            # Set the authenticated user in the contextvar
+            token = auth_context_var.set(user)
+            try:
+                await self.app(scope, receive, send)
+            finally:
+                auth_context_var.reset(token)
+        else:
+            # No authenticated user, just process the request
+            await self.app(scope, receive, send)

.mcp-venv/lib/python3.13/site-packages/mcp/server/auth/middleware/bearer_auth.py

@@ -0,0 +1,143 @@
+import json
+import time
+from typing import Any, TypedDict
+
+from pydantic import AnyHttpUrl
+from starlette.authentication import AuthCredentials, AuthenticationBackend, SimpleUser
+from starlette.requests import HTTPConnection
+from starlette.types import Receive, Scope, Send
+
+from mcp.server.auth.provider import AccessToken, TokenVerifier, principal_components
+
+
+class AuthenticatedUser(SimpleUser):
+    """User with authentication info."""
+
+    def __init__(self, auth_info: AccessToken):
+        super().__init__(auth_info.client_id)
+        self.access_token = auth_info
+        self.scopes = auth_info.scopes
+
+
+class AuthorizationContext(TypedDict):
+    client_id: str
+    issuer: str | None
+    subject: str | None
+
+
+def authorization_context(user: AuthenticatedUser) -> AuthorizationContext:
+    """Identify the principal `user` represents, for transports to compare
+    against the principal that created a session. Components the token
+    verifier does not supply are `None`, so the comparison degrades to the
+    remaining components.
+
+    See `examples/servers/simple-auth/mcp_simple_auth/token_verifier.py` for
+    a verifier that populates `subject` and `claims` from an introspection
+    response."""
+    client_id, issuer, subject = principal_components(user.access_token)
+    return AuthorizationContext(client_id=client_id, issuer=issuer, subject=subject)
+
+
+class BearerAuthBackend(AuthenticationBackend):
+    """Authentication backend that validates Bearer tokens using a TokenVerifier."""
+
+    def __init__(self, token_verifier: TokenVerifier):
+        self.token_verifier = token_verifier
+
+    async def authenticate(self, conn: HTTPConnection):
+        auth_header = next(
+            (conn.headers.get(key) for key in conn.headers if key.lower() == "authorization"),
+            None,
+        )
+        if not auth_header or not auth_header.lower().startswith("bearer "):
+            return None
+
+        token = auth_header[7:]  # Remove "Bearer " prefix
+
+        # Validate the token with the verifier
+        auth_info = await self.token_verifier.verify_token(token)
+
+        if not auth_info:
+            return None
+
+        if auth_info.expires_at and auth_info.expires_at < int(time.time()):
+            return None
+
+        return AuthCredentials(auth_info.scopes), AuthenticatedUser(auth_info)
+
+
+class RequireAuthMiddleware:
+    """Middleware that requires a valid Bearer token in the Authorization header.
+
+    This will validate the token with the auth provider and store the resulting
+    auth info in the request state.
+    """
+
+    def __init__(
+        self,
+        app: Any,
+        required_scopes: list[str],
+        resource_metadata_url: AnyHttpUrl | None = None,
+    ):
+        """Initialize the middleware.
+
+        Args:
+            app: ASGI application
+            required_scopes: List of scopes that the token must have
+            resource_metadata_url: Optional protected resource metadata URL for WWW-Authenticate header
+        """
+        self.app = app
+        self.required_scopes = required_scopes
+        self.resource_metadata_url = resource_metadata_url
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        auth_user = scope.get("user")
+        if not isinstance(auth_user, AuthenticatedUser):
+            await self._send_auth_error(
+                send, status_code=401, error="invalid_token", description="Authentication required"
+            )
+            return
+
+        auth_credentials = scope.get("auth")
+
+        for required_scope in self.required_scopes:
+            # auth_credentials should always be provided; this is just paranoia
+            if auth_credentials is None or required_scope not in auth_credentials.scopes:
+                await self._send_auth_error(
+                    send, status_code=403, error="insufficient_scope", description=f"Required scope: {required_scope}"
+                )
+                return
+
+        await self.app(scope, receive, send)
+
+    async def _send_auth_error(self, send: Send, status_code: int, error: str, description: str) -> None:
+        """Send an authentication error response with WWW-Authenticate header."""
+        # Build WWW-Authenticate header value
+        www_auth_parts = [f'error="{error}"', f'error_description="{description}"']
+        if self.resource_metadata_url:
+            www_auth_parts.append(f'resource_metadata="{self.resource_metadata_url}"')
+
+        www_authenticate = f"Bearer {', '.join(www_auth_parts)}"
+
+        # Send response
+        body = {"error": error, "error_description": description}
+        body_bytes = json.dumps(body).encode()
+
+        await send(
+            {
+                "type": "http.response.start",
+                "status": status_code,
+                "headers": [
+                    (b"content-type", b"application/json"),
+                    (b"content-length", str(len(body_bytes)).encode()),
+                    (b"www-authenticate", www_authenticate.encode()),
+                ],
+            }
+        )
+
+        await send(
+            {
+                "type": "http.response.body",
+                "body": body_bytes,
+            }
+        )

.mcp-venv/lib/python3.13/site-packages/mcp/server/auth/middleware/client_auth.py

@@ -0,0 +1,119 @@
+import base64
+import binascii
+import hmac
+import time
+from typing import Any
+from urllib.parse import unquote
+
+from starlette.requests import Request
+
+from mcp.server.auth.provider import OAuthAuthorizationServerProvider
+from mcp.shared.auth import OAuthClientInformationFull
+
+
+class AuthenticationError(Exception):
+    def __init__(self, message: str):
+        self.message = message
+
+
+class ClientAuthenticator:
+    """ClientAuthenticator is a callable which validates requests from a client
+    application, used to verify /token calls.
+
+    If, during registration, the client requested to be issued a secret, the
+    authenticator asserts that /token calls must be authenticated with
+    that same secret.
+
+    NOTE: clients can opt for no authentication during registration, in which case this
+    logic is skipped.
+    """
+
+    def __init__(self, provider: OAuthAuthorizationServerProvider[Any, Any, Any]):
+        """Initialize the authenticator.
+
+        Args:
+            provider: Provider to look up client information
+        """
+        self.provider = provider
+
+    async def authenticate_request(self, request: Request) -> OAuthClientInformationFull:
+        """Authenticate a client from an HTTP request.
+
+        Extracts client credentials from the appropriate location based on the
+        client's registered authentication method and validates them.
+
+        Args:
+            request: The HTTP request containing client credentials
+
+        Returns:
+            The authenticated client information
+
+        Raises:
+            AuthenticationError: If authentication fails
+        """
+        form_data = await request.form()
+        client_id = form_data.get("client_id")
+        if not client_id:
+            raise AuthenticationError("Missing client_id")
+
+        client = await self.provider.get_client(str(client_id))
+        if not client:
+            raise AuthenticationError("Invalid client_id")  # pragma: no cover
+
+        request_client_secret: str | None = None
+        auth_header = request.headers.get("Authorization", "")
+
+        if client.token_endpoint_auth_method == "client_secret_basic":
+            if not auth_header.startswith("Basic "):
+                raise AuthenticationError("Missing or invalid Basic authentication in Authorization header")
+
+            try:
+                encoded_credentials = auth_header[6:]  # Remove "Basic " prefix
+                decoded = base64.b64decode(encoded_credentials).decode("utf-8")
+                if ":" not in decoded:
+                    raise ValueError("Invalid Basic auth format")
+                basic_client_id, request_client_secret = decoded.split(":", 1)
+
+                # URL-decode both parts per RFC 6749 Section 2.3.1
+                basic_client_id = unquote(basic_client_id)
+                request_client_secret = unquote(request_client_secret)
+
+                if basic_client_id != client_id:
+                    raise AuthenticationError("Client ID mismatch in Basic auth")
+            except (ValueError, UnicodeDecodeError, binascii.Error):
+                raise AuthenticationError("Invalid Basic authentication header")
+
+        elif client.token_endpoint_auth_method == "client_secret_post":
+            raw_form_data = form_data.get("client_secret")
+            # form_data.get() can return an UploadFile or None, so we need to check if it's a string
+            if isinstance(raw_form_data, str):
+                request_client_secret = str(raw_form_data)
+
+        elif client.token_endpoint_auth_method == "none":
+            request_client_secret = None
+        else:
+            raise AuthenticationError(  # pragma: no cover
+                f"Unsupported auth method: {client.token_endpoint_auth_method}"
+            )
+
+        # A client registered for a secret-based auth method but with no stored secret is
+        # misconfigured: nothing was actually verified above, so it must not pass authentication.
+        if client.token_endpoint_auth_method != "none" and not client.client_secret:
+            raise AuthenticationError("Client is registered for secret-based authentication but has no stored secret")
+
+        # If client from the store expects a secret, validate that the request provides
+        # that secret
+        if client.client_secret:
+            if not request_client_secret:
+                raise AuthenticationError("Client secret is required")
+
+            # hmac.compare_digest requires that both arguments are either bytes or a `str` containing
+            # only ASCII characters. Since we do not control `request_client_secret`, we encode both
+            # arguments to bytes.
+            if not hmac.compare_digest(client.client_secret.encode(), request_client_secret.encode()):
+                raise AuthenticationError("Invalid client_secret")
+
+            if client.client_secret_expires_at and client.client_secret_expires_at < int(time.time()):
+                raise AuthenticationError("Client secret has expired")  # pragma: no cover
+
+        return client

.mcp-venv/lib/python3.13/site-packages/mcp/server/auth/provider.py

@@ -0,0 +1,371 @@
+from dataclasses import dataclass
+from typing import Any, Generic, Literal, Protocol, TypeVar
+from urllib.parse import parse_qs, urlencode, urlparse, urlunparse
+
+from pydantic import AnyUrl, BaseModel
+
+from mcp.shared.auth import OAuthClientInformationFull, OAuthToken
+
+
+class AuthorizationParams(BaseModel):
+    state: str | None
+    scopes: list[str] | None
+    code_challenge: str
+    redirect_uri: AnyUrl
+    redirect_uri_provided_explicitly: bool
+    resource: str | None = None  # RFC 8707 resource indicator
+
+
+class IdentityAssertionParams(BaseModel):
+    """Validated parameters of a SEP-990 identity-assertion (RFC 7523 jwt-bearer) request.
+
+    Passed to ``OAuthAuthorizationServerProvider.exchange_identity_assertion``. ``assertion`` is the
+    ID-JAG (a signed JWT) the enterprise identity provider issued; the provider validates it per
+    RFC 7523 §3 and the SEP-990 §5.1 processing rules before issuing an access token.
+    """
+
+    assertion: str  # RFC 7523 §2.1: the JWT (ID-JAG) presented as the authorization grant
+    scopes: list[str] | None = None
+    resource: str | None = None  # RFC 8707 resource indicator from the token request
+
+
+class AuthorizationCode(BaseModel):
+    code: str
+    scopes: list[str]
+    expires_at: float
+    client_id: str
+    code_challenge: str
+    redirect_uri: AnyUrl
+    redirect_uri_provided_explicitly: bool
+    resource: str | None = None  # RFC 8707 resource indicator
+    subject: str | None = None  # resource owner; propagate to the issued AccessToken
+
+
+class RefreshToken(BaseModel):
+    token: str
+    client_id: str
+    scopes: list[str]
+    expires_at: int | None = None
+    subject: str | None = None  # resource owner; propagate to refreshed AccessTokens
+
+
+class AccessToken(BaseModel):
+    token: str
+    client_id: str
+    scopes: list[str]
+    expires_at: int | None = None
+    resource: str | None = None  # RFC 8707 resource indicator
+    subject: str | None = None  # RFC 7662/9068 `sub`: resource owner; unique only per issuer
+    claims: dict[str, Any] | None = None  # additional claims (e.g. `iss`, `act`)
+
+
+def principal_components(token: AccessToken) -> tuple[str, str | None, str | None]:
+    """The (client_id, issuer, subject) triple identifying the principal a token represents.
+
+    The single source for "who is this token's principal": session ownership and
+    request-state binding both build on it. Components the token verifier does
+    not supply are `None`, so comparisons degrade to the remaining components.
+    """
+    issuer = (token.claims or {}).get("iss")
+    return token.client_id, str(issuer) if issuer is not None else None, token.subject
+
+
+RegistrationErrorCode = Literal[
+    "invalid_redirect_uri",
+    "invalid_client_metadata",
+    "invalid_software_statement",
+    "unapproved_software_statement",
+]
+
+
+@dataclass(frozen=True)
+class RegistrationError(Exception):
+    error: RegistrationErrorCode
+    error_description: str | None = None
+
+
+AuthorizationErrorCode = Literal[
+    "invalid_request",
+    "unauthorized_client",
+    "access_denied",
+    "unsupported_response_type",
+    "invalid_scope",
+    "server_error",
+    "temporarily_unavailable",
+    "invalid_target",
+]
+
+
+@dataclass(frozen=True)
+class AuthorizeError(Exception):
+    error: AuthorizationErrorCode
+    error_description: str | None = None
+
+
+TokenErrorCode = Literal[
+    "invalid_request",
+    "invalid_client",
+    "invalid_grant",
+    "unauthorized_client",
+    "unsupported_grant_type",
+    "invalid_scope",
+    # RFC 8707 §2: the requested resource (RFC 8707 indicator) is unknown or unsupported.
+    "invalid_target",
+]
+
+
+@dataclass(frozen=True)
+class TokenError(Exception):
+    error: TokenErrorCode
+    error_description: str | None = None
+
+
+class TokenVerifier(Protocol):
+    """Protocol for verifying bearer tokens."""
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        """Verify a bearer token and return access info if valid."""
+
+
+# NOTE: MCPServer doesn't render any of these types in the user response, so it's
+# OK to add fields to subclasses which should not be exposed externally.
+AuthorizationCodeT = TypeVar("AuthorizationCodeT", bound=AuthorizationCode)
+RefreshTokenT = TypeVar("RefreshTokenT", bound=RefreshToken)
+AccessTokenT = TypeVar("AccessTokenT", bound=AccessToken)
+
+
+class OAuthAuthorizationServerProvider(Protocol, Generic[AuthorizationCodeT, RefreshTokenT, AccessTokenT]):
+    async def get_client(self, client_id: str) -> OAuthClientInformationFull | None:
+        """Retrieves client information by client ID.
+
+        Implementors MAY raise NotImplementedError if dynamic client registration is
+        disabled in ClientRegistrationOptions.
+
+        Args:
+            client_id: The ID of the client to retrieve.
+
+        Returns:
+            The client information, or None if the client does not exist.
+        """
+
+    async def register_client(self, client_info: OAuthClientInformationFull) -> None:
+        """Saves client information as part of registering it.
+
+        Implementors MAY raise NotImplementedError if dynamic client registration is
+        disabled in ClientRegistrationOptions.
+
+        Args:
+            client_info: The client metadata to register.
+
+        Raises:
+            RegistrationError: If the client metadata is invalid.
+        """
+
+    async def authorize(self, client: OAuthClientInformationFull, params: AuthorizationParams) -> str:
+        """Handle the /authorize endpoint and return a URL that the client
+        will be redirected to.
+
+        Many MCP implementations will redirect to a third-party provider to perform
+        a second OAuth exchange with that provider. In this sort of setup, the client
+        has an OAuth connection with the MCP server, and the MCP server has an OAuth
+        connection with the 3rd-party provider. At the end of this flow, the client
+        should be redirected to the redirect_uri from params.redirect_uri.
+
+        +--------+     +------------+     +-------------------+
+        |        |     |            |     |                   |
+        | Client | --> | MCP Server | --> | 3rd Party OAuth   |
+        |        |     |            |     | Server            |
+        +--------+     +------------+     +-------------------+
+                            |   ^                  |
+        +------------+      |   |                  |
+        |            |      |   |    Redirect      |
+        |redirect_uri|<-----+   +------------------+
+        |            |
+        +------------+
+
+        Implementations will need to define another handler on the MCP server's return
+        flow to perform the second redirect, and generate and store an authorization
+        code as part of completing the OAuth authorization step.
+
+        Implementations SHOULD generate an authorization code with at least 160 bits of
+        entropy,
+        and MUST generate an authorization code with at least 128 bits of entropy.
+        See https://datatracker.ietf.org/doc/html/rfc6749#section-10.10.
+
+        Args:
+            client: The client requesting authorization.
+            params: The parameters of the authorization request.
+
+        Returns:
+            A URL to redirect the client to for authorization.
+
+        Raises:
+            AuthorizeError: If the authorization request is invalid.
+        """
+        ...
+
+    async def load_authorization_code(
+        self, client: OAuthClientInformationFull, authorization_code: str
+    ) -> AuthorizationCodeT | None:
+        """Loads an AuthorizationCode by its code.
+
+        Args:
+            client: The client that requested the authorization code.
+            authorization_code: The authorization code to get the challenge for.
+
+        Returns:
+            The AuthorizationCode, or None if not found.
+        """
+        ...
+
+    async def exchange_authorization_code(
+        self, client: OAuthClientInformationFull, authorization_code: AuthorizationCodeT
+    ) -> OAuthToken:
+        """Exchanges an authorization code for an access token and refresh token.
+
+        Args:
+            client: The client exchanging the authorization code.
+            authorization_code: The authorization code to exchange.
+
+        Returns:
+            The OAuth token, containing access and refresh tokens.
+
+        Raises:
+            TokenError: If the request is invalid.
+        """
+        ...
+
+    async def load_refresh_token(self, client: OAuthClientInformationFull, refresh_token: str) -> RefreshTokenT | None:
+        """Loads a RefreshToken by its token string.
+
+        Args:
+            client: The client that is requesting to load the refresh token.
+            refresh_token: The refresh token string to load.
+
+        Returns:
+            The RefreshToken object if found, or None if not found.
+        """
+        ...
+
+    async def exchange_refresh_token(
+        self,
+        client: OAuthClientInformationFull,
+        refresh_token: RefreshTokenT,
+        scopes: list[str],
+    ) -> OAuthToken:
+        """Exchanges a refresh token for an access token and refresh token.
+
+        Implementations SHOULD rotate both the access token and refresh token.
+
+        Args:
+            client: The client exchanging the refresh token.
+            refresh_token: The refresh token to exchange.
+            scopes: Optional scopes to request with the new access token.
+
+        Returns:
+            The OAuth token, containing access and refresh tokens.
+
+        Raises:
+            TokenError: If the request is invalid.
+        """
+        ...
+
+    async def load_access_token(self, token: str) -> AccessTokenT | None:
+        """Loads an access token by its token string.
+
+        Args:
+            token: The access token to verify.
+
+        Returns:
+            The access token, or None if the token is invalid.
+        """
+
+    async def revoke_token(
+        self,
+        token: AccessTokenT | RefreshTokenT,
+    ) -> None:
+        """Revokes an access or refresh token.
+
+        If the given token is invalid or already revoked, this method should do nothing.
+
+        Implementations SHOULD revoke both the access token and its corresponding
+        refresh token, regardless of which of the access token or refresh token is
+        provided.
+
+        Args:
+            token: The token to revoke.
+        """
+
+    async def exchange_identity_assertion(
+        self,
+        client: OAuthClientInformationFull,
+        params: IdentityAssertionParams,
+    ) -> OAuthToken:
+        """Exchanges an Identity Assertion Authorization Grant (ID-JAG) for an access token.
+
+        This is leg 2 of SEP-990: the client presents an ID-JAG - issued by the enterprise
+        identity provider - using the RFC 7523 ``urn:ietf:params:oauth:grant-type:jwt-bearer``
+        grant, and receives an access token for this MCP server. The default implementation
+        rejects every request as an unsupported grant type; override it to enable the grant.
+
+        The implementation is responsible for validating ``params.assertion`` per RFC 7523 §3
+        and the SEP-990 §5.1 processing rules, in particular:
+
+        - verify the JWT signature, ``iss``, and ``exp``, and that ``typ`` is ``oauth-id-jag+jwt``;
+        - require ``aud`` to identify this authorization server (its own issuer);
+        - require a ``sub`` (RFC 7523 §3 makes it mandatory) identifying the end user;
+        - reject replays - enforce ``exp``, and track ``jti`` for the assertion's lifetime;
+        - require the ID-JAG's ``client_id`` claim to match the authenticated ``client`` - do
+          NOT derive authorization from ``client.client_id`` alone, which for a confidential
+          client is authenticated but for any client is ultimately self-asserted in the request;
+        - audience-restrict the issued access token to the resource named in the ID-JAG's
+          ``resource`` claim, not merely ``params.resource`` (which the client controls);
+        - derive the granted scopes from the ID-JAG and policy rather than granting
+          ``params.scopes`` verbatim.
+
+        The handler guarantees ``client`` is confidential (it rejects clients without a stored
+        secret before calling this hook), but the ID-JAG remains the authoritative grant.
+
+        Args:
+            client: The authenticated client presenting the assertion.
+            params: The validated jwt-bearer request parameters (the ID-JAG and indicators).
+
+        Returns:
+            The OAuth token, containing the issued access token. A refresh token SHOULD NOT be
+            issued: SEP-990 relies on the IdP to control session lifetime via re-issued ID-JAGs.
+
+        Raises:
+            TokenError: If the assertion or request is invalid. Use ``invalid_grant`` for a
+                rejected assertion and ``invalid_target`` for an unknown ``resource``.
+        """
+        raise TokenError(
+            error="unsupported_grant_type",
+            error_description="The JWT bearer grant is not supported by this authorization server",
+        )
+
+
+def construct_redirect_uri(redirect_uri_base: str, **params: str | None) -> str:
+    parsed_uri = urlparse(redirect_uri_base)
+    query_params = [(k, v) for k, vs in parse_qs(parsed_uri.query).items() for v in vs]
+    for k, v in params.items():
+        if v is not None:
+            query_params.append((k, v))
+
+    redirect_uri = urlunparse(parsed_uri._replace(query=urlencode(query_params)))
+    return redirect_uri
+
+
+class ProviderTokenVerifier(TokenVerifier):
+    """Token verifier that uses an OAuthAuthorizationServerProvider.
+
+    This is provided for backwards compatibility with existing auth_server_provider
+    configurations. For new implementations using AS/RS separation, consider using
+    the TokenVerifier protocol with a dedicated implementation like IntrospectionTokenVerifier.
+    """
+
+    def __init__(self, provider: "OAuthAuthorizationServerProvider[AuthorizationCode, RefreshToken, AccessToken]"):
+        self.provider = provider
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        """Verify token using the provider's load_access_token method."""
+        return await self.provider.load_access_token(token)

.mcp-venv/lib/python3.13/site-packages/mcp/server/auth/routes.py

@@ -0,0 +1,262 @@
+from collections.abc import Awaitable, Callable
+from typing import Any
+from urllib.parse import urlparse
+
+from pydantic import AnyHttpUrl
+from starlette.middleware.cors import CORSMiddleware
+from starlette.requests import Request
+from starlette.responses import Response
+from starlette.routing import Route, request_response  # type: ignore
+from starlette.types import ASGIApp
+
+from mcp.server.auth.handlers.authorize import AuthorizationHandler
+from mcp.server.auth.handlers.metadata import MetadataHandler, ProtectedResourceMetadataHandler
+from mcp.server.auth.handlers.register import RegistrationHandler
+from mcp.server.auth.handlers.revoke import RevocationHandler
+from mcp.server.auth.handlers.token import TokenHandler
+from mcp.server.auth.middleware.client_auth import ClientAuthenticator
+from mcp.server.auth.provider import OAuthAuthorizationServerProvider
+from mcp.server.auth.settings import ClientRegistrationOptions, RevocationOptions
+from mcp.shared.auth import JWT_BEARER_GRANT_TYPE, OAuthMetadata, ProtectedResourceMetadata
+from mcp.shared.inbound import MCP_PROTOCOL_VERSION_HEADER
+
+
+def validate_issuer_url(url: AnyHttpUrl):
+    """Validate that the issuer URL meets OAuth 2.0 requirements.
+
+    Args:
+        url: The issuer URL to validate.
+
+    Raises:
+        ValueError: If the issuer URL is invalid.
+    """
+
+    # RFC 8414 requires HTTPS, but we allow loopback/localhost HTTP for testing
+    if url.scheme != "https" and url.host not in ("localhost", "127.0.0.1", "[::1]"):
+        raise ValueError("Issuer URL must be HTTPS")
+
+    # No fragments or query parameters allowed
+    if url.fragment:
+        raise ValueError("Issuer URL must not have a fragment")
+    if url.query:
+        raise ValueError("Issuer URL must not have a query string")
+
+
+AUTHORIZATION_PATH = "/authorize"
+TOKEN_PATH = "/token"
+REGISTRATION_PATH = "/register"
+REVOCATION_PATH = "/revoke"
+
+# SEP-990: leg 2 uses the RFC 7523 jwt-bearer grant; support is advertised as the ID-JAG profile.
+ID_JAG_GRANT_PROFILE = "urn:ietf:params:oauth:grant-profile:id-jag"
+
+
+def cors_middleware(
+    handler: Callable[[Request], Response | Awaitable[Response]],
+    allow_methods: list[str],
+) -> ASGIApp:
+    cors_app = CORSMiddleware(
+        app=request_response(handler),
+        allow_origins="*",
+        allow_methods=allow_methods,
+        allow_headers=[MCP_PROTOCOL_VERSION_HEADER],
+    )
+    return cors_app
+
+
+def create_auth_routes(
+    provider: OAuthAuthorizationServerProvider[Any, Any, Any],
+    issuer_url: AnyHttpUrl,
+    service_documentation_url: AnyHttpUrl | None = None,
+    client_registration_options: ClientRegistrationOptions | None = None,
+    revocation_options: RevocationOptions | None = None,
+    identity_assertion_enabled: bool = False,
+) -> list[Route]:
+    validate_issuer_url(issuer_url)
+
+    client_registration_options = client_registration_options or ClientRegistrationOptions()
+    revocation_options = revocation_options or RevocationOptions()
+    metadata = build_metadata(
+        issuer_url,
+        service_documentation_url,
+        client_registration_options,
+        revocation_options,
+        supports_identity_assertion=identity_assertion_enabled,
+    )
+    client_authenticator = ClientAuthenticator(provider)
+
+    # Create routes
+    # Allow CORS requests for endpoints meant to be hit by the OAuth client
+    # (with the client secret). This is intended to support things like MCP Inspector,
+    # where the client runs in a web browser.
+    routes = [
+        Route(
+            "/.well-known/oauth-authorization-server",
+            endpoint=cors_middleware(
+                MetadataHandler(metadata).handle,
+                ["GET", "OPTIONS"],
+            ),
+            methods=["GET", "OPTIONS"],
+        ),
+        Route(
+            AUTHORIZATION_PATH,
+            # do not allow CORS for authorization endpoint;
+            # clients should just redirect to this
+            endpoint=AuthorizationHandler(provider).handle,
+            methods=["GET", "POST"],
+        ),
+        Route(
+            TOKEN_PATH,
+            endpoint=cors_middleware(
+                TokenHandler(
+                    provider, client_authenticator, identity_assertion_enabled=identity_assertion_enabled
+                ).handle,
+                ["POST", "OPTIONS"],
+            ),
+            methods=["POST", "OPTIONS"],
+        ),
+    ]
+
+    if client_registration_options.enabled:  # pragma: no branch
+        registration_handler = RegistrationHandler(
+            provider,
+            options=client_registration_options,
+        )
+        routes.append(
+            Route(
+                REGISTRATION_PATH,
+                endpoint=cors_middleware(
+                    registration_handler.handle,
+                    ["POST", "OPTIONS"],
+                ),
+                methods=["POST", "OPTIONS"],
+            )
+        )
+
+    if revocation_options.enabled:  # pragma: no branch
+        revocation_handler = RevocationHandler(provider, client_authenticator)
+        routes.append(
+            Route(
+                REVOCATION_PATH,
+                endpoint=cors_middleware(
+                    revocation_handler.handle,
+                    ["POST", "OPTIONS"],
+                ),
+                methods=["POST", "OPTIONS"],
+            )
+        )
+
+    return routes
+
+
+def build_metadata(
+    issuer_url: AnyHttpUrl,
+    service_documentation_url: AnyHttpUrl | None,
+    client_registration_options: ClientRegistrationOptions,
+    revocation_options: RevocationOptions,
+    supports_identity_assertion: bool = False,
+) -> OAuthMetadata:
+    authorization_url = AnyHttpUrl(str(issuer_url).rstrip("/") + AUTHORIZATION_PATH)
+    token_url = AnyHttpUrl(str(issuer_url).rstrip("/") + TOKEN_PATH)
+
+    grant_types_supported = ["authorization_code", "refresh_token"]
+    # SEP-990 / ext-auth §6: support for the ID-JAG flow is advertised as a grant PROFILE, not as
+    # the jwt-bearer grant type (which an AS might support for other purposes).
+    authorization_grant_profiles_supported: list[str] | None = None
+    if supports_identity_assertion:
+        grant_types_supported.append(JWT_BEARER_GRANT_TYPE)
+        authorization_grant_profiles_supported = [ID_JAG_GRANT_PROFILE]
+
+    # Create metadata
+    metadata = OAuthMetadata(
+        issuer=issuer_url,
+        authorization_endpoint=authorization_url,
+        token_endpoint=token_url,
+        scopes_supported=client_registration_options.valid_scopes,
+        response_types_supported=["code"],
+        response_modes_supported=None,
+        grant_types_supported=grant_types_supported,
+        token_endpoint_auth_methods_supported=["client_secret_post", "client_secret_basic"],
+        token_endpoint_auth_signing_alg_values_supported=None,
+        service_documentation=service_documentation_url,
+        ui_locales_supported=None,
+        op_policy_uri=None,
+        op_tos_uri=None,
+        introspection_endpoint=None,
+        code_challenge_methods_supported=["S256"],
+        authorization_grant_profiles_supported=authorization_grant_profiles_supported,
+    )
+
+    # Add registration endpoint if supported
+    if client_registration_options.enabled:  # pragma: no branch
+        metadata.registration_endpoint = AnyHttpUrl(str(issuer_url).rstrip("/") + REGISTRATION_PATH)
+
+    # Add revocation endpoint if supported
+    if revocation_options.enabled:  # pragma: no branch
+        metadata.revocation_endpoint = AnyHttpUrl(str(issuer_url).rstrip("/") + REVOCATION_PATH)
+        metadata.revocation_endpoint_auth_methods_supported = ["client_secret_post", "client_secret_basic"]
+
+    return metadata
+
+
+def build_resource_metadata_url(resource_server_url: AnyHttpUrl) -> AnyHttpUrl:
+    """Build RFC 9728 compliant protected resource metadata URL.
+
+    Inserts /.well-known/oauth-protected-resource between host and resource path
+    as specified in RFC 9728 §3.1.
+
+    Args:
+        resource_server_url: The resource server URL (e.g., https://example.com/mcp)
+
+    Returns:
+        The metadata URL (e.g., https://example.com/.well-known/oauth-protected-resource/mcp)
+    """
+    parsed = urlparse(str(resource_server_url))
+    # Handle trailing slash: if path is just "/", treat as empty
+    resource_path = parsed.path if parsed.path != "/" else ""
+    return AnyHttpUrl(f"{parsed.scheme}://{parsed.netloc}/.well-known/oauth-protected-resource{resource_path}")
+
+
+def create_protected_resource_routes(
+    resource_url: AnyHttpUrl,
+    authorization_servers: list[AnyHttpUrl],
+    scopes_supported: list[str] | None = None,
+    resource_name: str | None = None,
+    resource_documentation: AnyHttpUrl | None = None,
+) -> list[Route]:
+    """Create routes for OAuth 2.0 Protected Resource Metadata (RFC 9728).
+
+    Args:
+        resource_url: The URL of this resource server
+        authorization_servers: List of authorization servers that can issue tokens
+        scopes_supported: Optional list of scopes supported by this resource
+        resource_name: Optional human-readable name for this resource
+        resource_documentation: Optional URL to documentation for this resource
+
+    Returns:
+        List of Starlette routes for protected resource metadata
+    """
+    metadata = ProtectedResourceMetadata(
+        resource=resource_url,
+        authorization_servers=authorization_servers,
+        scopes_supported=scopes_supported,
+        resource_name=resource_name,
+        resource_documentation=resource_documentation,
+        # bearer_methods_supported defaults to ["header"] in the model
+    )
+
+    handler = ProtectedResourceMetadataHandler(metadata)
+
+    # RFC 9728 §3.1: Register route at /.well-known/oauth-protected-resource + resource path
+    metadata_url = build_resource_metadata_url(resource_url)
+    # Extract just the path part for route registration
+    parsed = urlparse(str(metadata_url))
+    well_known_path = parsed.path
+
+    return [
+        Route(
+            well_known_path,
+            endpoint=cors_middleware(handler.handle, ["GET", "OPTIONS"]),
+            methods=["GET", "OPTIONS"],
+        )
+    ]

.mcp-venv/lib/python3.13/site-packages/mcp/server/auth/settings.py

@@ -0,0 +1,42 @@
+from pydantic import AnyHttpUrl, BaseModel, ConfigDict, Field
+
+
+class ClientRegistrationOptions(BaseModel):
+    enabled: bool = False
+    client_secret_expiry_seconds: int | None = None
+    valid_scopes: list[str] | None = None
+    default_scopes: list[str] | None = None
+
+
+class RevocationOptions(BaseModel):
+    enabled: bool = False
+
+
+class AuthSettings(BaseModel):
+    # Preserve empty URL paths so a path-less issuer/resource passed as a string keeps its
+    # canonical form (no trailing slash). RFC 8414/9207 issuer comparison is exact string
+    # comparison, so a spurious trailing slash would break it. See PR #2925 for the metadata
+    # models; this applies the same to the server's own configured URLs.
+    model_config = ConfigDict(url_preserve_empty_path=True)
+
+    issuer_url: AnyHttpUrl = Field(
+        ...,
+        description="OAuth authorization server URL that issues tokens for this resource server.",
+    )
+    service_documentation_url: AnyHttpUrl | None = None
+    client_registration_options: ClientRegistrationOptions | None = None
+    revocation_options: RevocationOptions | None = None
+    required_scopes: list[str] | None = None
+    identity_assertion_enabled: bool = Field(
+        default=False,
+        description="Advertise and accept the SEP-990 Identity Assertion Authorization Grant "
+        "(the RFC 7523 jwt-bearer grant carrying an ID-JAG) at the token endpoint, for enterprise "
+        "IdP flows. The provider must implement `exchange_identity_assertion`.",
+    )
+
+    # Resource Server settings (when operating as RS only)
+    resource_server_url: AnyHttpUrl | None = Field(
+        ...,
+        description="The URL of the MCP server to be used as the resource identifier "
+        "and base route to look up OAuth Protected Resource Metadata.",
+    )

.mcp-venv/lib/python3.13/site-packages/mcp/server/caching.py

@@ -0,0 +1,85 @@
+"""Server-side caching hints (SEP-2549, protocol revision 2026-07-28).
+
+Results for the cacheable methods carry `ttlMs`/`cacheScope` freshness hints.
+A handler sets them by returning a result with explicit `ttl_ms`/`cache_scope`
+values; `Server(cache_hints={method: CacheHint(...)})` fills them for handlers
+that don't. Fields the handler set win, per field, so a server-wide hint never
+overrides a handler's explicit choice.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, Literal, TypeVar
+
+import mcp_types as types
+from mcp_types.methods import CACHEABLE_METHODS, CacheableMethod
+
+__all__ = ["CACHEABLE_METHODS", "CacheHint", "CacheableMethod", "apply_cache_hint", "validate_cache_hints"]
+
+
+@dataclass(frozen=True, slots=True)
+class CacheHint:
+    """Freshness hint for one cacheable method's results.
+
+    `ttl_ms` is how long, in milliseconds, a client may consider the result
+    fresh (`0` means immediately stale). `scope` is whether a cached result may
+    be shared across authorization contexts (`"public"`) or only reused within
+    the one that produced it (`"private"`).
+    """
+
+    ttl_ms: int = 0
+    scope: Literal["public", "private"] = "private"
+
+    def __post_init__(self) -> None:
+        if self.ttl_ms < 0:
+            raise ValueError(f"ttl_ms must be >= 0, got {self.ttl_ms}")
+        if self.scope not in ("public", "private"):
+            raise ValueError(f"scope must be 'public' or 'private', got {self.scope!r}")
+
+
+CacheableResultT = TypeVar("CacheableResultT", bound=types.CacheableResult)
+
+
+def apply_cache_hint(result: CacheableResultT, hint: CacheHint) -> CacheableResultT:
+    """Fill `ttl_ms`/`cache_scope` on `result` from `hint`.
+
+    Per-field: a field the handler set explicitly - even to its default value,
+    tracked via `model_fields_set` - is left alone; only unset fields take the
+    hint. A handler constructing results with `model_construct` bypasses that
+    tracking and is treated as having set nothing.
+    """
+    update: dict[str, int | str] = {}
+    if "ttl_ms" not in result.model_fields_set:
+        update["ttl_ms"] = hint.ttl_ms
+    if "cache_scope" not in result.model_fields_set:
+        update["cache_scope"] = hint.scope
+    return result.model_copy(update=update) if update else result
+
+
+def validate_cache_hints(cache_hints: Mapping[Any, Any] | None) -> dict[str, CacheHint]:
+    """Validate a `cache_hints` constructor argument into a plain dict.
+
+    The `Server`/`MCPServer` signatures already close the key set and value
+    type for type-checked callers; this runtime gate is deliberately loose in
+    its parameter so it covers everyone else (e.g. a map deserialized from
+    config) - a bad entry fails at construction, not on the first request to
+    that method.
+
+    Raises:
+        ValueError: If a key is not a cacheable method.
+        TypeError: If a value is not a `CacheHint`.
+    """
+    if cache_hints is None:
+        return {}
+    # repr-format keys so a non-string key raises this ValueError, not a TypeError from sorted/join.
+    unknown = sorted(repr(method) for method in cache_hints if method not in CACHEABLE_METHODS)
+    if unknown:
+        raise ValueError(f"cache_hints keys must be cacheable methods (see CacheableMethod); got: {', '.join(unknown)}")
+    validated: dict[str, CacheHint] = {}
+    for method, hint in cache_hints.items():
+        if not isinstance(hint, CacheHint):
+            raise TypeError(f"cache_hints[{method!r}] must be a CacheHint, got {type(hint).__name__}")
+        validated[method] = hint
+    return validated

.mcp-venv/lib/python3.13/site-packages/mcp/server/connection.py

@@ -0,0 +1,493 @@
+"""`Connection` - per-client connection state and the standalone outbound channel.
+
+Always present on `Context` (never `None`), even in stateless deployments.
+Holds peer info, per-connection scratch `state` and an `exit_stack` for
+teardown, and an `Outbound` for the standalone stream (the SSE GET stream in
+streamable HTTP, or the single duplex stream in stdio).
+
+Construct via the factories: `Connection.from_envelope` for the 2026-era
+single-exchange path (born ready, no back-channel) and `Connection.for_loop`
+for the handshake-driven loop path. Both populate `protocol_version` so the
+kernel reads it as a fact.
+
+`notify` is best-effort: it never raises. If there's no standalone channel
+or the stream has been dropped, the notification is debug-logged and silently
+discarded - server-initiated notifications are inherently advisory.
+`send_raw_request` raises `NoBackChannelError` when there's no channel; `ping`
+is the only spec-sanctioned standalone request.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping
+from contextlib import AsyncExitStack
+from typing import Any, Final, TypeVar, get_args, overload
+
+import anyio
+from mcp_types import (
+    LOG_LEVEL_META_KEY,
+    ClientCapabilities,
+    CreateMessageRequest,
+    CreateMessageResult,
+    ElicitRequest,
+    ElicitResult,
+    EmptyResult,
+    Implementation,
+    InitializeRequestParams,
+    ListRootsRequest,
+    ListRootsResult,
+    LoggingLevel,
+    PingRequest,
+    Request,
+)
+from mcp_types import methods as _methods
+from mcp_types.version import LATEST_HANDSHAKE_VERSION, MODERN_PROTOCOL_VERSIONS
+from pydantic import BaseModel, ValidationError
+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.subscriptions import LISTEN_STREAM_METHODS
+
+__all__ = ["Connection"]
+
+logger = logging.getLogger(__name__)
+# `Connection.log`'s `logger` parameter (public API, the spec's logger-name
+# field) shadows the module logger inside that method; this alias keeps the
+# module logger reachable there.
+_logger = logger
+
+_LOG_LEVELS: Final[tuple[LoggingLevel, ...]] = get_args(LoggingLevel)
+"""Severity-ascending, from the `LoggingLevel` literal's declaration order (the
+RFC 5424 scale) - the literal is the single source of the ordering."""
+
+_ALL_LOG_LEVELS: Final[frozenset[LoggingLevel]] = frozenset(_LOG_LEVELS)
+
+
+def allowed_log_levels(protocol_version: str, meta: Mapping[str, Any] | None) -> frozenset[LoggingLevel]:
+    """The `notifications/message` levels deliverable for one inbound request.
+
+    2026-07-28+ makes log delivery a per-request opt-in (server/utilities/
+    logging): the client sets the reserved `io.modelcontextprotocol/logLevel`
+    `_meta` key, absent means no levels - the server MUST NOT send - and
+    present means that level and above. An unrecognized value reads as absent;
+    spec methods already reject a malformed value at surface validation
+    before any handler runs, so that arm only serves custom methods, where
+    dropping is the safe direction. Connection-scoped emitters pass
+    `meta=None`: `logging/setLevel` is gone at 2026 and log delivery is
+    request-scoped only, so they deliver nothing. Handshake versions keep
+    their `logging/setLevel`-era semantics: every level may be sent, filtering
+    is the application's `logging/setLevel` handler's job as before.
+    """
+    if protocol_version not in MODERN_PROTOCOL_VERSIONS:
+        return _ALL_LOG_LEVELS
+    requested = (meta or {}).get(LOG_LEVEL_META_KEY)
+    if requested not in _LOG_LEVELS:
+        return frozenset()
+    return frozenset(_LOG_LEVELS[_LOG_LEVELS.index(requested) :])
+
+
+ResultT = TypeVar("ResultT", bound=BaseModel)
+
+# Result types for the spec's server-to-client request set, used by
+# `Connection.send_request` to infer the result type. If the spec's request
+# set grows substantially, consider declaring the result mapping on the
+# request types themselves (a `__mcp_result__` ClassVar read via a structural
+# protocol) so this table and the overload ladder don't need maintaining.
+_RESULT_FOR: dict[type[Request[Any, Any]], type[BaseModel]] = {
+    CreateMessageRequest: CreateMessageResult,
+    ElicitRequest: ElicitResult,
+    ListRootsRequest: ListRootsResult,
+    PingRequest: EmptyResult,
+}
+
+
+_ModelT = TypeVar("_ModelT", bound=BaseModel)
+
+
+def _typed(model: type[_ModelT], raw: Any) -> _ModelT | None:
+    """Validate a raw envelope value into a typed model.
+
+    A missing, null or mis-shaped value falls through to `ValidationError`
+    and is treated as not supplied so the request still routes. Spec methods
+    are separately re-validated by the kernel's per-version params surface,
+    which types the reserved `_meta` keys strictly.
+    """
+    try:
+        return model.model_validate(raw, by_name=False)
+    except ValidationError:
+        return None
+
+
+def _notification_params(payload: dict[str, Any] | None, meta: Meta | None) -> dict[str, Any] | None:
+    if not meta:
+        return payload
+    out = dict(payload or {})
+    out["_meta"] = meta
+    return out
+
+
+class _NoChannelOutbound:
+    """Connection-scoped `Outbound` for the no-back-channel case.
+
+    The structural answer to "this connection cannot push to its peer":
+    `send_raw_request` raises `NoBackChannelError`; `notify` drops with a
+    debug log. `Connection.from_envelope` installs this so the modern
+    single-exchange path never needs a mode flag - the channel itself says no.
+    """
+
+    async def send_raw_request(
+        self,
+        method: str,
+        params: Mapping[str, Any] | None,
+        opts: CallOptions | None = None,
+    ) -> dict[str, Any]:
+        raise NoBackChannelError(method)
+
+    async def notify(self, method: str, params: Mapping[str, Any] | None, opts: CallOptions | None = None) -> None:
+        logger.debug("dropped %s: no standalone channel", method)
+
+
+_NO_CHANNEL = _NoChannelOutbound()
+
+
+class NotifyOnlyOutbound(_NoChannelOutbound):
+    """Connection-scoped `Outbound` that forwards notifications and refuses requests.
+
+    Installed by `serve_dual_era_loop` for modern (2026-07-28+) connections
+    over duplex stream transports: the pipe is real, so server notifications
+    ride it, but the modern protocol forbids server-initiated JSON-RPC
+    requests, so `send_raw_request` (inherited) refuses by construction.
+
+    Change notifications (`notifications/*/list_changed`,
+    `notifications/resources/updated`) are dropped with a debug log: at this
+    era they reach a client only through a `subscriptions/listen` stream it
+    opened, so a bare copy on the shared channel would be an unrequested
+    notification. Publish them on the server's `SubscriptionBus` instead.
+    """
+
+    def __init__(self, outbound: Outbound) -> None:
+        self._outbound = outbound
+
+    async def notify(self, method: str, params: Mapping[str, Any] | None, opts: CallOptions | None = None) -> None:
+        # At the 2026-07-28 era these are `subscriptions/listen` stream goods
+        # only: the spec forbids sending a change notification a subscription
+        # did not request, and listen streams deliver them (stamped, filtered)
+        # via the request-scoped outbound, never this connection-scoped channel.
+        if method in LISTEN_STREAM_METHODS:
+            logger.debug("dropped %s: delivered via subscriptions/listen at this era", method)
+            return
+        await self._outbound.notify(method, params, opts)
+
+
+class Connection:
+    """Per-client connection state and standalone-stream `Outbound`.
+
+    Construct via `from_envelope` (modern single-exchange: born ready, no
+    back-channel) or `for_loop` (handshake-driven: ready once the client's
+    `notifications/initialized` arrives). Either way `protocol_version` is
+    populated at construction.
+    """
+
+    outbound: Outbound
+    """The connection-scoped channel for server-initiated messages."""
+
+    session_id: str | None
+
+    client_capabilities: ClientCapabilities | None
+    """The capabilities the peer declared: the handshake's on the loop path,
+    the request envelope's on the modern path. `None` when none were declared.
+    Kept in lockstep with `client_params` by its setter, and settable on its
+    own for the modern envelope, where capabilities are required but client
+    info is optional (spec PR #3002) - capability checks must not depend on the
+    peer having identified itself."""
+
+    protocol_version: str
+    """The protocol version this connection speaks. Populated at construction
+    by the factory and overwritten by `_handle_initialize` once the handshake
+    commits on the loop path."""
+
+    initialized: anyio.Event
+    """Set when `notifications/initialized` arrives (matches TS `oninitialized`);
+    the point from which the spec permits server-initiated requests beyond
+    ping/logging. Pre-set on connections built via `from_envelope`."""
+
+    state: dict[str, Any]
+    """Per-connection scratch state; persists across requests on this connection."""
+
+    exit_stack: AsyncExitStack
+    """Per-connection teardown, unwound LIFO (shielded) when the connection
+    closes. Push cleanup from handlers or middleware; exceptions are logged
+    and swallowed."""
+
+    def __init__(
+        self,
+        outbound: Outbound,
+        *,
+        protocol_version: str,
+        session_id: str | None = None,
+        client_params: InitializeRequestParams | None = None,
+    ) -> None:
+        self.outbound = outbound
+        self.protocol_version = protocol_version
+        self.session_id = session_id
+        self.client_capabilities = None
+        self.client_params = client_params
+        self.initialized = anyio.Event()
+        self.state = {}
+        self.exit_stack = AsyncExitStack()
+
+    @property
+    def client_params(self) -> InitializeRequestParams | None:
+        """The full `initialize` request params, or the equivalent built from the
+        2026-era envelope. `None` when no client info was supplied."""
+        return self._client_params
+
+    @client_params.setter
+    def client_params(self, value: InitializeRequestParams | None) -> None:
+        # Assignment is the sync point: recording full client params (the
+        # handshake commit, or a modern envelope carrying client info) also
+        # records the capabilities fact, so the two can never drift. Clearing
+        # to `None` leaves `client_capabilities` alone - the modern envelope
+        # declares capabilities without client info.
+        self._client_params = value
+        if value is not None:
+            self.client_capabilities = value.capabilities
+
+    @classmethod
+    def from_envelope(
+        cls,
+        protocol_version: str,
+        client_info: Any,
+        client_capabilities: Any,
+        *,
+        outbound: Outbound = _NO_CHANNEL,
+    ) -> Connection:
+        """A born-ready connection populated from a request's `_meta` envelope.
+
+        `protocol_version` must be an already-validated version string - the
+        inbound classification ladder owns rejecting non-string or unsupported
+        values. `client_info` and `client_capabilities` are the raw envelope
+        values: this constructor owns turning them into connection identity,
+        identically on every modern entry, so a mis-shaped value degrades to
+        not-supplied rather than failing the request. `initialized` is set,
+        well-formed capabilities are recorded as `client_capabilities` (client
+        info is optional per spec PR #3002, so capability checks never depend on
+        it), and the full `client_params` is additionally synthesized when
+        client info was supplied too. `outbound` defaults to the no-channel
+        sentinel for the single-exchange HTTP path; duplex modern transports
+        (e.g. stdio) pass a notify-only wrapper around the dispatcher so
+        server notifications ride the pipe while server-initiated requests
+        stay refused.
+        """
+        info = _typed(Implementation, client_info)
+        capabilities = _typed(ClientCapabilities, client_capabilities)
+        client_params = None
+        if info is not None and capabilities is not None:
+            client_params = InitializeRequestParams(
+                protocol_version=protocol_version,
+                capabilities=capabilities,
+                client_info=info,
+            )
+        connection = cls(outbound, protocol_version=protocol_version, client_params=client_params)
+        connection.client_capabilities = capabilities
+        connection.initialized.set()
+        return connection
+
+    @classmethod
+    def for_loop(
+        cls,
+        outbound: Outbound,
+        *,
+        session_id: str | None = None,
+        protocol_version_hint: str | None = None,
+    ) -> Connection:
+        """A connection for the handshake-driven loop path.
+
+        Not born-ready: `initialized` is set later by the kernel when
+        `notifications/initialized` arrives. `protocol_version` is seeded from
+        the transport hint (or `LATEST_HANDSHAKE_VERSION`) so it's never `None`;
+        the handshake overwrites it once negotiated.
+        """
+        return cls(
+            outbound,
+            protocol_version=protocol_version_hint if protocol_version_hint is not None else LATEST_HANDSHAKE_VERSION,
+            session_id=session_id,
+        )
+
+    @property
+    def has_standalone_channel(self) -> bool:
+        """Whether this connection has a real back-channel for server-initiated
+        messages. Derived from `outbound` - the no-channel sentinel is the only
+        case that doesn't.
+
+        Channel presence, not request permission: a modern (2026-07-28+)
+        duplex connection has a channel that carries notifications while
+        `send_raw_request` still refuses, because the protocol forbids
+        server-initiated requests."""
+        return self.outbound is not _NO_CHANNEL
+
+    @property
+    def initialize_accepted(self) -> bool:
+        """True once the inbound request gate is open: `initialize` recorded the
+        peer info, or the handshake completed outright (born-ready, or a bare
+        `notifications/initialized`). Derived, never stored."""
+        return self.client_params is not None or self.initialized.is_set()
+
+    async def send_raw_request(
+        self,
+        method: str,
+        params: Mapping[str, Any] | None,
+        opts: CallOptions | None = None,
+    ) -> dict[str, Any]:
+        """Send a raw request on the standalone stream.
+
+        Low-level `Outbound` channel. Prefer the typed `send_request` or the
+        convenience methods below; use this directly only for off-spec
+        messages. `opts` carries per-call `timeout` / `on_progress` /
+        resumption hints; see `CallOptions`.
+
+        Raises:
+            MCPError: The peer responded with an error.
+            NoBackChannelError: no back-channel for server-initiated requests -
+                `has_standalone_channel` is `False`, or a modern (2026-07-28+)
+                connection, where the protocol forbids them.
+        """
+        return await self.outbound.send_raw_request(method, params, opts)
+
+    @overload
+    async def send_request(
+        self, req: CreateMessageRequest, *, opts: CallOptions | None = None
+    ) -> CreateMessageResult: ...
+    @overload
+    async def send_request(self, req: ElicitRequest, *, opts: CallOptions | None = None) -> ElicitResult: ...
+    @overload
+    async def send_request(self, req: ListRootsRequest, *, opts: CallOptions | None = None) -> ListRootsResult: ...
+    @overload
+    async def send_request(self, req: PingRequest, *, opts: CallOptions | None = None) -> EmptyResult: ...
+    @overload
+    async def send_request(
+        self, req: Request[Any, Any], *, result_type: type[ResultT], opts: CallOptions | None = None
+    ) -> ResultT: ...
+    async def send_request(
+        self,
+        req: Request[Any, Any],
+        *,
+        result_type: type[BaseModel] | None = None,
+        opts: CallOptions | None = None,
+    ) -> BaseModel:
+        """Send a typed server-to-client request and return its typed result.
+
+        For spec request types the result type is inferred. For custom requests
+        pass `result_type=` explicitly.
+
+        Raises:
+            MCPError: The peer responded with an error.
+            NoBackChannelError: No back-channel for server-initiated requests.
+            pydantic.ValidationError: The peer's result does not match the expected result type.
+            KeyError: `result_type` omitted for a non-spec request type.
+        """
+        raw = await self.send_raw_request(req.method, dump_params(req.params), opts)
+        if req.method in _methods.MONOLITH_REQUESTS:
+            try:
+                _methods.validate_client_result(req.method, self.protocol_version, raw)
+            except KeyError:
+                pass
+        cls = result_type if result_type is not None else _RESULT_FOR[type(req)]
+        return cls.model_validate(raw, by_name=False)
+
+    async def notify(self, method: str, params: Mapping[str, Any] | None, opts: CallOptions | None = None) -> None:
+        """Send a best-effort notification on the standalone stream.
+
+        Never raises. If there's no standalone channel or the stream is broken,
+        the notification is dropped and debug-logged.
+        """
+        try:
+            await self.outbound.notify(method, params, opts)
+        except (anyio.BrokenResourceError, anyio.ClosedResourceError):
+            logger.debug("dropped %s: standalone stream closed", method)
+
+    async def ping(self, *, meta: Meta | None = None, opts: CallOptions | None = None) -> None:
+        """Send a `ping` request on the standalone stream.
+
+        Raises:
+            MCPError: The peer responded with an error.
+            NoBackChannelError: no back-channel for server-initiated requests -
+                `has_standalone_channel` is `False`, or a modern (2026-07-28+)
+                connection, where the protocol forbids them.
+        """
+        await self.send_raw_request("ping", dump_params(None, meta), opts)
+
+    @deprecated("The logging capability is deprecated as of 2026-07-28 (SEP-2577).", category=MCPDeprecationWarning)
+    async def log(self, level: LoggingLevel, data: Any, logger: str | None = None, *, meta: Meta | None = None) -> None:
+        """Send a `notifications/message` log entry on the standalone stream. Best-effort.
+
+        On 2026-07-28+ connections this never sends: log delivery is a
+        per-request opt-in that rides the requesting stream (`ctx.log`,
+        `ctx.session.send_log_message`), and the standalone stream is
+        forbidden from carrying `notifications/message`, so the entry is
+        debug-logged and dropped.
+        """
+        if level not in allowed_log_levels(self.protocol_version, None):
+            _logger.debug("dropped notifications/message: no connection-wide log delivery at %s", self.protocol_version)
+            return
+        params: dict[str, Any] = {"level": level, "data": data}
+        if logger is not None:
+            params["logger"] = logger
+        await self.notify("notifications/message", _notification_params(params, meta))
+
+    async def send_tool_list_changed(self, *, meta: Meta | None = None) -> None:
+        await self.notify("notifications/tools/list_changed", _notification_params(None, meta))
+
+    async def send_prompt_list_changed(self, *, meta: Meta | None = None) -> None:
+        await self.notify("notifications/prompts/list_changed", _notification_params(None, meta))
+
+    async def send_resource_list_changed(self, *, meta: Meta | None = None) -> None:
+        await self.notify("notifications/resources/list_changed", _notification_params(None, meta))
+
+    async def send_resource_updated(self, uri: str, *, meta: Meta | None = None) -> None:
+        await self.notify("notifications/resources/updated", _notification_params({"uri": uri}, meta))
+
+    def check_capability(self, capability: ClientCapabilities) -> bool:
+        """Return whether the connected client declared the given capability.
+
+        Returns `False` when no capabilities have been recorded.
+        """
+        # TODO(L53): redesign - mirrors v1 ServerSession.check_client_capability
+        # verbatim for parity.
+        if self.client_capabilities is None:
+            return False
+        have = self.client_capabilities
+        if capability.roots is not None:
+            if have.roots is None:
+                return False
+            if capability.roots.list_changed and not have.roots.list_changed:
+                return False
+        if capability.sampling is not None:
+            if have.sampling is None:
+                return False
+            if capability.sampling.context is not None and have.sampling.context is None:
+                return False
+            if capability.sampling.tools is not None and have.sampling.tools is None:
+                return False
+        if capability.elicitation is not None and have.elicitation is None:
+            return False
+        if capability.experimental is not None:
+            if have.experimental is None:
+                return False
+            for k, v in capability.experimental.items():
+                if k not in have.experimental or have.experimental[k] != v:
+                    return False
+        if capability.extensions is not None:
+            # SEP-2133: an extension is supported when the client declares its
+            # identifier. Settings are negotiated per-extension (the client may
+            # advertise more than the server asks for), so presence - not value
+            # equality - is the meaningful check.
+            if have.extensions is None:
+                return False
+            for identifier in capability.extensions:
+                if identifier not in have.extensions:
+                    return False
+        return True