Notezbeta
Back to blog

Claude Code can now put images in your notes: file uploads over MCP

ProductDenis Povarov

Ask an AI assistant to write up yesterday's incident and it will do a fine job — right up to the graph. The screenshot sits on your desktop, the note says "see attached", and nothing is attached. Until now the Notez MCP server could read, write, and reorganize your notes, but a file on your computer was out of its reach.

Notez v0.11.0 closes that gap. Any MCP assistant that can run shell commands — Claude Code, Cursor, Codex CLI — can now upload a local image or file and put it straight into a note.

What it looks like

You ask:

Add ./grafana-latency.png to my Incident 2026-09-10 note, right under the Timeline heading, and attach the raw logs from ./incident-logs.zip.

The assistant uploads both files and edits the note. The screenshot shows inline under Timeline; the archive becomes a file chip you can click to download. Both appear on your Files page, count against your storage like anything else, and follow the same formats and size limits as the editor.

It works everywhere a note gets written: creating a new note, editing part of one, or rewriting it.

Why the file never goes through the chat

The obvious design is a tool that takes the file as an argument. MCP tool calls are JSON, so the file would travel as base64 text inside the model's own output — roughly 35,000 tokens for a 100 KB screenshot, and a PDF would not fit at all. The protocol has no way to transfer a file yet; a proposal for exactly that is still a draft.

So we used the path the Notez editor already uses. When you drop an image into the editor, your browser asks the server for a signed upload and sends the bytes straight to storage. An assistant does the same thing in three steps:

  1. It asks for an upload. The create_upload tool takes the file name, its type, and its exact size, and answers with a ready-to-run curl command signed for that one file.

  2. It runs the command. The file goes from your machine to storage directly. Nothing passes through the conversation, so a 20 MB PDF costs no more tokens than a 20 KB one.

  3. It confirms. confirm_upload checks the file actually arrived, then hands back a one-line snippet the assistant pastes into the note.

The catch is simple and honest: step 2 needs a shell. Assistants that can run commands, like Claude Code and Cursor, handle it without being asked. Chat-only clients such as Claude Desktop cannot, and they say so instead of pretending — they point you to the app.

Checking the file really arrived

An agent can report "done" about a command that failed. Rather than take its word for it, confirm_upload asks storage for the file. If nothing is there, the assistant is told to run the command again. If the bytes that arrived are not the size it declared, the upload is refused and it starts over. The declared size is what your storage quota counts, so a file that misstates its size never gets recorded.

This is the part we spent the most time on.

Notez keeps track of every file a note uses. That tracking is what lets it clean up after you: when you delete an image from a note its storage is eventually freed, and a file uploaded but never used is removed after three days. In the editor you never see any of this, because every image it inserts carries a hidden file id.

An assistant writes Markdown by hand. After an upload, the most natural thing in the world for a model to write is a plain image link — ![latency](https://…/grafana.png). It renders. It looks right. And it carries no file id, so as far as Notez is concerned the note does not use that file. Three days later the cleanup removes it, and a note you shared last week quietly shows a broken image.

We caught this while building the feature rather than after shipping it, and closed it from both ends:

  • The assistant gets the right markup. confirm_upload returns a snippet that already carries the file id, and the server's instructions tell the assistant to paste it verbatim.

  • Notez refuses the wrong markup. If a note write links a freshly uploaded file by its address alone, the write is rejected with an explanation, and the assistant retries with the snippet. Links to anything else still work: pictures from other sites, and files that already live safely in another note.

The same guard protects the in-app AI chat, so neither assistant can leave a time bomb in your notes.

What to know before you try it

  • Uploads are reachable by their exact address, just like images you paste into the editor. Nothing lists them and the addresses cannot be guessed, but do not upload anything you would not put in a note.

  • Storage belongs to the workspace owner. Uploads count against the account that owns the workspace, whichever way the assistant connected.

  • Screenshots are stored at full size. The editor compresses images in your browser; an assistant's upload arrives exactly as the file sits on disk.

  • In-app AI chat cannot upload. It runs in your browser with no access to your files. The two upload tools, and list_workspaces for sign-in connections, are the only ones the MCP server has that chat does not.

Try it

  1. In Notez, open Settings → Integrations → Notez MCP server and click Generate MCP key.

  2. Add it to Claude Code with the command shown on that page, or to Cursor with the JSON config.

  3. Ask for something with a file in it: "Put ./architecture.png in my System design note."

The full reference — every tool, error, and limit — is in MCP server setup, and Files and attachments covers formats and storage.

FAQ

Can Claude Code upload images to Notez?

Yes. Claude Code can run shell commands, so it can use the create_upload and confirm_upload tools to put a local image or file into any note in a workspace it's connected to.

Does it work in Claude Desktop?

Not out of the box. The upload step runs a curl command, and Claude Desktop cannot run commands unless you have given it a tool that can. It will tell you to add the file in the app instead.

Which files can an AI assistant upload?

The same ones as the editor: images (JPG, PNG, GIF, SVG, WEBP, and more), PDFs and office documents, video, and ZIP or RAR archives — up to your plan's per-file limit.

Does an uploaded file count against my storage?

Yes — the storage of the workspace owner's account, exactly like a file added in the editor.

What does NOTE_UPLOAD_NOT_LINKED mean?

The assistant tried to link an uploaded file by its address alone. Notez refuses that because the file would not be tracked and would be removed after three days. The assistant should paste the snippet confirm_upload returned — most retry on their own.

Continue reading