SEP-2356: File input support for tools and elicitation#2356
Draft
SEP-2356: File input support for tools and elicitation#2356
Conversation
Proposes Tool.inputFiles and ElicitRequestFormParams.requestedFiles to let servers declaratively mark which arguments expect user-selected files. Clients declaring the fileInputs capability render native file pickers and encode selections as data URIs (with a standardized name= media-type parameter for filenames). Key design points: - inputFiles is a sibling of inputSchema (not an annotation hint) - Per-argument accept[] MIME filters and maxSize limits - Supports single-file and array-of-file arguments - Adds StringArraySchema to PrimitiveSchemaDefinition for elicitation - Capability gates advertising, not acceptance: servers always accept well-formed data URIs regardless of negotiation - Error convention: -32602 with data.reason for size/type violations - Cites OpenAI Apps SDK openai/fileParams as prior art https://claude.ai/code/session_01UE8PfZW3WmKXvoqtamBbtp
- elicitation.form.fileInputs nests under existing client cap - Tool-side stays top-level (no ClientCapabilities.tools exists) - Independent gating: clients can support one surface without the other - Add Open Questions section debating alt placements: new ClientCapabilities.tools namespace vs single unified flag https://claude.ai/code/session_01UE8PfZW3WmKXvoqtamBbtp
One top-level ClientCapabilities.fileInputs flag instead of the split approach. Rationale captured: - Underlying capability (file picker + data URI encoding) is singular - Elicitation is already gated by the elicitation capability itself - Simpler server check - No ClientCapabilities.tools exists to nest under anyway Removes Open Questions section; the placement debate is resolved. https://claude.ai/code/session_01UE8PfZW3WmKXvoqtamBbtp
… to schema
Implements the file upload SEP with declarative file input metadata:
- FileInputDescriptor: { accept?: string[], maxSize?: number } - advisory MIME filter + byte limit
- Tool.inputFiles: maps argument names to FileInputDescriptor for native file pickers
- ElicitRequestFormParams.requestedFiles: symmetric support for elicitation forms
- StringArraySchema: new PrimitiveSchemaDefinition member for multi-file inputs
- ClientCapabilities.fileInputs: capability gate (server MUST NOT send inputFiles without it)
Files are transmitted as RFC 2397 data URIs: data:<mediatype>;name=<filename>;base64,<data>
https://claude.ai/code/session_01JxhHWiXrXgE4JWC27dznRN
ochafik
changed the title
ochafik
changed the base branch from
claude/mcp-file-upload-metadata-cg19I
to
main
Introduces an Overview section in the SEP that walks reviewers through the complete round trip on both surfaces before the formal spec: - Tool: `describe_image` definition with `inputFiles`, paired with the matching `tools/call` request carrying a data-URI argument. - Elicitation: `elicitation/create` request with `requestedFiles`, paired with the matching `ElicitResult` response carrying the data-URI content. All examples use the same real (non-truncated) 1x1 PNG so the wire encoding is concrete and copy-pasteable. The same examples are added as validated JSON files under schema/draft/examples/ and wired into schema.ts via @includecode so they appear in the generated reference docs. https://claude.ai/code/session_0168Rxur9BGcHnAzo3zpZkEH
Rename placeholder SEP file to 2356 (the PR number), fill in the header title and PR link, and regenerate the SEP docs so the new page appears in the community SEP index and navigation. https://claude.ai/code/session_0168Rxur9BGcHnAzo3zpZkEH
localden
reviewed
Mar 11, 2026
Replace 'future SEP' framing in three places with direct guidance: inputFiles covers the inline case, URL-mode elicitation covers files too large to embed. No new transport machinery needed. :house: Remote-Dev: homespace
… handling by surface - Gate StringArraySchema behind fileInputs capability (SEP prose + schema.ts docstring) so existing form-mode clients aren't broken by an unrecognized PrimitiveSchemaDefinition member - Clarify maxSize applies per-file for array-typed arguments - Reword schema-shape constraints to permit extra properties; add SHOULD-ignore rule for malformed inputFiles/requestedFiles entries - Require format:"uri" on StringArraySchema.items for file fields - Add percent-encoding test vector; require name= before ;base64 per RFC 2397 - Define accept matching: type/subtype only, case-insensitive, params stripped - Scope file_uri_malformed to broken data: URIs; non-data URIs are server-defined - Split error handling into tool-call (-32602) vs elicitation-result (re-elicit or fail enclosing op) subsections :house: Remote-Dev: homespace
localden
changed the title
…p-sdks-8Rub5 # Conflicts: # docs/community/seps/index.mdx # docs/docs.json # docs/seps/2356-declarative-file-inputs-for-tools-and-elicitation.mdx
The committed mdx was out of sync with its source .md (admonition line break). Main never tripped this because the workflow only runs when seps/**/*.md changes; adding 2356.md surfaces the drift.
localden
added
draft
localden
changed the title
|
Hey, great feature. Any timeline on this? |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds support for declarative file inputs in tools and elicitation forms, allowing servers to specify which arguments/fields should be rendered as file pickers by clients. Files are transmitted as RFC 2397 data URIs with embedded metadata.
Key Changes
fileInputscapability toClientCapabilitiesto allow clients to declare support for file input handlinginputFilesfield toToolinterface to declare which tool arguments accept file inputs, with optional MIME type and size constraintsrequestedFilesfield toElicitRequestFormParamsfor file inputs in elicitation formsFileInputDescriptorinterface with optionalaccept(MIME type patterns) andmaxSize(byte limit) fields for client-side validation hintsPrimitiveSchemaDefinitionto includeStringArraySchemafor multi-file inputs in elicitation formsImplementation Details
data:<mediatype>;name=<filename>;base64,<data>name=parameter is percent-encoded to preserve original filenamesfileInputscapabilityFileInputDescriptorare advisory; servers must independently validate inputsInvalidParamsErrorand reason"file_too_large"{"type": "string", "format": "uri"}or arrays thereofPrototype PRs
Related work
_meta["openai/fileParams"]is used in MCP Apps for the same purpose, but with an extra step to upload a file & get a fileId