mcp-file-bridge

A ChatGPT/Codex App file bridge designed to move artifacts without putting file bytes or Base64 in model context.

The repository contains:

• an MCP/App server (/mcp)

• a host-native file input tool (ingest_file)

• a direct HTTP streaming fallback for ordinary networked clients

• a reusable Agent Skill under skills/file-transfer/

• Docker deployment files

Why this exists

A remote MCP server cannot open /mnt/data/foo.zip from a ChatGPT/Codex sandbox. Passing Base64 through tools/call.arguments is also unsuitable for large files because the bytes would travel through model/tool JSON.

Compatible OpenAI hosts support an Apps-style file parameter bridge. ingest_file advertises:

{
  "_meta": {
    "openai/fileParams": ["file"]
  }
}

The model-facing call can remain tiny:

ingest_file(file=/mnt/data/build.apk, path="builds/build.apk")

At execution time a compatible host handles the local file out of band and the remote app receives a temporary provided-file object such as:

{
  "download_url": "https://...temporary-signed-url...",
  "file_id": "file_...",
  "mime_type": "application/octet-stream",
  "file_name": "build.apk"
}

The bridge server then streams that URL directly to persistent storage while calculating SHA-256. The binary payload is never generated by the model and never Base64-encoded into ordinary MCP arguments.

Related MCP server: ssh-mcp

Architecture

ChatGPT / Codex host
        |
        | local artifact / attachment
        | (bytes stay outside model context)
        v
host file-parameter bridge
        |
        | temporary provided-file object
        | {download_url,file_id,...}
        v
mcp-file-bridge App
        |
        | server-side HTTPS stream
        v
/data/files/<destination>

Important size note

OpenAI Codex currently has an explicit 512 MiB limit in its openai/fileParams local-file upload bridge. That limit is host-side, not this server's storage limit.

MAX_FILE_BYTES defaults to 10 GiB so the server itself can accept larger transfers from future/other host file-transfer mechanisms. A 1 GiB file therefore requires a host path whose file-transfer layer supports that size; do not assume the legacy OpenAI file-parameter bridge will accept it.

MCP's newer file-transfer work (x-mcp-file / File Objects and Transfer) is intended to keep large file bytes out of JSON-RPC. This project keeps the storage/data plane compatible with that direction, but does not claim a host supports a particular large-file size until tested on that host.

MCP tools

ingest_file — preferred for ChatGPT/Codex

Inputs:

• file: host-native file parameter

• path (optional): destination under /data/files

• sha256 (optional): expected SHA-256

The tool descriptor declares _meta["openai/fileParams"] = ["file"].

The server validates the temporary download URL, streams it without buffering the full file, applies MAX_FILE_BYTES, prevents path traversal, and returns the stored size and SHA-256.

create_upload — fallback for networked clients

Creates a short-lived PUT /upload/<id> session. This is useful for MCP clients that can access the public network themselves.

Do not use this path from a sandbox with no public network egress.

Other tools

• get_upload

• cancel_upload

• list_files

• stat_file

• delete_file

Plugin shape

As of the current ChatGPT plugin model, a plugin can package workflow Skills together with an App. This repository is structured for that split:

skills/file-transfer/SKILL.md   workflow guidance
src/server.mjs                  MCP-backed App

The Plugin Directory / workspace publishing layer is managed by ChatGPT, not by a magic repository manifest. Deploy the App first, connect/test it as a custom App where your plan/workspace supports that, then package the App together with the included Skill when creating/submitting the plugin.

The skill explicitly instructs compatible agents to use ingest_file and never Base64 a binary artifact into model context.

Deploy

cp .env.example .env
# Set a strong MCP_API_TOKEN and your public HTTPS base URL.
docker compose up -d --build

Expected endpoints:

GET  /healthz
POST /mcp
PUT  /upload/<id>      # fallback data plane

For ChatGPT, the MCP endpoint must be reachable through HTTPS (or through a supported secure tunnel during development).

Configuration

MCP_API_TOKEN=replace-with-a-long-random-secret
PUBLIC_BASE_URL=https://mcp-files.example.com
MAX_FILE_BYTES=10737418240
PROVIDED_FILE_HOST_SUFFIXES=openai.com,oaiusercontent.com,blob.core.windows.net

PROVIDED_FILE_HOST_SUFFIXES restricts hosts from which ingest_file is willing to retrieve temporary provided files. Redirect targets are revalidated.

Security

• optional Bearer auth for /mcp

• destination path traversal prevention

• streaming transfer (no whole-file RAM buffering)

• SHA-256 calculation on every completed file

• optional expected SHA-256 validation

• maximum file size enforcement while streaming

• HTTPS-only host-provided file downloads

• host suffix allowlist and redirect revalidation

• destinations are never silently overwritten

Test

npm test

Current storage tests cover path traversal, direct streaming with SHA-256, bad upload tokens, and host-provided streaming.

Compatibility strategy

1. Preferred: host-native App file parameter (openai/fileParams)

2. Future/when supported by host: standard MCP out-of-band file transfer (x-mcp-file / File Objects and Transfer)

3. Fallback: direct HTTP PUT for clients with their own network egress

4. Never: Base64/chunking file bytes through model-generated MCP arguments

License

MIT