SEP-2631: File Objects and Transfer

[caseychow-oai]

Summary

This PR introduces SEP-2631 for first-class MCP file transfer. It builds on SEP-2356's x-mcp-file input declaration model, keeps file-valued inputs as URI strings, and adds out-of-band upload/download negotiation plus generated file outputs.

Motivation

MCP has partial primitives for file-like workflows, but no single interoperable story for "the user gives a file to a tool" or "a tool returns a file to the user." Implementations currently rely on ad hoc argument conventions, hosted-storage handles, inline base64, or harness-specific rewriting. That makes file upload behavior drift across clients, gateways, and servers, and it makes it hard for server authors to declare portable file-taking tools.

What This SEP Proposes

This SEP adds a focused file transfer contract:

• SEP-2356 input declarations — file-valued tool and elicitation fields are declared with x-mcp-file on URI string schema properties.
• URI-string file inputs — clients can satisfy file inputs with SEP-2356 data: URIs or with file URIs prepared through files/prepareUpload.
• Allowed transfer modes — x-mcp-file.transferModes lets servers allow inline transfer, require upload transfer, or leave clients free to choose.
• FileValue outputs — generated or returned files use a URI plus optional display metadata such as name, MIME type, and size.
• Upload/download control plane — files/prepareUpload and files/getDownload negotiate HTTPS transfer descriptors while keeping bytes out of JSON-RPC payloads.
• URI namespace guidance — file URIs and resource URIs have distinct resolution contracts; file URIs resolve through file transfer methods, not resources/read.
• Tool, elicitation, content, and resource integration — file URI values can appear in tool arguments and elicitation responses, while FileValue can appear in structured tool output, file content blocks, and optional file-backed resource contents.

Relationship to Other SEPs

This SEP is designed to complement nearby work:

• SEP-2356: Declarative file inputs — this SEP adopts x-mcp-file declarations and extends the URI-string value contract with negotiated file URI transfer.
• SEP-2575: Make MCP Stateless — this SEP keeps file identity in the JSON-RPC control plane and leaves lifecycle/storage policy server-defined so it can fit stateless-by-default directions.
• SEP-2322: Multi Round-Trip Requests — file upload and download negotiation is intentionally expressed as explicit control-plane round trips that can compose with broader multi-round-trip request work.

Validation

• npm run generate
• env npm_config_cache=/private/tmp/mcp-npm-cache mise x node@22.20.0 -- npm run check

AI Assistance Disclosure

This SEP was drafted with Codex assistance under human direction and review.