SEP: Binary Mode Elicitation for File Uploads

Status: Proposal
Author: @localden
Created: August 5, 2025
Type: Standards Track

Abstract

This SEP proposes extending the Model Context Protocol (MCP) elicitation feature to support a new binary mode for file uploads. The current elicitation mechanism supports form mode for structured text data and URL mode for out-of-band interactions, but lacks the ability to request file uploads directly. This extension would add a third mode enabling servers to request binary files (images, documents, archives, etc.) from users while maintaining the same security principles and user interaction model as the existing elicitation specification.

Motivation

The current MCP elicitation specification supports two modes:

• Form mode: For structured text data collection with JSON schema validation
• URL mode (in review SEP-1036): For secure out-of-band interactions (OAuth, payments, etc.)

However, many real-world use cases require servers to process binary files directly within the MCP workflow:

1. Image Analysis: Computer vision servers need to analyze user-uploaded images
2. Document Processing: PDF analyzers, OCR services, and document parsers need access to binary documents
3. Code Analysis: Static analysis tools may need to process compiled binaries or archives
4. Data Import: Servers may need to process CSV, Excel, or other binary data formats
5. Model Training: ML servers may need training data in various binary formats

Currently, these scenarios require workarounds such as:

• Complex base64 encoding within text fields (inefficient, size-limited)
• External file hosting with URL sharing (security concerns, complexity)
• Pre-uploading files to shared locations (poor user experience)

The existing elicitation model provides the perfect foundation for binary file requests because it already:

• Maintains client control over user interactions
• Provides clear security boundaries
• Supports structured validation
• Offers a consistent three-action response model (accept/decline/cancel)
• Uses a flexible mode-based architecture that can accommodate new interaction types

Specification

1. Capability Declaration

Clients that support binary elicitation MUST declare the binary mode within the existing elicitation capability during initialization (similar to what was proposed in SEP-1036 for out-of-band elicitations):

{ "capabilities": { "elicitation": { "form": {}, "url": {}, "binary": { "maxFileSize": 104857600, "supportedMimeTypes": ["*/*"] } } } }

The binary mode capability includes:

• maxFileSize (optional): Maximum file size in bytes the client will accept
• supportedMimeTypes (optional): Array of supported MIME types (default: ["*/*"] for all types)

2. Binary Mode Elicitation Requests

Binary file requests use mode: "binary" within the existing elicitation/create method. The server provides upload endpoints for each file field:

{ "jsonrpc": "2.0", "id": 1, "method": "elicitation/create", "params": { "mode": "binary", "message": "Please upload an image for analysis", "requestedSchema": { "type": "object", "properties": { "imageFile": { "type": "file", "title": "Image File", "description": "Select an image file to analyze", "accept": ["image/*"], "maxSize": 5242880, "required": true }, "description": { "type": "string", "title": "Description", "description": "Optional description of the image", "maxLength": 500 } }, "required": ["imageFile"] }, "uploadEndpoints": { "imageFile": { "url": "https://server.example.com/mcp/upload/session-abc123", "method": "POST", "uploadId": "550e8400-e29b-41d4-a716-446655440000" } } } }

File Schema Properties

The file type schema supports the following properties:

• type: MUST be "file"
• title: Display name for the file input
• description: Help text for the user
• accept: Array of MIME types or file extensions (e.g., ["image/*", ".pdf", "application/json"])
• maxSize: Maximum file size in bytes for this specific field
• multiple: Boolean indicating if multiple files are allowed (default: false)
• required: Boolean indicating if the file is required (inherited from parent object)

Upload Endpoints

The uploadEndpoints object maps file field names to their upload configuration:

• url: Server endpoint URL for uploading the file content
• method: HTTP method to use for upload (typically "POST" or "PUT")
• uploadId: Unique identifier for this upload (GUID format recommended)

For multiple file fields, each field has its own upload endpoint:

{ "uploadEndpoints": { "imageFile": { "url": "https://server.example.com/mcp/upload/session-abc123", "method": "POST", "uploadId": "550e8400-e29b-41d4-a716-446655440000" }, "documentFile": { "url": "https://server.example.com/mcp/upload/session-def456", "method": "POST", "uploadId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8" } } }

3. Response Format

Binary file responses include file metadata that confirms which files the user selected and uploaded:

Accept Response

{ "jsonrpc": "2.0", "id": 1, "result": { "action": "accept", "content": { "imageFile": { "name": "sunset.jpg", "size": 2097152, "mimeType": "image/jpeg", "uploadId": "550e8400-e29b-41d4-a716-446655440000" }, "description": "A beautiful sunset over the ocean" } } }

File Object Structure

Each file in the response contains:

• name: Original filename
• size: File size in bytes
• mimeType: MIME type of the file
• uploadId: The upload ID provided by the server in the upload endpoint configuration

Multiple Files

When multiple: true is specified, the file field contains an array of file objects:

{ "content": { "documents": [ { "name": "document1.pdf", "size": 1048576, "mimeType": "application/pdf", "uploadId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8" }, { "name": "document2.pdf", "size": 2097152, "mimeType": "application/pdf", "uploadId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8" } ] } }

Decline/Cancel Responses

Decline and cancel responses remain unchanged from the base elicitation specification:

