docs: document progressToken usage in transport features

ContextVM-org · ContextVM-org · commit bb13dcb304c9 · 2026-05-12T15:58:59.000+02:00
Adds documentation explaining how the MCP request progressToken enables request-scoped transport features (CEP-22 oversized transfer and CEP-41 open streams). Covers high-level SDK automatic token creation versus low-level manual request requirements, and recommends resetTimeoutOnProgress for long-running requests.
diff --git a/src/content/docs/ts-sdk/transports/nostr-client-transport.md b/src/content/docs/ts-sdk/transports/nostr-client-transport.md
@@ -117,6 +117,17 @@ This keeps the active relay set minimal and avoids automatically merging every p
     - If the message is a **response** (correlated by the original event ID), it is passed to the MCP client to resolve the pending request.
     - If the message is a **notification**, it is emitted through the `onmessage` handler.
 
+## Progress Tokens and Request-Scoped Transport Features
+
+Some transport features are activated per request, not just per transport instance.
+
+- [Oversized Transfer](/ts-sdk/transports/oversized-transfer) uses the MCP request `progressToken` as the CEP-22 transfer identifier.
+- [Open Stream](/ts-sdk/transports/open-stream) uses the MCP request `progressToken` as the CEP-41 stream identifier.
+
+When you use the MCP TypeScript SDK through high-level request APIs and provide an `onprogress` callback, the SDK usually creates that token automatically. When you construct raw requests manually, you must provide the token yourself if you want request-scoped progress-based transport features to activate.
+
+For requests that may receive progress notifications over a longer period, `resetTimeoutOnProgress: true` is the recommended client-side setting. On the MCP TypeScript SDK low-level `client.request()` path, that timeout-reset behavior is effective when `onprogress` is also provided.
+
 ## Server Discovery and Relay Selection
 
 The client transport accepts a known [`serverPubkey`](contextvm-docs/src/content/docs/ts-sdk/transports/nostr-client-transport.md:28) in multiple forms and can now resolve operational relays automatically when needed.
diff --git a/src/content/docs/ts-sdk/transports/open-stream.md b/src/content/docs/ts-sdk/transports/open-stream.md
@@ -116,6 +116,8 @@ If your application already has its own request correlation or tracing scheme, y
 
 This is why the helper is usually preferable to assembling the request metadata and session correlation manually.
 
+For consistency with other progress-based transport features such as [Oversized Transfer](/ts-sdk/transports/oversized-transfer), remember that high-level MCP TypeScript SDK usage can usually create the request `progressToken` automatically when `onprogress` is used, while low-level manual requests must provide that token explicitly. On the MCP TypeScript SDK low-level `client.request()` path, `resetTimeoutOnProgress: true` also depends on `onprogress` being provided.
+
 ## Enabling Open Stream on Transports
 
 To use CEP-41 across the Nostr transports, enable `openStream` on both the server and the client transport.
diff --git a/src/content/docs/ts-sdk/transports/oversized-transfer.md b/src/content/docs/ts-sdk/transports/oversized-transfer.md
@@ -22,6 +22,66 @@ With defaults:
 
 This means most consumers do not need to configure anything unless they want stricter limits or different relay-size margins.
 
+## Request Activation and `progressToken`
+
+CEP-22 oversized transfer is request-scoped. It is only available for a logical exchange when the originating MCP request includes a `progressToken`, as described in [CEP-22: Oversized Payload Transfer](/spec/ceps/cep-22).
+
+In practice, this matters most on the client side:
+
+- if you use the MCP TypeScript SDK in the normal high-level way and provide an `onprogress` callback, the SDK assigns the `progressToken` automatically
+- if you build raw JSON-RPC requests manually or bypass the usual MCP client helpers, you must ensure a `progressToken` is present yourself
+- when no `progressToken` is present, oversized transfer cannot activate for that request, so the exchange falls back to ordinary non-fragmented behavior
+
+For the MCP TypeScript SDK's low-level `client.request()` path specifically, `resetTimeoutOnProgress: true` only works when an `onprogress` callback is provided. In that code path the SDK registers the progress handler and manages the request `progressToken` automatically.
+
+This is why oversized transfer usually works transparently for normal MCP client calls, but low-level transport integrations must still understand the request-level activation rule.
+
+### Recommended MCP client usage
+
+When you expect a request may run for a while or may trigger CEP-22 fragmentation, prefer enabling progress handling explicitly:
+
+```typescript
+const result = await client.callTool(
+  {
+    name: 'long-task',
+    arguments: {},
+  },
+  CallToolResultSchema,
+  {
+    onprogress: (progress) => {
+      console.log(
+        `${progress.progress}/${progress.total}: ${progress.message}`,
+      );
+    },
+    timeout: 30_000,
+    resetTimeoutOnProgress: true,
+  },
+);
+```
+
+With this pattern:
+
+- the MCP TypeScript SDK creates the `progressToken` automatically
+- the application receives ordinary MCP progress updates when they are emitted
+- ContextVM transports can also use the same MCP progress channel for CEP-22 transfer frames
+
+### Why `resetTimeoutOnProgress: true` is strongly recommended
+
+CEP-22 frames are carried over MCP `notifications/progress`. That means a valid oversized transfer is itself ongoing request activity, not idle time.
+
+Setting `resetTimeoutOnProgress: true` is therefore strongly recommended because it allows each valid progress notification to extend the request timeout window. Without that, a client may time out a healthy oversized transfer simply because the response is arriving as multiple progress-framed transfer messages before the final JSON-RPC result.
+
+When using the MCP TypeScript SDK, remember that this timeout-reset behavior is tied to `onprogress`. In practice, use both together.
+
+### Low-level transport usage
+
+If you are working below the usual MCP client helpers, such as constructing raw requests for [`NostrClientTransport`](/ts-sdk/transports/nostr-client-transport), treat `progressToken` as part of the activation contract for CEP-22.
+
+- High-level MCP SDK usage with `onprogress` usually handles this automatically.
+- Manual raw requests must include the token explicitly in request metadata.
+- If you omit it, the transport cannot correlate an oversized transfer session for that exchange.
+- For low-level MCP TS SDK `client.request()` calls, `resetTimeoutOnProgress: true` should be paired with `onprogress`; providing your own raw token alone does not enable the SDK-managed timeout reset path.
+
 ## When You Would Change It
 
 Most projects should keep the default behavior.
@@ -110,6 +170,8 @@ If an oversized transfer fails, the transport may surface one of these errors:
 
 - Leave oversized transfer enabled unless you have a specific reason not to.
 - Keep defaults unless you know your relay environment needs different thresholds.
+- Prefer high-level MCP client calls with `onprogress` so the SDK can assign a `progressToken` automatically.
+- Set `resetTimeoutOnProgress: true` for requests that may emit progress or trigger CEP-22 oversized transfer.
 - Tighten `policy` values if you operate in a more adversarial or resource-constrained environment.
 - Refer to [CEP-22: Oversized Payload Transfer](/spec/ceps/cep-22) for protocol-level behavior.
 
