Add FileInput/FileOutput well-known types for file transfer between MCP tools

[birdayz]

What

Add mcp.v1.FileInput and mcp.v1.FileOutput as well-known protobuf types with oneof source/destination for deployment-aware file transfer in MCP tools.

Why

MCP tools that move files need different transports depending on deployment topology. Inline bytes work for small files in hosted mode. Filesystem paths avoid context-window bloat in sandbox deployments. And S3 presigned URLs solve the MCP-to-MCP file transfer problem in production without a shared filesystem -- MCP A uploads to S3, emits a presigned GET URL, MCP B downloads directly, and the LLM just passes a URL string instead of carrying megabytes through its context window.

Without a shared abstraction every file-moving MCP reinvents this, and MCP-to-MCP file passing doesn't work at all in pure MCP (no sandbox) because the protocol has no mechanism for direct server-to-server transfer.

Implementation details

Proto shape

message S3Reference {
  string presigned_url = 1;
}

message FileInput {
  oneof source {
    bytes content = 1;     // inline (hosted, small files)
    string path = 2;       // filesystem (sandbox)
    S3Reference s3 = 3;    // presigned URL (cloud-native)
  }
  string filename = 4;
  string mime_type = 5;
}

message FileOutput {
  oneof destination {
    bytes content = 1;
    string path = 2;
    S3Reference s3 = 3;
  }
  string filename = 4;
  string mime_type = 5;
  int64 size_bytes = 6;
}

The oneof makes the transport explicit at the proto level. Common metadata (filename, mime_type, size_bytes) sits outside the oneof -- always present regardless of transport.

Generator (pkg/gen/schema.go)

Recognizes mcp.v1.FileInput, mcp.v1.FileOutput, and mcp.v1.S3Reference by FQN in messageFieldSchema() -- same mechanism as google.protobuf.Timestamp. Emits JSON Schemas with an x-mcp-file-mode extension marker that the runtime uses to locate file-typed properties.

Runtime (pkg/runtime/file_mode.go)

Four modes via WithFileMode(mode) registration option:

• FileModeInline -- exposes only the content oneof variant (hosted)
• FileModePath -- exposes only path (sandbox)
• FileModeS3 -- exposes only s3 (cloud-native)
• FileModeAll -- all variants visible, agent picks (hybrid)

Schema rewriting strips non-matching oneof variants at registration time. The x-mcp-file-mode marker is removed from the final schema.

Framework contract

MCP handlers always produce/consume raw bytes. The framework layer (in the consumer repo) intercepts and rewrites to the configured transport:

Handler returns FileOutput{content: <bytes>}
         |
    Framework intercepts
         |
   ┌─────┼─────┐
   v     v     v
 inline path   S3
        write  upload, mint
        to     presigned
        disk   GET URL

Handlers never touch S3 or the filesystem directly.

S3 presigned URL flow

S3Reference carries a presigned URL. The framework (not the handler) mints it:

• Output: framework uploads bytes to a scratch bucket, returns a presigned GET URL
• Input: framework downloads from the presigned URL, passes bytes to the handler

Presigned URLs are time-limited and scoped to a single object -- no IAM cross-wiring between MCPs. This makes MCP-to-MCP file transfer work without the LLM carrying bytes through its context window.

S3 wiring is not yet implemented in any consumer -- this PR defines the proto shape and schema machinery so the framework can wire it when ready.

References

First consumer: SharePoint managed MCP in cloudv2 (https://github.com/redpanda-data/cloudv2/pull/26291).

[malinskibeniamin]

do we need to validate the path so that nobody references wrong location like local fs?