{ "jsonrpc": "2.0", "id": 1, "result": { "action": "decline" } }

5. File Upload Protocol

The file upload process follows this sequence:

1. Server sends elicitation/create request with uploadEndpoints containing upload URLs for each file field
2. Client presents file selection interface to user
3. User selects files and confirms
4. Client uploads files directly to the server's provided endpoints
5. Client sends elicitation response with file metadata confirming successful uploads

File Upload Request

Files are uploaded to the endpoints provided by the server using the specified HTTP method:

POST /mcp/upload/session-abc123 HTTP/1.1 Host: server.example.com Authorization: Bearer {mcp-client-auth-token} Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW ------WebKitFormBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; name="file"; filename="sunset.jpg" Content-Type: image/jpeg [binary file content] ------WebKitFormBoundary7MA4YWxkTrZu0gW--

File Upload Response

Servers MUST respond with an HTTP success status code (2xx) to indicate successful upload. The response format is implementation-specific, but servers MAY include additional information in the response. Clients are not obligated to parse the response or pass it back to the server beyond knowing the response HTTP code.

HTTP/1.1 200 OK Content-Type: application/json { "uploadId": "550e8400-e29b-41d4-a716-446655440000", "status": "completed" }

Upload Requirements

Clients MUST:

1. Use the exact url provided in the elicitation request's uploadEndpoints
2. Include the MCP client's authorization token in the Authorization header
3. Use multipart/form-data encoding for file uploads
4. Use "file" as the form field name for the uploaded file
5. Include the original filename in the Content-Disposition header
6. Set the appropriate Content-Type for the file within the multipart section

For multiple files, each file should be included as a separate form field:

POST /mcp/upload/session-def456 HTTP/1.1 Host: server.example.com Authorization: Bearer {mcp-client-auth-token} Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW ------WebKitFormBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; name="file"; filename="document1.pdf" Content-Type: application/pdf [binary file content for document1.pdf] ------WebKitFormBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; name="file"; filename="document2.pdf" Content-Type: application/pdf [binary file content for document2.pdf] ------WebKitFormBoundary7MA4YWxkTrZu0gW--

Upload Progress Reporting

Servers MAY request progress updates for file uploads by including a progressToken in the elicitation request metadata:

{ "jsonrpc": "2.0", "id": 1, "method": "elicitation/create", "params": { "_meta": { "progressToken": "upload-progress-123" }, "mode": "binary", "message": "Please upload an image for analysis", "requestedSchema": { // ... schema definition } } }

During file upload, clients MAY send progress notifications to the server:

{ "jsonrpc": "2.0", "method": "notifications/progress", "params": { "progressToken": "upload-progress-123", "progress": 1048576, "total": 2097152, "message": "Uploading sunset.jpg..." } }

Progress notifications:

• progress: Bytes uploaded so far
• total: Total file size in bytes (from the elicitation response)
• message: Optional human-readable status message

Servers MAY:

• Request progress notifications by including a progressToken in the elicitation request
• Use progress information for monitoring, logging, or user feedback purposes

Clients MAY:

• Send progress notifications if a progressToken was provided in the elicitation request
• Report upload progress using the notifications/progress method

6. Size and Type Validation

Clients MUST validate file uploads against the specified constraints:

1. Size validation: Files exceeding maxSize (field-level) or maxFileSize (capability-level) MUST be rejected
2. Type validation: Files not matching the accept criteria SHOULD be filtered from file selection
3. Multiple files: When multiple: false (default), only one file MUST be accepted per field

Backwards Compatibility with Existing Implementations

For maximum compatibility:

• Clients that declare "elicitation": {} without mode specification should be treated as supporting form mode only
• Servers should gracefully handle clients that don't support binary mode by either offering alternative workflows or clear error messages

Security Implications

Trust and Safety

1. User control: Users maintain complete control over file uploads through the client interface
2. Validation: Size and type restrictions constrained on the client
3. No direct access: Servers cannot directly access user file systems - all uploads are user-initiated

Security Considerations

1. File size limits: Prevent DoS attacks through large file uploads
2. Type restrictions: MIME type validation reduces risk of unwanted file uploads
3. Content scanning: Servers SHOULD implement malware scanning on uploaded files
4. User consent: Clear UI indicating which server is requesting files and why
5. Rate limiting: Servers SHOULD implement rate limiting for upload endpoints
6. Audit trail: File upload requests and responses SHOULD be logged for security auditing
7. Upload authentication: Upload endpoints must validate MCP client authorization tokens
8. Upload session security: Upload URLs should include upload-specific identifiers to prevent unauthorized uploads
9. File storage: Uploaded files should be stored securely with appropriate access controls

Privacy Implications

1. File content: Files are uploaded directly to servers - users must be clearly informed
2. Metadata exposure: File names and sizes are shared and may contain sensitive information
3. Upload logs: Server logs of file uploads may reveal sensitive patterns and should be handled carefully
4. Transport security: File uploads must use secure transport (HTTPS/TLS)
5. Authorization reuse: The same MCP authorization token is used for uploads, maintaining consistent security model

Relevant Discussions

• How to upload file to remote MCP Server #1220
• Passing attachments (resources) to MCP servers? #155