Overview
A stdio MCP server behind the hub runs inside the MCPHub container. When a tool takes a local path, the path is resolved on the hub, not on the client that asked for it. File staging closes that gap for the narrow case where a client needs to hand a file to a tool and get a result back:- the client uploads a copy to the hub,
- the call carries an
mcpfile://reference in a declared input parameter, - the hub rewrites the reference to a real path inside that user’s staging root,
- the tool works on the copy. The reverse direction works too: the client reserves a destination, the tool writes it, and the hub serves the result through a one-time download link.
Enabling file staging
File staging is off by default and has no dashboard UI in this phase. Three things must line up: the global master switch, the server’sstaging declaration, and the per-tool opt-in.
1. Global master switch
An administrator enables staging through the system-config API. The request merges the supplied keys over the stored settings; other settings are unchanged.PUT /api/system-config answers 403 for non-admin callers. Prepend BASE_PATH to the path when the hub is served under a sub-path.
2. Server staging declaration
Declare the adapter on the server. An owner can set the adapter on their own private server; adding or removingshared trust is admin-only:
{"shared":true} in the same request (admin only) and a credentialTemplate with per-user slots.
3. Per-tool opt-in
file-staging route is owner-or-admin. tool is the bare tool name, and omitted inputParams/outputParams keep their stored values, so disabling a tool does not lose its declaration. Both PATCH routes validate the result as a whole: an enabled tool still requires staging.adapter and a stdio server.
There is no dashboard UI for staging in this phase. A whole-server PUT /api/servers/:name ({"config": ...}) is still available for bulk edits, but it replaces the entire tools object when one is supplied, so prefer the PATCH routes for staging changes.
Requirements
- The server is a stdio server. HTTP/SSE and OpenAPI servers cannot use staging.
- The server declares
staging.adapter: "ssh"and each staged tool opts in withfileStaging. - The pinned upstream release
@fangjunjie/ssh-mcp-server@1.11.0is the only adapter profile verified so far. The launcher must benpx(ornode) with that exact spec as the first positional argument, and the connected server must report version1.11.0; staging stays disabled for any other package, version or launcher. - The resolved command line is checked against an SSH option allowlist for every principal. Options that would widen the child’s local root —
--allowed-local-paths,--config-file, and the--ssh/--ssh-config-fileconnection objects that carry the same setting — disable staging for the server. - A shared, group or public server additionally needs
"staging": { "adapter": "ssh", "shared": true }and acredentialTemplatewith per-user slots. Without both, staging is refused for the server. install.baseUrl(orINSTALL_BASE_URL) is configured when download links are needed; a remote client cannot resolve the hub’slocalhost.
Configuration
In file mode, the same configuration looks like this inmcp_settings.json. Through the API, PATCH /api/servers/:name/staging sets the staging object and PATCH /api/servers/:name/file-staging sets one tool’s fileStaging object.
inputParams lists the parameters that accept a reference to a file the hub already holds. outputParams lists the parameters that name a destination the tool writes and the hub later registers. A reference used in the wrong direction, in an undeclared parameter, or twice in one call is rejected before the tool runs. The same parameter cannot appear in both lists.
Only ready references can be inputs; only reserved references can be outputs. When the tool schema is available, a declared parameter must exist in that schema and must be a string. hiddenParams must not overlap inputParams or outputParams. Enabling fileStaging without any parameter is rejected at save time.
Configuration and group templates do not export a server’s staging declaration or per-tool fileStaging; an imported template never enables staging on its own.
Directions
The direction of the reference follows the direction of the data, not the tool name alone.remotePath is a normal remote-side parameter in both SSH calls and is never a staging parameter.
Input: hand an uploaded file to a tool
remotePath stays a normal remote path. It is not rewritten and must not be listed in inputParams.
Output: let a tool write a file the hub will serve
ssh-upload for the server ssh); the tools keys are the bare tool names (upload, download).
Hub tools
The hub injects three virtual tools into a route that exposes at least one staging-enabled server, when the caller resolves to a real user:filenameis display metadata only, never a path. Directory components, NUL, CR, LF, quotes and backslashes are removed, and the name is cut to 255 UTF-8 bytes.content_base64is an inline upload. Omit the field entirely to reserve an output destination; an empty string is rejected.serveris required only when the route exposes more than one staging-enabled server, and it must name one of them.allow_zero_byte(defaultfalse) permits a zero-byte tool output to become ready. It applies only to an output reference.statusanddownloadonly see references owned by the calling user; a foreign or missing reference returns the same not-found error.downloadrequires areadyreference; a reserved, failed or expired reference is refused. The returned link is single-use and short-lived; a retry needs a newmcphub_file_downloadcall.- The tools are listed only on routes with a staging target, and they are not exposed through
$smartrouting.
Reserved namespace
Any tool name beginning withmcphub_file_ is reserved for the hub, and configuration rejects a tools entry under that prefix. If an upstream server still exposes such a tool, the hub definition wins: the upstream tool is not listed, and a call with that name is handled or rejected by the hub and never forwarded to the server.
Downloads
mcphub_file_download mints a URL from install.baseUrl plus the configured basePath:
BASE_PATH this is /staging/download/:token. The route is registered directly on the app, outside the /api dashboard authentication middleware: possession of the token is the capability, so a client does not need a dashboard session to fetch the file. Prepend BASE_PATH when the hub is served under a sub-path.
The route is GET only (HEAD answers 405). The token is random, stored hashed, expires after downloadTtlSeconds, and is consumed atomically on the first request; an unknown, used or expired token returns the same 404. The response is always an attachment with a sanitized filename, Content-Type: application/octet-stream, X-Content-Type-Options: nosniff, Cache-Control: private, no-store and no inline rendering.
If install.baseUrl is missing or still points at the built-in http://localhost:3000 default, mcphub_file_download refuses to mint a link: a remote MCP client cannot resolve it. Set a public URL in Settings or with INSTALL_BASE_URL.
Staged file lifecycle and restart
References move throughreserved, ready, failed and expired:
reservedis a zero-byte destination created bymcphub_file_uploadwithout content. It is not a valid input.readyis registered content with a size and SHA-256. It is read-only and can be used as an input or downloaded.failedis terminal: the call failed, threw, timed out, or produced a missing, oversized or (unlessallow_zero_byte) empty file.expiredis past the reference TTL.
- A reserved reference that held a lease when the hub stopped becomes
failedat startup, its lease and quota reservation are cleared, and its UUID is never reused. A reference leased by a crashed call is never re-leased, overwritten or served, even if the orphaned child wrote bytes into it. - A reserved reference that was never leased survives the restart and remains available as an output destination until its TTL expires.
- Ready content and its TTL survive a restart. Read pins do not: they are cleared at startup because no reader outlives the process.
MCPHUB_REPLICA_MODE=true) disables staging, and a second hub process must not share the same staging directory.
Settings
Settings live undersystemConfig.fileStaging and are written through PUT /api/system-config (admin only); file mode can also set the same object in mcp_settings.json. Partial updates merge over the stored values. Defaults:
Staged content lives under
data/uploads/staging (override with MCPHUB_STAGING_ROOT); the file-mode ledger and the process lock live under data/staging-state (MCPHUB_STAGING_STATE_DIR). Both belong on a persistent volume. The ledger is authoritative; meta.json inside a reference directory is only a cache.
With DB_SYNCHRONIZE=false, apply docs/migrations/0006-file-staging.sql before enabling staging in database mode. Database mode keeps refs and tokens in file_staging_refs and file_staging_tokens; the content still lives on the local staging root.
Authentication
A staging call must resolve to a real user account. The following callers are refused before a reference is created or rewritten:- system bearer keys, even when the key names an owner;
- anonymous callers and the
skipAuthguestuser; - users flagged
credentialEligible: false, and users that no longer exist; - replica-mode requests.
Security boundary
Staging makes the hub copy a file; it does not grant the client filesystem access to the hub. The boundary is enforced by hub-side ownership checks and by the trusted SSH adapter’s own per-principal root.- The tool child runs as the same OS user in the same container as the hub. There is no OS-level isolation between principals.
- The per-principal working directory and staging root are a correctness boundary, not a security boundary. They keep a reference and its relative paths bound to the right user and stop the trusted adapter from resolving paths outside that root. They do not stop a tool that can read the filesystem directly.
- A shared or public server is therefore not an isolation boundary between its users. Neither is the hub container as a whole: another stdio server with shell or filesystem access can read the staging tree and the ledger. Restrict who can use such servers, or accept the risk.
- A reference is a capability bound to one user and one server, and a download link is a single-use capability. Treat both as secrets.
- Staging is not transparent: only declared parameters are rewritten. A raw path the client sends in another parameter still resolves inside the container, and the hub does not scan or rewrite tool responses.
Not included
Staging does not yet provide browser upload pages, S3/MinIO or multi-node storage, response-path detection or automaticdownloadUrl injection, $smart exposure of the virtual tools, an MCP Apps file API, a revoke path for issued references, non-SSH adapters, or OS-level isolation. A ref is kept out of activity records on the direct and nested call paths, including error entries; a payload that reaches an upstream tool through a channel the hub does not inspect (for example a resource read) is outside that guarantee. There is also no dashboard editor for staging in this phase; configuration goes through the PATCH routes described above.