Docs: align client, MCP Apps, OpenAPI, and auth integration examples with current APIs

[strawgate]

Several client-facing and integration docs describe stale API behavior or examples. The issues are docs-only, but they affect high-copy-paste areas: client task handling, MCP Apps routing, OpenAPI request construction, and auth provider setup examples.

Concrete drift found in the docs audit:

• Client task docs omit the input_required status and understate how task.wait() behaves when a task leaves working.
• Client docs should consistently describe CallToolResult.data, raw MCP results via call_tool_mcp, resource version reads, cancellation notifications, and resource-updated notifications.
• MCP Apps architecture docs describe the older _meta.fastmcp.app routing path; current app tools use deterministic hashed backend names and per-tool Prefab renderer resources.
• OpenAPI docs say empty strings are omitted from query params; current request construction skips None, while empty strings remain explicit empty query values.
• Scalekit/auth integration examples use ambiguous placeholders or deprecated patterns; the current provider setup uses base_url, environment_url, resource_id, optional required_scopes, and a JWT verifier configured from those values.

Expected: client, apps, OpenAPI, and auth integration docs should match current public APIs and request-routing behavior so copied examples run as written.

Verified against current code and tests:

• fastmcp_slim/fastmcp/client/client.py
• fastmcp_slim/fastmcp/client/messages.py
• fastmcp_slim/fastmcp/client/tasks.py
• fastmcp_slim/fastmcp/client/mixins/resources.py
• fastmcp_slim/fastmcp/apps/app.py
• fastmcp_slim/fastmcp/server/providers/prefab_synthesis.py
• fastmcp_slim/fastmcp/server/server.py
• fastmcp_slim/fastmcp/utilities/openapi/director.py
• fastmcp_slim/fastmcp/server/auth/providers/scalekit.py
• tests/client/*
• tests/server/tasks/*
• tests/utilities/openapi/test_director.py
• tests/server/auth/providers/test_scalekit.py

A focused local validation pass for the candidate docs updates passed: docs examples, broken links, prek, and client/task/OpenAPI/auth-provider tests.

[marvin-context-protocol]

Claude finished @strawgate's task in 3m 0s —— View job

---

tl;dr: Verified against source code — 4 of the 5 claims have real, confirmed drift. The OpenAPI empty-string claim and the MCP Apps architecture claim are the most impactful. The client tools doc already covers CallToolResult.data and call_tool_mcp, but notifications and tasks docs have genuine gaps. Scalekit docs are already aligned with current code.

Recommendation: Fix the four confirmed docs issues. Highest-value targets are the OpenAPI query-param section (factually wrong) and the architecture doc (describes a routing mechanism that no longer exists). The tasks and notifications gaps are smaller but still worth fixing.

Findings

1. Client tasks: input_required status missing — CONFIRMED

The tasks doc (docs/clients/tasks.mdx:67,119) lists only four statuses: "working", "completed", "failed", "cancelled". But tasks.py:220-221 explicitly includes input_required in the docstring:

state: Desired state ('working', 'input_required', 'completed', 'failed', 'cancelled').
       If None, waits until the task exits the 'working' state (completed, failed, cancelled, input_required, etc.)

The wait() behavior is also understated: the doc says wait(state="completed") but doesn't explain that wait() with no state returns as soon as the task leaves working — including on input_required. The _wait_terminal() method (tasks.py:273-286) shows input_required is NOT terminal, meaning result() keeps waiting through it while bare wait() does not.

Fix: Add input_required to status lists at lines 67 and 119, and clarify wait() behavior in the "Waiting with Control" section.

2. Client notifications: on_cancelled and on_resource_updated missing — CONFIRMED

The Handler Template in docs/clients/notifications.mdx:77-121 lists 7 hooks but omits two that exist in messages.py:

• on_cancelled (messages.py:127) — dispatched at line 59
• on_resource_updated (messages.py:122-124) — dispatched at line 71

Fix: Add both hooks to the Handler Template section.

3. Client tools: CallToolResult.data and call_tool_mcp — ALREADY DOCUMENTED

The tools doc (docs/clients/tools.mdx) already covers:

• CallToolResult.data (lines 57-94, with property card)
• call_tool_mcp() (lines 170-183, with code example)
• Error handling with raise_on_error (lines 116-143)

This claim from the issue appears overstated — the tools page is already aligned. If the concern is about other docs pages not cross-referencing these features, that's a different scope.

4. MCP Apps architecture: stale routing description — CONFIRMED

The architecture doc (docs/apps/architecture.mdx) describes two mechanisms that no longer exist:

a) Shared renderer resource: The doc says (line 88):

"FastMCP registers the renderer as a ui://prefab/renderer.html resource [...] All Prefab tools on a server share this single resource."

But prefab_synthesis.py:142 shows per-tool resources:

uri = f"ui://prefab/tool/{tool_hash}/renderer.html"

And addressing.py:10-12 confirms:

"Each prefab tool gets a unique renderer resource at ui://prefab/tool/<hash>/renderer.html."

b) Tool routing: The doc describes _meta.fastmcp.app tag and get_app_tool bypass (lines 53-77). But the current code uses deterministic hashed backend names (addressing.py:38-40):

def hashed_backend_name(app_name: str, tool_name: str) -> str:
    return f"{hash_tool(app_name, tool_name)}_{tool_name}"

The dispatcher now uses get_tool_by_hash (referenced in app.py:64) instead of get_app_tool. The _meta.fastmcp.app tag still exists for identification, but the routing path is fundamentally different.

Fix: Rewrite the "The shared resource" section and the "Tool call routing" section to describe the hash-based addressing scheme and per-tool renderer resources.

5. OpenAPI query parameter docs: factually incorrect — CONFIRMED

The doc (docs/integrations/openapi.mdx:406-419) states:

"FastMCP only includes query parameters that have non-empty values. Parameters with None values or empty strings are automatically filtered out."

The example shows "brand": "" being excluded with # ❌ Excluded.

But director.py:178-179 only skips None:

if value is None:
    continue  # Skip None values for optional parameters

Empty strings pass through and become explicit empty query values (e.g., ?brand=). This is the most directly user-impacting drift — copy-pasted code from the docs will produce different behavior than described.

Fix: Change the doc text to say only None values are excluded. Update the example to show "brand": "" as # ✅ Included (as ?brand=).

6. Scalekit auth integration — ALREADY ALIGNED

The docs (docs/integrations/scalekit.mdx) already use the current API: base_url, environment_url, resource_id, optional required_scopes. The deprecation warning for mcp_url/client_id is already present (line 48). The code example at line 55 matches scalekit.py:63-76 exactly. No changes needed here.

Action Plan

File 1: docs/clients/tasks.mdx

1. Lines 67, 119: Add "input_required" to status enum lists. Change:

   # status.status is "working", "completed", "failed", or "cancelled"
   

   to:

   # status.status is "working", "input_required", "completed", "failed", or "cancelled"
   

2. Lines 72-80 (Waiting with Control): Add explanation that wait() with no state returns when the task leaves working, which includes input_required. Add an input_required example:

   # Wait for any non-working state (includes input_required, completed, failed, cancelled)
   status = await task.wait(timeout=30.0)
   
   # Wait specifically for input_required
   status = await task.wait(state="input_required", timeout=30.0)

3. Handler Template (lines 109-129): Add "input_required" case to the status handler example.

File 2: docs/clients/notifications.mdx

1. Lines 77-121 (Handler Template): Add the two missing hooks:

   async def on_resource_updated(
       self, message: mcp.types.ResourceUpdatedNotification
   ) -> None:
       """Called when a specific resource has been updated."""
       pass
   
   async def on_cancelled(self, message: mcp.types.CancelledNotification) -> None:
       """Called when the server cancels a request."""
       pass

File 3: docs/apps/architecture.mdx

1. Lines 86-91 (The shared resource): Rewrite to describe per-tool resources at ui://prefab/tool/<hash>/renderer.html. Explain that each Prefab tool gets its own renderer resource, keyed by a deterministic hash of (app_name, tool_name).

2. Lines 67-77 (Tool call routing / get_app_tool bypass): Update to describe hash-based backend names (<hash>_<local_name>) and get_tool_by_hash. The _meta.fastmcp.app tag still exists for identification but routing now uses the hash prefix.

File 4: docs/integrations/openapi.mdx

1. Lines 406-419: Change "non-empty values" to "non-None values". Remove the claim about empty strings being filtered. Update the example:

   "max_price": None,          # ❌ Excluded (None is skipped)
   "brand": "",                # ✅ Included (sent as ?brand=)

Related Files

File	Relevance
fastmcp_slim/fastmcp/client/tasks.py:210-286	wait() and _wait_terminal() — shows input_required handling
fastmcp_slim/fastmcp/client/messages.py:57-129	MessageHandler with on_cancelled and on_resource_updated hooks
fastmcp_slim/fastmcp/server/providers/addressing.py	Hash-based backend tool addressing
fastmcp_slim/fastmcp/server/providers/prefab_synthesis.py:142	Per-tool renderer resource URI
fastmcp_slim/fastmcp/utilities/openapi/director.py:178-179	Query param filtering — only None, not empty strings
fastmcp_slim/fastmcp/server/auth/providers/scalekit.py:63-76	ScalekitProvider constructor — already matches docs
docs/clients/tasks.mdx	Task docs — missing input_required
docs/clients/notifications.mdx	Notification handler template — missing 2 hooks
docs/apps/architecture.mdx	Architecture doc — stale routing/renderer description
docs/integrations/openapi.mdx	OpenAPI docs — wrong empty-string claim

---

Marvin Context Protocol | Type /marvin to interact further

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.