Feat/mcp 2026 07 28

AGENTS.md

@@ -2,6 +2,7 @@
 ## fast-agent contributor notes
 
 - Use `uv run` for repo scripts and examples.
+- Use the fast-agent CLI to start sub-agent tasks. Use gpt-5.6-terra?reasoning=high as the primary model for this. Escalate to the user if you want bigger or smaller models.
 - Always run `uv run scripts/lint.py` and `uv run scripts/typecheck.py` after code changes.
 - Check the type safety rules in `typesafe.md` and avoid hasattr/getattr style checks
 - Avoid unnecessary defensive programming. Validate at boundaries and use static analysis and type safety rules to write concise code. Do not caveat without good cause (external data processing for example).

docs-internal/mcp-2026-07-28-functional-deficits.md

@@ -0,0 +1,30 @@
+# MCP 2026-07-28 functional-deficit ledger
+
+This ledger records behavior intentionally not reimplemented during the MCP
+SDK v2 / FastMCP v4 migration. Entries remain open until functionality is
+restored, replaced, or explicitly removed as a product decision.
+
+| ID | Area | Deficit | Reason | Recovery |
+| --- | --- | --- | --- | --- |
+| MCP2-001 | HTTP diagnostics | Exact POST JSON/SSE response mode, GET, and resumption message counters are no longer collected. | SDK v2 exposes no public low-level diagnostics hook; modern MCP also removes GET and resumption. | Keep operation-level status. Add an upstream diagnostics hook only if response-mode telemetry remains valuable. |
+| MCP2-002 | Legacy session diagnostics | `Mcp-Session-Id` is not captured from the SDK v2 Streamable HTTP transport. | SDK v2 intentionally removed the session-ID callback from its public transport contract. | Show no session for modern peers. Recover legacy-only IDs if FastMCP/SDK adds a public accessor. |
+| MCP2-003 | Modern health | Periodic MCP ping is disabled after modern negotiation. | MCP 2026-07-28 removes `ping`. | Use negotiation, operation success/error, subscription state, and stdio process state. |
+| MCP2-004 | HTTP OAuth events | Existing detailed OAuth timing and paste-fallback behavior still depends on the migrated SDK provider subclass. | FastMCP v4's public OAuth API does not expose equivalent event and paste hooks. | Replace the subclass when upstream exposes lifecycle callbacks; retain focused compatibility tests meanwhile. |
+| MCP2-005 | Transport result channel | Tool results no longer receive a synthetic `transport_channel` attribute. | Request IDs and response channels are dispatcher internals in SDK v2. | Record operation timing/status externally; request a public diagnostics hook if exact channel attribution is required. |
+| MCP2-007 | MCP OpenTelemetry auto-instrumentation | `opentelemetry-instrumentation-mcp==0.62.1` is not activated. | It patches the removed SDK v1 symbol `mcp.client.streamable_http.streamablehttp_client` and crashes telemetry setup with SDK v2. | Re-enable `McpInstrumentor` when an SDK-v2-compatible release is available; fast-agent's own MCP progress and timing telemetry remains active. |
+| MCP3-003 | Subscription replay | A dropped modern subscription may lose events before reconnection. | MCP subscriptions have no replay. | The supervisor reopens with bounded backoff; perform full derived-index refresh after reconnection when upstream exposes an acknowledgment/restart barrier suitable for this lifecycle. |
+| MCP3-004 | Resource subscriptions | The initial supervisor listens for list changes but does not yet maintain a dynamic set of individual resource URIs. | Fast-agent only materializes selected Skybridge resources and the filter is immutable. | Rebuild observed URIs after resource-list refresh and restart the listener with that set. |
+| MCP3-005 | Shared cache | No persistent or cross-principal protocol response cache is provided. | Safe sharing requires verified principal partitioning and stable server identity. | Keep future shared caching opt-in and default `share_public=False`. |
+| MCP3-006 | FastMCP elicitation examples | FastMCP v4 `Context.elicit()` still uses a standalone server-to-client request, which SDK v2 rejects on a negotiated `2026-07-28` connection. Three existing custom-handler integration cases therefore fail even though the SDK-native MRTR path succeeds. | FastMCP `4.0.0a2` does not expose the SDK `MCPServer` resolver/InputRequired API. | Migrate the examples to SDK `MCPServer` + `Resolve(Elicit(...))`, or adopt the FastMCP MRTR API when one is public. |
+| MCP3-007 | State-transfer example | The current harness MCP server exposes agent tools but no `<agent>_history` prompt, so `examples/mcp/state-transfer` can send a turn but cannot transfer it through the documented prompt. | The prompt surface was absent before this protocol migration and is not restored by the FastMCP v4 update. | Add a session-scoped history prompt to `HarnessMCPAppServer` and notify prompt-list subscribers when the first history entry is created. |
+| MCP3-008 | Modern stdio subscriptions | `subscriptions/listen` is reported as unsupported on modern stdio connections. | SDK v2's server rejects the request with `subscriptions/listen is not served over this transport`; its streaming response contract is implemented for Streamable HTTP. | Retain ordinary stdio list-change notifications if the modern specification adds them, or enable listen when the SDK server transport supports streaming responses over stdio. |
+| MCP3-009 | Sampling tool choice | Fast-agent advertises `sampling.tools`, but the provider-neutral sampling bridge does not yet enforce MCP `toolChoice.mode="required"` or `"none"` uniformly across providers. | Fast-agent's generic `RequestParams` has no provider-neutral tool-choice field; provider wire shapes differ. | Add a provider-neutral tool-choice policy at the LLM boundary, then map it in each provider before expanding sampling support further. |
+| MCP3-010 | FastMCP sampling/roots examples | Existing FastMCP integration servers call `Context.session.create_message()` and `list_roots()` as standalone server-initiated requests. After modern negotiation the SDK rejects them because 2026-07-28 requires embedded MRTR input requests. | FastMCP v4's context helpers still expose the legacy standalone path; SDK `MCPServer` exposes modern `Resolve(Sample(...))` and `Resolve(ListRoots())`. | Migrate the examples and integration simulators to SDK resolver inputs, or adopt equivalent FastMCP resolver APIs when public. Keep legacy-server callback coverage separately. |
+
+## Resolved during the high-level client refactor
+
+| ID | Resolution |
+| --- | --- |
+| MCP2-006 | All negotiation now runs through public `mcp.client.Client(mode="auto")`; fast-agent no longer imports `_probe.negotiate_auto`. |
+| MCP3-001 | Tool, prompt, and resource MRTR now use the SDK high-level client; the custom `*_complete` methods and private input-required driver were removed. |
+| MCP3-002 | Attached runtimes use the SDK's default per-client response cache. Request-scoped clients disable caching to preserve authorization isolation. Modern subscription refresh uses `Client.listen()`, including the SDK cache-eviction barrier. |