Skip to content

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.

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.

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.

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 stream

The 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.

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 collision

If 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.

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
    }

    quotaBytes or quotaFiles is null when that dimension has no quota.

  • Executables — a file whose bytes, extension or declared type mark it as an executable answers 415 with code: "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.

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.

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.