Repository navigation
Description
Description
On a MCPServer running with stateless_http=True (2026-07-28 "modern" path), a client that correctly advertises the MCP Apps extension via the first-class ClientSession(extensions=...) parameter still sees client_supports_apps(ctx) == False inside tool handlers. The per-request params._meta["io.modelcontextprotocol/clientCapabilities"] envelope appears to be parsed into a Connection (Connection.from_envelope) but the handler-visible ServerSession.client_capabilities is None, so the SEP-2133 "degrade gracefully" branch recommended by the SDK's own apps.py docstring is unreachable on this transport.
Environment
- mcp (python-sdk): 2.3.0 (installed from PyPI)
- Python: 3.13
- OS: Windows 10 (platform-independent; transport is pure HTTP)
- Transport: Streamable HTTP,
stateless_http=True,json_response=True
Minimal Reproduction
repro_server.py:
from mcp.server.apps import Apps, client_supports_apps
from mcp.server.mcpserver import MCPServer
from mcp.server.mcpserver.context import Context
apps = Apps()
@apps.tool(resource_uri="ui://repro/app.html",
description="Echoes whether caller negotiated MCP Apps")
async def probe(ctx: Context) -> str:
return f"client_supports_apps={client_supports_apps(ctx)}"
apps.add_html_resource("ui://repro/app.html", "<html><body>repro</body></html>", name="repro")
mcp = MCPServer("repro", extensions=[apps])
if __name__ == "__main__":
mcp.run("streamable-http", host="127.0.0.1", port=8779,
stateless_http=True, json_response=True)repro_client.py:
import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client
UI = "io.modelcontextprotocol/ui"
MIME = "text/html;profile=mcp-app"
async def main() -> None:
async with streamable_http_client("http://127.0.0.1:8779/mcp") as (read, write):
async with ClientSession(read, write,
extensions={UI: {"mimeTypes": [MIME]}}) as session:
await session.initialize()
res = await session.call_tool("probe", {})
print(res.content[0].text)
asyncio.run(main())Run the server, then the client.
Actual
client_supports_apps=False
Expected
client_supports_apps=True
since the client advertised io.modelcontextprotocol/ui with the text/html;profile=mcp-app MIME type — exactly the condition client_supports_apps() checks (mcp/server/apps.py, L217-230).
Additional observations (same setup)
- A hand-crafted HTTP request carrying the same envelope also yields
False:
params._meta = {"io.modelcontextprotocol/protocolVersion": "2026-07-28", "io.modelcontextprotocol/clientCapabilities": {"extensions": {"io.modelcontextprotocol/ui": {"mimeTypes": ["text/html;profile=mcp-app"]}}}, ...}→ inside the handler,ctx.client_capabilities is Noneandctx.request_context.session.client_capabilities is None(verified via an introspection tool). So this is not a client-side stamping issue. tools/listoutput is identical with and without the capability (the server does not filter_meta.ui) — consistent with "degradation lives in the handler", which makes the handler's blindness to capabilities the single broken link.- Bisection — the bug is specific to the modern stateless path. Identical client code run against the identical server with
stateless_http=False(legacyinitializehandshake) printsclient_supports_apps=True. So capability propagation works on the handshake path and breaks only on the 2026-07-28 per-request_metaenvelope path — this looks like wiring in the modern dispatcher rather than an Apps-module defect.
Suspected area (from source reading, not confirmed)
Connection.from_envelope (mcp/server/connection.py) stores the parsed ClientCapabilities, and ServerSession.client_capabilities delegates to self._connection.client_capabilities. On the modern single-exchange HTTP path (runner.py::handle, which builds the envelope connection per request), the session observed by the tool handler does not seem to be backed by that envelope connection — capabilities degrade to None silently, by design of _typed() ("a mis-shaped value degrades to not-supplied").
Related but distinct: #3773 (legacy initialize responses dropping capabilities.extensions) is already fixed; this report is about the modern stateless request path.
Impact
SEP-2133 requires extensions to degrade gracefully, and the SDK ships client_supports_apps() as the canonical way to branch. On stateless Streamable HTTP servers — the deployment shape the 2026-07-28 spec actively encourages — that helper is currently dead code, leaving server authors no in-SDK way to distinguish Apps-capable hosts.
Current workaround
Always dual-output (content text + structuredContent) and let the host ignore _meta.ui; server-side branching is skipped. Fine for most cases, but it forecloses any per-host optimization and contradicts the docstring guidance in apps.py.
Happy to file a PR with a failing conformance scenario if helpful.
Activity
rithishcodespace commentedon Nov 2, 2026
I would like to investigate and work on this issue.
From the reproduction and suspected execution path, I plan to trace how "Connection.from_envelope()`"propagates client capabilities into the handler-visible "ServerSession" in the stateless Streamable HTTP dispatcher.
I'll first reproduce the behavior and identify the exact point where the capabilities are lost, then explore a minimal fix with regression tests covering both stateless and legacy transports.
Please let me know if there are any design considerations or existing workarounds I should account for.
media-ctrl commentedon Nov 3, 2026