mcpdrives
Documentation menu

Documentation

Transfers and jobs

Tool calls carry paths and small text. File contents move by signed link between storage and the agent's machine, or from one bucket to another, and long copies continue as background jobs.

drive_transfer with action: "download" returns a time-limited GET link for one file; action: "upload" returns a PUT link and the headers to send. The agent fetches them from its own environment, so the bytes go straight between the storage service and the agent's machine:

curl -o deck.pdf "$DOWNLOAD_URL"
curl -X PUT --upload-file ./report.pdf -H 'content-type: application/pdf' "$UPLOAD_URL"
  • Links last 15 minutes unless the agent asks for another lifetime. The drive's setting caps it, 24 hours by default and at most 7 days.
  • A download link can set the file name the browser saves and can open the file inline instead.
  • On a folder where the connection may add files but not replace them, the upload link includes If-None-Match: *, so the storage service refuses to overwrite an existing file. R2, Amazon S3 and MinIO enforce this.
  • A read-only connection gets download links but no upload links. A drop-box connection gets upload links but no download links.

A signed link works for anyone who has it until it expires, even after you revoke the connection that created it. Keep lifetimes short on shared drives.

Large uploads

For a large file, the agent starts a multipart upload with action: "multipart" and the file's size. It receives one PUT link per part, uploads each part and collects the ETag header from each response, then calls action: "complete" with the list of parts. action: "abort" cancels an upload and frees its parts.

Copies and moves

cp and mv in the shell, drive_files and Code Mode's cp() and mv() share one copy engine:

  • Same storage account: when both mounts use the same endpoint and key, each object is copied server-side with the provider's copy operation, and nothing streams. Objects over 5 GiB use a multipart copy.
  • Different providers: each object streams from the source to the destination through mcpdrives. Objects up to 256 MiB use one upload; larger ones use ranged reads and a multipart upload, in parts of at least 16 MiB.
  • A folder copy runs 8 objects at a time, in key order. A move copies each object and then deletes the source.
  • With overwrite turned off, existing files at the destination are skipped and counted.

Streamed bytes count toward your account's daily transfer allowance of 200 GiB. Server-side copies do not.

Background jobs

A tool call copies, moves or deletes for up to 20 seconds. Whatever is left then continues as a background job, and the tool returns the job's ID with the progress so far. A cross-provider object larger than 64 MiB always goes to a job, because a single large object could outlast the request.

  • Jobs advance in steps of up to 500 objects, with the access of the connection that started them.
  • Agents list, check and cancel jobs with drive_jobs. The dashboard shows them on the drive's page.
  • Revoking the connection that started a job cancels the job.
  • An account can run 3 jobs at once and start 200 per day.

Dashboard uploads

Files you upload in the dashboard go through mcpdrives to a five-minute signed link, so your buckets need no CORS settings and your keys never reach the browser. Dashboard uploads are limited to 100 MiB; use an agent with upload links for larger files.