MCP File Staging Service

Lightweight HTTP file staging service for MCP servers deployed on remote machines.

The Problem

MCP (Model Context Protocol) is JSON-RPC — it has no binary data channel. When an MCP server runs on a different machine than the client (e.g., server on a VM, client on a workstation or phone), tools that accept a sourcePath parameter can only read files from the server's local filesystem. The client's files don't exist there.

The common workarounds — base64 encoding (33% bloat, size limits) and SCP (requires SSH access) — don't work well from constrained clients like phones or chat interfaces.

The Solution

This service runs alongside your MCP servers and provides a standard HTTP multipart upload endpoint. Any client that can make an HTTP POST (curl, browser, phone app, automation) can stage a file on the server, then reference the server-local path in MCP tool calls.

Phone/Browser/CLI                    Server (VM)
       |                                |
       |  POST /upload (multipart)      |
       |------------------------------->|  mcp-file-staging-service
       |  {"stagingPath": "/staging/.."}|  stores file locally
       |<-------------------------------|
       |                                |
       |  MCP: upload_file              |
       |  sourcePath: "/staging/.."     |
       |------------------------------->|  google-workspace-mcp
       |  (uploads to Google Drive)     |  reads local file
       |<-------------------------------|

API

POST /upload

Upload a file via multipart form data.

curl -F "file=@report.pdf" http://server:3201/upload

Response:

{
  "stagingPath": "/staging/a1b2c3d4-e5f6-7890-abcd-ef1234567890.pdf",
  "originalName": "report.pdf",
  "bytes": 47700,
  "expiresInHours": 24
}

GET /files

List all staged files with metadata.

DELETE /files/:filename

Delete a specific staged file.

GET /health

Health check / service info.

Deployment

Docker (recommended)

docker compose up -d

Standalone

npm install
node index.js

Environment Variables

Variable	Default	Description
STAGING_PORT	3201	HTTP listen port
STAGING_HOST	0.0.0.0	Bind address
STAGING_DIR	/tmp/gws-mcp-staging	Where staged files are stored
STAGING_MAX_FILE_SIZE	104857600 (100 MB)	Max upload size in bytes
STAGING_MAX_AGE_HOURS	24	Auto-delete files older than this

Integration with MCP Servers

Google Workspace MCP

The google-workspace-mcp upload_file tool accepts a sourcePath parameter and a cleanupSource flag. After staging a file here, call:

{
  "name": "report.pdf",
  "sourcePath": "/staging/a1b2c3d4.pdf",
  "folderId": "...",
  "cleanupSource": true
}

cleanupSource: true tells the MCP server to delete the staged file after successful upload to Drive.

Any MCP Server

Any MCP tool that reads files from disk can use staged paths. The staging service is MCP-agnostic — it's just HTTP file storage with auto-cleanup.

Architecture Notes

• Files are stored with UUID names (preserving original extension) to avoid collisions
• Auto-cleanup runs every 10 minutes, removing files older than STAGING_MAX_AGE_HOURS
• Path traversal is prevented on the delete endpoint
• CORS is enabled for browser-based uploads
• Single file per request, max 1 concurrent file per upload
• No authentication by default — intended for trusted LAN use. Add a reverse proxy with auth for public exposure.

Security

This service is designed for trusted LAN deployment. It has:

• No authentication (add via reverse proxy if needed)
• Path traversal prevention on delete
• File size limits
• Auto-cleanup of old files

Do not expose to the public internet without adding authentication.