docs(mcp): action file uploads — flow, client prerequisites, integrity

[Scra3]

Documents the action file uploads capability of the Forest MCP server, shipping with agent-nodejs #1815 (approved, merging shortly).

Added to the MCP server reference page:

• the requestActionFileUpload tool in the Actions table
• Action file uploads: the 3-step flow (the file never travels through the AI's context window), the zero-config in-memory default and its single-instance limit, the storage backend for replicas/serverless, and both off switches (fileUploads: false / FOREST_MCP_FILE_UPLOADS=false)
• Client prerequisites — the part customers will actually trip on: Claude Code works everywhere including localhost; Claude Desktop/Claude.ai/Cowork need a publicly reachable host and its domain allowed in the sandbox egress allowlist. On managed workspaces both settings (plus adding the connector at all) belong to the workspace admin, stated as such.
• Integrity: single-use URL, user-bound handle, the sha256 pin, size caps — and the observed filename normalization ("a label, not an identifier").

Everything stated was verified end to end against a live agent on Claude Code, Claude Desktop, Claude.ai and Cowork.

🤖 Generated with Claude Code

Note

Document action file uploads for the MCP server, including client prerequisites and integrity details

Adds an "Action file uploads" section to mcp-server.mdx covering the full upload flow, configuration, and constraints.

• Documents two new environment variables: FOREST_MCP_FILE_UPLOADS (toggle) and FOREST_MCP_UPLOAD_STORAGE_MODULE (storage backend), with precedence rules between them.
• Describes the three-step upload flow: request a destination via requestActionFileUpload, perform the HTTPS upload, then pass the file handle to executeAction.
• Adds a "Client prerequisites" subsection noting differences between Claude Code and desktop/web clients, including workspace-admin-controlled settings for outbound HTTPS uploads.
• Adds an "Integrity" subsection covering upload URL and handle TTLs, SHA-256 pinning, size limits, and 507 responses when the in-memory store reaches capacity.
• Notes experimental status tied to MCP spec discussions and stability expectations for the UploadStorage contract.

Changes since #26 opened

• Updated error response documentation for upload capacity limits in MCP server [1259692]
• Added warning about storage backend configuration for deployed standalone MCP servers [1259692]
• Clarified configuration method for fileUploads settings in MCP server [1259692]
• Corrected upload endpoint URL reference in MCP server documentation [1259692]
• Adjusted wording for capacity windows and refusal conditions in MCP upload documentation [1259692]
• Rewrote the Warning block in the MCP server documentation to clarify deployment constraints for standalone servers [e311348]
• Clarified upload endpoint configuration in MCP server documentation by adding alternative path format that includes basePath parameter [7f840bc]
• Updated Claude Code client compatibility requirements regarding upload host reachability [7f840bc]

^{Macroscope summarized 1975ef5.}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
forest	🟢 Ready	View Preview	Aug 17, 2026, 1:12 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[Scra3]

Review pass on this PR found six issues in the shipped-behaviour parts and one scoping problem. All fixed in 2f4df26.

The one a reader would have hit hardest. Step 3 of the flow block read executeAction {Document: "$uploadedFile:<handle>"} — but the fileHandle the tool returns already carries the prefix (fileHandle: ${UPLOADED_FILE_PREFIX}${handle}). Following the block literally yields $uploadedFile:$uploadedFile:<jwt>, and the resulting error tells you to re-request a destination and upload again — sending you round a loop instead of at the string concatenation. Now executeAction {Document: fileHandle}, with one sentence saying the prefix is already there.

Scoping: FOREST_MCP_SERVER_URL is out of this PR. It only exists on agent-nodejs#1832, which is not merged — git grep on main returns nothing, so on the published 1.22.0 setting it has no error, no warning and no effect. Documenting it here would have sent a reader with the localhost problem to a remedy that changes nothing. It lands with that PR.

Also fixed, all verified against the code rather than the README: the upload endpoint path is now named (<your-back-end-url>/mcp/uploads, which is the host to get allowlisted) along with objects being lost on restart; the 64 MiB total limit is documented with the consequence that matters (redeeming does not free, so ~three max-size files per 45-minute window, then 507) — "20 MiB each" alone would have made operators size this wrong; the tool covers File and FileList; FOREST_MCP_FILE_UPLOADS=false wins over a configured storage module and only true/false boot; and the experimental note now keeps the half that matters to an integrator — the UploadStorage contract is expected to survive, so an adapter is safe to write.