Documentation
Access and sharing
Access is set in up to three places, and an agent gets the narrowest of them. You can end any connection, any share link or a whole drive from the dashboard.
Permissions
mcpdrives checks four permissions on every call, for the folder the call touches:
- Read: list folders, read files, search and download.
- Create: add files that do not exist yet, including uploads and folders.
- Overwrite: replace or edit existing files.
- Delete: delete files and move them away.
The dashboard offers them as five levels:
| Level | Read | Create | Overwrite | Delete | Typical use |
|---|---|---|---|---|---|
| Read only | Yes | No | No | No | List, read, search and download. |
| Add files | Yes | Yes | No | No | Read, plus add new files and folders. Never changes or deletes existing files. |
| Read and write | Yes | Yes | Yes | No | Read, add and edit files. No deletes. |
| Full access | Yes | Yes | Yes | Yes | Read, add, edit, move and delete. |
| Drop box | No | Yes | No | No | Add new files only. Cannot list or read anything. |
On a folder without overwrite, mcpdrives asks the storage service to refuse replacements with If-None-Match: *. Cloudflare R2, Amazon S3 and MinIO enforce that in the same request. For other providers, mcpdrives checks first and then writes, which leaves a short window in which a file created by someone else could be replaced.
Where access is set
- The mount. Its access is the most any agent can do in that folder.
- The connection. When you approve an agent, you choose a level and the folders it can see. Hidden folders do not appear at all, not even in a listing of
/. - The share link. A link sets a level and folders for everyone who connects through it.
An agent's access in a folder is what all of these allow together. A full-access connection to a read-only mount can still only read there. A connection approved with a share link never gets more than the link allows, whatever the agent asks for.
Tools by access
A drive shows each connection only the tools it can use. This table comes from the server's own tool list for each level.
| Tool | Read only | Drop box | Add files | Read and write | Full access |
|---|---|---|---|---|---|
drive_ls | Yes | Yes | Yes | Yes | Yes |
drive_read | Yes | No | Yes | Yes | Yes |
drive_search | Yes | No | Yes | Yes | Yes |
drive_write | No | Yes | Yes | Yes | Yes |
drive_edit | No | No | No | Yes | Yes |
drive_files | No | Yes | Yes | Yes | Yes |
drive_transfer | Yes | Yes | Yes | Yes | Yes |
drive_shWhen the drive's shell is on | Yes | Yes | Yes | Yes | Yes |
drive_codeWhen Code Mode is on | Yes | Yes | Yes | Yes | Yes |
drive_jobs | Yes | Yes | Yes | Yes | Yes |
drive_activity | Yes | Yes | Yes | Yes | Yes |
drive_manageOnly when you allow management | Yes | Yes | Yes | Yes | Yes |
Tools that appear for every level still check each call. drive_transfer gives a read-only connection download links but no upload links, and the shell refuses a write to a read-only folder.
Approving an agent
The approval page shows the app's name, which the app supplies itself, the address the sign-in returns to and the client ID. Agents on your own computer, such as Claude Code or Codex, return to a 127.0.0.1 or localhost address; approve those only right after you start the connection yourself.
You choose the connection's name, its level, its folders and how long it lasts, from one day to until you revoke it. If every folder is checked, the connection also sees mounts you add later. As the owner, you can also let the agent manage the drive: add storage through one-time links, mount and unmount folders and edit the drive's instructions.
Share links
A share link lets someone else connect their own agent to your drive without an account. They open the link in their browser, add the drive's URL to their agent and approve the connection themselves, within the link's limits. You set:
- a name, so you recognize the link later;
- the level and folders, read only by default;
- when the link stops working, from one day to one year, or never, seven days by default;
- how many connections it allows, from 1 to 1,000, or no limit;
- how long each connection lasts, up to 365 days, 30 by default.
Revoking a share link ends every connection that was approved with it. A drive can have up to 50 share links.
Access requests
If you turn on access requests in a drive's settings, someone who has neither an account nor a link can ask for access. Their approval page offers a note to you, and their browser waits. You see the request in the dashboard and on the approval page, and when you approve it, their browser continues and their agent connects. Your own browser stays on mcpdrives.
Access keys
For clients that cannot sign in through a browser, create an access key on the drive's Access tab with a name, a level and an expiry. The key is shown once; mcpdrives stores only its hash. The client sends it as Authorization: Bearer.
Revoking and pausing
| Action | Effect |
|---|---|
| Revoke a connection or key | Its tokens stop working on the next request. Its background jobs are cancelled. |
| Revoke a share link | The link stops working, and every connection approved with it is revoked. |
| Pause a drive | Every connection to the drive is refused until you resume it. |
| Delete a drive | Its connections, share links and mounts are removed. Files in your buckets are untouched. |
| Remove a storage connection | Possible only when no mount uses it. The encrypted secret is deleted. |
Signed download and upload links that were already issued keep working until they expire, because the storage service checks them, not mcpdrives. Keep link lifetimes short on drives you share.
A drive can have up to 100 active connections at a time.