
The Model Context Protocol has no standard way to move a file larger than a tool call's JSON payload, and as of November 10, 2026 the MCP maintainers published a draft extension called io.modelcontextprotocol/files to fix that. The pattern keeps file bytes out of JSON-RPC entirely: a tool call carries only file metadata, and the actual upload or download happens over a separate HTTPS request to a URL the server hands back. If you are building an MCP server on top of Docusign, Procore, or NetSuite document data, this draft is the reference pattern to build against before you invent your own.
Every MCP server builder who has shipped a tool that touches a PDF, a signed agreement, or a CRM export has hit the same wall: MCP tool calls travel as JSON-RPC messages, and JSON has no efficient way to carry binary data except base64, which bloats a 2MB PDF into roughly 2.7MB of text sitting in the model's context window. Server builders worked around this with ad hoc conventions: prose instructions asking users to paste base64 strings, bespoke presigned-URL schemes, or local file paths that only work for desktop clients. The File Uploads Working Group's charter describes exactly this gap: MCP servers that need a file from the user have had to improvise, which produces inconsistent UX and pushes encoding details onto the people least equipped to deal with them.
The November 10 post, written by MCP maintainers Den Delimarsky and Wil St. Charles, is the first attempt at a shared answer for both directions: a client sending a file to a tool, and a tool handing a file back to a client.
The core design decision is that file contents never enter the JSON-RPC message. Here's the upload flow as described in the draft and in independent write-ups of the same draft:
x-mcp-file, so compatible clients know that argument expects a file rather than an ordinary string.clientCapabilities on requests that might need it, including tools/list, specifying whether it can upload out of band, accept download targets, or both.upload_required result containing an upload target: a URL, headers, an expiry, a credentials mode, and a requestState value.As one independent technical breakdown of the draft put it, the extension "wants to standardize" the pattern of base64 blobs and bespoke presigned-URL conventions that server builders had been hand-rolling.
Downloads work in reverse. A tool that produces a file, say a generated PDF or a signed agreement export, returns a download target in the tool result's _meta field rather than inlining the file. The credentials field on that target controls whether the client's MCP token gets attached to the download request, which matters if the file lives behind the same authorization boundary as the MCP server or at a separate storage service entirely. The working group's charter notes that file downloads are explicitly secondary to upload work for now, and that resumable, chunked transfer and upload-from-elicitation-form flows are future work, not part of this draft.
One detail worth flagging for anyone validating files server-side: a matching SHA-256 digest only confirms the bytes you received match the hash the server advertised. It does not confirm the file is safe. A compromised or malicious server can hand you a harmful file with a perfectly correct digest, so digest verification is not a substitute for scanning or sandboxing.
{
"name": "upload_signed_agreement",
"inputSchema": {
"type": "object",
"properties": {
"agreement": {
"type": "object",
"x-mcp-file": {
"accept": ["application/pdf"],
"maxSizeBytes": 26214400
}
},
"envelopeId": { "type": "string" }
},
"required": ["agreement", "envelopeId"]
}
}A client that does not support the extension simply ignores x-mcp-file and treats the argument as an ordinary object, which is why the draft is additive rather than breaking.
The new extension addresses the transport problem, but it does not replace the existing choice between returning a file as a tool result or exposing it as an MCP resource, and that choice still matters for integration builders today, draft or no draft.
MCP already defines resources as a distinct primitive from tools: resources are read-only, application-controlled context that a host can list and fetch independently, while tools are model-controlled actions with side effects. A resources/read call returns a contents array where each item is either UTF-8 text or a base64-encoded blob, so a PDF or image resource is legal today without any new extension. The practical guidance from the MCP ecosystem has been consistent well before this draft: prefer resource links or URIs over embedding large content directly in a tool result, because Claude Desktop's resource handling has size limits and content returned from MCP servers is generally expected to stay under roughly 1MB.
The rule of thumb for 2027 integration work: a tool returning a 200-byte invoice summary should inline it as JSON. A tool handling a signed PDF, a construction drawing set, or a multi-megabyte CRM export should return a resource_link or, once clients support it, an upload_required/download target under the new files extension, and let the bytes travel over plain HTTPS outside the model's context entirely.
If you are exposing documents from Docusign, Procore, or NetSuite through an MCP server, this draft is the pattern to design against now, even while it is experimental. Three implications stand out:
Version your capability declarations. The extension ties itself to protocol revision 2026-07-28 and later, and declares itself through clientCapabilities. If your MCP server supports file uploads, say what file types and sizes it accepts in the tool's x-mcp-file schema rather than discovering limits through failed calls. Docusign Connect, for comparison, already enforces payload limits on its own webhook deliveries and signs each one with HMAC-SHA256 over the raw request body, a model worth mirroring: declare limits up front, verify integrity on receipt, and never trust an unsigned delivery.
Don't inline signed agreements as base64 in a tool response. A completed Docusign envelope, a Procore drawing set, or a NetSuite file cabinet export routinely runs into the megabytes. Returning that as a base64 tool result both bloats the model's context and risks hitting the practical size ceilings several MCP clients already enforce. Treat it as a resource link or an out-of-band download target instead, exactly as our Claude Docusign MCP integration guide recommends for connecting agents to Docusign in production.
Metadata-first beats upload-first. The working group chose to require file metadata before any bytes move specifically so a server can validate destination folder, permissions, and quota before committing to a transfer. For document stores like Procore's project folders or NetSuite's file cabinet, where access depends on project role or subsidiary, that ordering avoids transferring a multi-megabyte file only to reject the tool call afterward on a permissions check you could have run first.
File upload and download design is a different problem from webhook delivery, but they share a root cause: both exist because production integrations have to move binary payloads and event data reliably between systems that were not built to talk to each other directly. Docusign Connect signs its webhook deliveries with HMAC and retries aggressively against dead endpoints, which is the reason a dedicated relay layer like Baton exists for teams that need those events to reliably reach Docusign Workflow Builder (formerly Maestro) runs rather than disappearing into a flaky endpoint. If your MCP server's job is to hand a signed agreement to an agent after an envelope completes, you still need that webhook leg working first; our guide on triggering workflows from any platform covers that half of the pipeline.
This is not a theoretical problem. Zoho CRM now publishes an official, first-party MCP server that gives external AI agents authenticated, real-time access to CRM data and actions, alongside Zoho's broader Zia LLM and agent tooling. A CRM MCP server is exactly the kind of integration that will need to hand a quote PDF, a signed contract, or a bulk export to an agent, and exactly the kind of integration where base64-stuffed tool calls fall apart first. Every ISV shipping an MCP server on top of a document-heavy platform, not just Zoho, should treat the November 10 draft as the pattern to build the file-handling layer against, rather than inventing a one-off convention that has to be rewritten once the extension stabilizes.
Is the MCP file upload and download extension finalized? No. As of November 2026 it is an experimental draft from the File Uploads Working Group, anchored on a proposal called SEP-2356, with no reference implementation yet and the shape expected to change.
Can MCP tools already return files today, without this extension?
Yes. MCP resources already support returning binary content as a base64-encoded blob through resources/read, and tool results can include resource_link content today. The new extension adds an out-of-band transport specifically for files too large or sensitive to inline, which resources and tool results were never designed to carry efficiently.
Why not just send the file as base64 inside a tool call? Base64 inflates binary size by roughly a third, consumes model context tokens for data the model never needs to read, and still has to go somewhere if the file is tens of megabytes. The draft's authors chose to keep file bytes out of JSON-RPC specifically to avoid that cost, moving them over a direct HTTPS PUT or GET instead.
Does a SHA-256 digest match mean the downloaded file is safe? No. A matching digest confirms the bytes you received match what the server advertised, not that the file itself is safe. A malicious or compromised server can supply a harmful file with a correct digest, so digest checks belong alongside scanning, not instead of it.
What should Docusign, Procore, or NetSuite integrators do about this today? Build your MCP server's file-handling layer around resource links and out-of-band transfer now, not base64-in-tool-calls, so you are already aligned with where the protocol is heading. Validate file metadata (type, size, permissions) before accepting a transfer, and keep your webhook and HMAC verification layer, whichever platform it's for, separate from and upstream of your file transport logic.
The file upload and download extension is still a draft, but the direction is clear: binary payloads move out of band, and MCP servers that get ahead of this now will not have to rewrite their file-handling logic when the extension stabilizes. If you are building an MCP server or agent integration on top of Docusign, Procore, Zoho CRM, or NetSuite document data and want a second set of eyes on the architecture, talk to the fluidlabs team about how we're wiring agentic AI into production document workflows.
Thirty minutes with an engineer. Within 48 hours you get a scoped plan and a fixed price in writing, or a straight “you don't need us.” No charge, nothing to sign.
Talk to an engineer →or email us at hello@fluidlabs.com