Documentation

Drives and mounts

A drive is a named folder tree with its own MCP URL. Each top-level folder in it is a mount: a bucket, or a folder inside a bucket, from one of your storage connections.

Drives

Make one drive per job or per audience: a drive for a design agent, another for a nightly report job, another that you share with a reviewer. Every account starts with a drive named Home, which cannot be deleted. An account can have up to 50 drives.

Each drive has a name, instructions for agents and a status. Pausing a drive refuses every agent connected to it until you resume it. Deleting a drive removes its mounts, share links and agent connections, and cancels its background jobs. It never touches the files in your buckets.

Mounts

A mount places a bucket folder at a path in the drive. You choose:

• the path, such as /r2-media or /clients/acme;
• the storage connection and the bucket;
• an optional folder prefix inside the bucket, up to 512 bytes, such as media/2025/;
• the access: read only, add files, read and write, full access or drop box.

Mounts in one drive can come from different providers and different accounts. A drive holds up to 16 mounts.

Path rules

• A path has at most four levels, and each level starts with a letter or digit and uses letters, digits, ., _ and -, up to 63 characters.
• Mounts cannot share a path or sit inside each other. /clients/acme and /clients/zenith can both exist; /clients and /clients/acme cannot.
• A mount at / must be the only mount in the drive.
• The shell reserves these top-level names: tmp, bin, usr, dev, proc, etc, sys, sbin, lib, var and mcp.

When mounts share a parent, such as /clients/acme and /clients/zenith, the parent /clients is a virtual folder. Agents can list it, and nothing can be written to it.

Paths and keys

Object storage has keys, not folders. mcpdrives maps a path to a key by removing the mount path and adding the folder prefix. With /r2-media mounted from bucket media, prefix 2025/:

/r2-media/backup/deck.pdf  →  bucket "media", key "2025/backup/deck.pdf"

A folder is every key that starts with its path. An empty folder that an agent creates with mkdir is stored as a zero-byte marker key that ends in /, the same convention most storage consoles use. Paths outside the mount's prefix do not exist for the agent, so .. cannot reach other keys.

What the agent is told

When an agent connects, the drive sends it instructions: the drive's name, your own instructions for it and the mounts with their access. This is the text an agent receives for an example drive with full access to one mount:

"Example" is an mcpdrives drive: S3-compatible storage presented as one folder tree.
Mounts (each is a top-level folder):
  /work: Example bucket, read, create, overwrite, delete
Paths are absolute (e.g. /assets/notes.md). Folders are key prefixes; a mount you cannot read may still accept new files.
Use drive_sh for bash across mounts: cp -r /a/x /b/y, mv, rm, grep -rn, find, jq, pipes. /tmp is scratch.
Use drive_read, drive_write and drive_edit for precise changes; pass the etag from a read as ifMatch so you never overwrite someone else's newer change.
Use drive_transfer to move bytes without sending them through this conversation: it returns links you can curl from your own environment.
Use drive_code for multi-step programs (loops, filtering, bulk edits) that run next to the data.
Large copies, moves and deletes continue as background jobs (drive_jobs).

Write your instructions in the drive's settings, up to 2,000 characters. Use them for conventions such as "Put drafts in /assets/drafts and never edit /assets/final".

Drive settings

Activity

Every write, edit, copy, move, delete, link, shell run and Code Mode run is recorded with the time, the path, the byte count and the name of the connection that made it. The log never stores file contents, shell commands, programs or secrets. Each account keeps its latest 10,000 entries. Agents can read recent activity with drive_activity to pick up where another agent left off.