Read and write files from a tool
Some tools need the file, not a description of it — parse the spreadsheet the user uploaded, or hand back a generated report. DioscHub exposes two HTTP endpoints your MCP server calls directly for this: one to fetch a file, one to write one back. The bytes travel between your server and DioscHub over HTTP; they never pass through the model’s context.
Authenticate with a scoped admin API key
Section titled “Authenticate with a scoped admin API key”Both endpoints are authenticated with a DioscHub admin API key, presented in the x-api-key header.
Mint a key for your server scoped to just the two file permissions:
mcp-files:read— to fetch files.mcp-files:write— to write files.
A key minted with only these scopes carries no other admin authority. Keep it server-side, never expose it to the model, and give each MCP server its own key.
Present the file access token
Section titled “Present the file access token”On every tool call that belongs to a chat session, DioscHub puts an opaque file access token in the
call’s _meta, under dioschub/fileAccess. Send it back in the X-File-Access-Token header, next to
your API key:
// params._meta of the tools/call your server receives{ "dioschub/fileAccess": "<opaque token>" }The token is valid for 15 minutes and is issued for one tool call: it is bound to the session and to your MCP server’s instance, with read
and write access. DioscHub takes the session from the token, so you no
longer need to send X-Session-Id; if you do send it, it must match the token’s session.
DioscHub answers 403 and does nothing when:
- the token is invalid, tampered with or expired;
- the session does not match the token’s session;
- the operation is not granted by the token;
- the session is no longer live (completed, expired, deleted or quarantined);
- your server is no longer attached to the session’s Assistant.
An invalid token is never retried against the legacy path below: it is refused.
Fetch a user’s file
Section titled “Fetch a user’s file”POST /api/mcp/files/fetch returns a file’s bytes by exact name:
const res = await fetch('https://your-hub.example.com/api/mcp/files/fetch', { method: 'POST', headers: { 'x-api-key': process.env.DIOSC_MCP_FILES_KEY, 'x-file-access-token': fileAccessToken, // from the call's _meta["dioschub/fileAccess"] 'content-type': 'application/json', }, body: JSON.stringify({ name: 'q3-orders.xlsx' }),});// res.body is the raw file streamThe request is keyed by name — there is deliberately no listing or search endpoint. A name that
does not exist returns 404 with no hint about what else is there. Your tool works with names it
already knows (from the conversation, or a put_file it made earlier).
The response streams: DioscHub sends the bytes from storage as it reads them, with Content-Length set,
so read res.body as a stream rather than buffering a large file. A file whose
retention has expired is treated as missing and returns
404, even before the retention sweep deletes it. Fetching is never refused for size or quota.
Write a file back
Section titled “Write a file back”POST /api/mcp/files/upload stores a file into the user’s library and returns the stored name:
const form = new FormData();form.append('file', new Blob([reportBytes]), 'q3-summary.pdf');
const res = await fetch('https://your-hub.example.com/api/mcp/files/upload', { method: 'POST', headers: { 'x-api-key': process.env.DIOSC_MCP_FILES_KEY, 'x-file-access-token': fileAccessToken }, body: form,});const { filename } = await res.json(); // may be disambiguated on a name collisionIf the name already exists, DioscHub keeps both and returns the disambiguated name — an MCP server can never clobber a user’s existing file. The stored file is indexed, so the Assistant can find and reference it by name afterward.
The upload streams straight into storage; DioscHub does not hold the file in memory. Send large files as a stream too. The session is checked before any bytes are stored, so a request for an unknown or refused session stores nothing.
Size limit and quota refusals
Section titled “Size limit and quota refusals”A file written with put_file is a file in the user’s library like any other, so the same
limits apply:
-
Upload size limit — the limit of the session’s Role, else the system limit (default 100 MB, at most 1 GB). DioscHub stops reading at the limit and answers
413:{ "statusCode": 413, "code": "FILE_TOO_LARGE", "limitBytes": 104857600, "message": "File too large" } -
Storage quota — the file counts against the user’s storage quota and file count. A write that would exceed either answers
413:{"statusCode": 413,"code": "QUOTA_EXCEEDED","message": "Storage quota exceeded","usageBytes": 5767168,"quotaBytes": 6291456,"usageFiles": 4,"quotaFiles": 20,"requiredBytes": 2097152}quotaBytesorquotaFilesisnullwhen that dimension has no quota. -
Executables — a file whose bytes, extension or declared type mark it as an executable answers
415withcode: "FILE_TYPE_REFUSED". Any other type is stored and classified by its content; see File types, kinds & parser limits.
Either way nothing is stored — no bytes and no file. Branch on code, not on the status alone, and have
your tool return a plain explanation to the model (for example “the report is larger than the 100 MB
upload limit” or “the user’s file storage is full”), so the assistant can tell the user what to do. If
retention is on, the written file gets an expiry like any other upload.
Scope: the signed-in user’s own library
Section titled “Scope: the signed-in user’s own library”The file scope is resolved from the session, never from anything your server asserts. The file access token carries the session, and DioscHub resolves the file library from the Assistant and the signed-in user on that session. Your server reaches only that user’s own chat-file library for that Assistant — not another user’s files, and not the Knowledge base.
Why the bytes stay out of the model
Section titled “Why the bytes stay out of the model”The file bytes flow only between your server and DioscHub over these HTTP endpoints. The model sees whatever text your tool chooses to return — a summary, a row count, a reference to the written file — but never the file’s contents and never the API key. This keeps large or sensitive files out of the model’s context by construction, the same way Credential Blind keeps auth out of it.
Next: wire identity so your tools know who the user is — Identity & auth.