Workspace files from your AI tools

Ask Claude, Cursor or any AI tool connected to your workspace to read a report, file a document or tidy a folder in Workspace files, and it does it as you, in the same folder your team and coworkers use.

​

Before you start

Connect your AI tool to your workspace first: Connect MCP walks through creating a workspace API key and pasting the setup into your tool.

• It acts as a person. Every change is made as the person who created the workspace API key, and shows on the Files page under their name. It works only while that person is an active member of the workspace; if they leave, a current member creates a new key.
• It sees what that person sees. The whole of Workspace files, and nothing in anyone’s tasks.
• Your tool can learn the rules itself. Ask it to read the workspace_files guide (read_mcp_guide) before it starts: paths, mentions, limits and what to do on a conflict.

​

What your AI can do

​

Naming files

A file is named by its path from the top of the folder: Reports/2026/Q3 summary.md. Your tool can also write it as files/Reports/2026/Q3 summary.md or @files/Reports/2026/Q3 summary.md, the way chat messages and coworkers name files. Every result carries a mention to paste into a message for a person or a coworker.

• Names are case-insensitive. Report.pdf and report.PDF can’t both live in one folder. Results spell a path the way it’s really stored.
• An id outlives a rename. Any tool that takes path also takes nodeId, the id from a result. A path names whatever holds that name now; an id keeps naming the same file after someone renames or moves it.

​

Reading and downloading

• Text comes back as text, up to 50,000 characters a call by default and 200,000 at most (maxChars). A longer file is read in slices: the result says hasMore, and your tool asks again from nextOffset with the same versionId, so every slice comes from the same version.
• Any other file up to 5 MB comes back as a download. A bigger one returns its details only; open it on the Files page.
• Search finds names, not contents. To find a file by what it says, your tool searches for likely names, then reads the candidates.

​

Uploading and replacing

When the name is taken, write_workspace_file refuses by default. ifExists decides: To replace safely, read first and pass the revision it returned as ifMatch. If someone changed the file in between, the write is refused with a conflict instead of overwriting their work; your tool reads again and decides. note, one line of up to 500 characters, shows in the file’s history.

​

Versions

Your tool’s saves to one file within 10 minutes join one version, so a tool fixing a report in several passes leaves one version, not ten. Because the tool acts as a person, a replace takes one of the file’s three version places like your own save would, and can push out the oldest version, whoever wrote it. Before an AI tool rewrites a file you can’t lose, make it a checkpoint on the Files page, or ask the tool to write beside it with keep_both. Your tool can’t make or remove checkpoints itself.

​

The Trash, not delete

There’s no permanent delete from an AI tool. trash_workspace_file moves a file or a whole folder to the Trash, where anyone can restore it for 30 days. Ask your tool to tell you what it trashed.

​

Try these

“Read Reports/2026/Q3 summary.md in Workspace files and save a one-page version beside it as Q3 summary short.md.”

“Find every invoice PDF changed this week in Workspace files and move them into Inbox/Invoices.”

“List what’s in the Contracts folder and tell me which files Sam changed last.”

​

Common questions

​

Next steps