The Notez MCP server lets an AI assistant read, create, and reorganize your notes over the Model Context Protocol — and upload images and files into them.
Two ways to connect
Sign in: Claude, ChatGPT, VS Code and Claude Code. Add
https://api.notez.dev/api/mcpas a connector, sign in to Notez and allow access. There is no key, and one connection reaches every workspace you belong to. Step by step: Connect Claude, ChatGPT or VS Code.An MCP key: Cursor, Windsurf, scripts and CI, or Claude Code if you prefer. The workspace owner generates a key that works in that one workspace. The rest of this page is about keys.
Both use the tools listed under The tools below; a sign-in connection adds list_workspaces.
1. Generate a key
In Notez, go to Settings → Integrations and find the Notez MCP server tile. It shows Configured or Not set up.
Click Generate MCP Key, then copy the Endpoint and the Bearer token. The token is shown once — store it somewhere safe. Notez keeps only a hash of it, so once you leave the page it shows just the key's first characters, and the only way to see a full key again is to rotate it.
The key is bound to the workspace you are currently in. Only the workspace owner can generate or rotate it; other members connect by signing in.
Keys generated before v0.15.0 stopped working when keys moved to hashed storage: generate a new one and update your client.
2. Add it to your client
Right after you generate or rotate a key, the Integrations page shows both snippets with your real endpoint and token already filled in — copying from there is the least error-prone route. Later visits show YOUR_MCP_KEY in their place.
Claude Code
claude mcp add --transport http --scope user notez <your-endpoint> \
--header "Authorization: Bearer <your-token>"The --header line is required. Without it the server is added but every call fails authentication.
--scope user makes Notez available in every project you open in Claude Code. Leave it out and Claude Code adds the server to the current project only. Because a key is bound to one workspace, a user-scope server reaches the same workspace everywhere; to connect one project to a different workspace, generate a key in that workspace and run the command in that project without --scope user. The project's own server takes precedence over the user-scope one.
JSON config — for Cursor and Windsurf, the page shows ready-to-paste JSON including the same Authorization header. Claude Desktop connects by signing in instead; see Connect Claude, ChatGPT or VS Code. Config file locations:
Client | Location |
|---|---|
Claude Code |
|
Cursor |
|
Windsurf |
|
3. Restart and test
Restart your client, then ask something like "What Notez tools do you have?" or "Search my Notez notes for anything about onboarding."
The tools
Reading
Tool | What it does |
|---|---|
| The workspace with its members, tags, properties and board columns |
| Search and list with filters and pagination |
| Semantic search by a question or by a note, up to 5 results |
| A whole kanban board, cards grouped by column, with a total per column |
| The reminders that remind you and every date property value between two dates, up to 62 days |
| One note, by id or by its link, as Markdown, plain text, or full detail, with who created it and how it arrived |
| Direct children of a note |
| The path from root to parent |
| The notes a note links to, and the notes that link to it |
| All tags with note counts |
| The workspace's custom properties and their options |
| One note's property values and tags |
| Search the Notez Help Center and read the best-matching article |
Writing
Tool | What it does |
|---|---|
| Create a note; supports Markdown, tag IDs, and a parent |
| Change a note's title |
| Change part of a note, leaving the rest untouched |
| Rewrite a whole note body |
| Set or clear one custom property value |
| Replace a note's tags with existing ones |
| Add a note to favorites, or remove it |
| Nest a note under another, or return it to the top level |
| Move a note between the columns of its board, or off it |
| Add columns to the workspace board or to a note's own board |
| Create tags by name, in a batch, idempotently |
| Define a new custom property for the workspace |
| Rename a property, rename its options, or add options |
| Rename a tag or a board column |
| Move a note, and everything under it, to the trash |
| Bring a note back from the trash, with the notes trashed along with it |
Files
Tool | What it does |
|---|---|
| Start uploading a local file; returns a ready-to-run |
| Check the file arrived and return the snippet that embeds it in a note |
That is 31 tools with a key. The first 29 are the same ones in-app AI chat uses; the two file tools exist only here, because the upload runs as a shell command — see Uploading images and files below.
An app connected by signing in gets one more, list_workspaces, which lists the workspaces it can act in. Every other tool except search_help and get_note then takes a workspace argument. get_note finds the note in whichever of your workspaces holds it, so a pasted note link works without one. That makes 32. A connection allowed Read only gets 14: the reading tools above plus list_workspaces. The writing and file tools are not offered to it at all.
Each tool is marked as reading, writing, or destructive (replace_note_content and delete_note), so apps that ask before making a change, such as ChatGPT, can tell which is which.
list_notes is the one listing tool, and every filter on it ANDs with the others: substring search, tags, board columns, custom property values, note type, favorites-only, top-level-only, the Bin, created and updated day ranges, ordering, and pagination. One call answers "notes tagged work, updated this week, not in the Done column". Called with no arguments it returns the most recently updated notes.
Day ranges are read in UTC. An MCP client has no browser to report a timezone, and UTC is the one reading that does not depend on where the server happens to run — so pass explicit YYYY-MM-DD days and expect UTC boundaries.
get_board reads up to 20 cards per column. A busier column still reports its true total, and the rest can be paged with list_notes and that column's id.
search_similar_notes depends on semantic indexing being available; when it is not, assistants fall back to list_notes. Given a note's id instead of a question, it finds the notes most like that one, including ones that do not link to it. A note saved moments ago may not be indexed yet.
get_note_links lists both directions: the notes a note links to and the notes that link back to it. Inline note links and relation properties both count.
get_note also says who created the note and when, how it arrived (source: the app, AI chat, MCP, the API, an import and so on), and who last edited it. Ask "who added this note?" and the assistant can answer.
get_calendar reads what the Calendar page shows, for a range of up to 62 days: the reminders that remind you, one entry per occurrence of a repeating one, and every date property value in the workspace. Reminders that remind only other members are never listed, and copies of a reminder in one note are listed once. To set a reminder, the assistant creates a short note titled with what to remember, holding the reminder, or adds it to a note you point at. To move or stop one, it edits that note, and a change to a repeating reminder moves the whole series. Notez does not pass your time zone to the app, so it uses the one the app knows, else the one on your existing reminders, else it asks you; a reminder set without one runs on UTC. See Reminders and the calendar.
Pointing the assistant at a note
Every note has a link, https://notez.dev/notes/<id>. Copy it with Copy link in the note's ⋯ menu and paste it into the chat. The assistant passes it to get_note, which takes the link as well as a bare id, and reads the note in one call. It never tries to open the link in a browser, where it would only hit the sign-in page. When it mentions a note in a reply, it links it the same way.
A public share link (notez.dev/share/…) carries no note id, so the assistant asks for the note's own link instead. With a key, a link to a note in another workspace comes back as not found, and the assistant says so rather than searching for it.
What it deliberately cannot do
The MCP server cannot delete anything permanently — not a note, and not a tag, property, option, or board column. Creating and renaming those is allowed (rename_tag_or_board_column for tags and columns, update_property for properties and their options); removing one would erase data on every note that used it, so that decision stays with you in the app.
It is worth knowing that a note's board follows its position in the note tree, so move_note takes a note off its board as a side effect of re-filing it.
Every write is recoverable: body edits and renames are snapshotted into Version history, and delete_note moves a note to the Bin rather than erasing it, where restore_note can bring it back. Deleting a note takes its child notes with it, and the response reports how many went along, so an assistant can tell you the scale of what it just did.
The 29 shared tools match in-app AI chat exactly — same names, same arguments, same required fields. The two file tools are the one deliberate exception: chat runs in your browser and has no shell to run an upload. A test fails the build if the lists drift apart any other way.
Uploading images and files
An assistant that can run shell commands — Claude Code, Cursor, Codex CLI — can put a local image or file straight into a note. Ask in plain words: "Add ./diagram.png to my Architecture note."
Behind that one sentence it does three things:
Asks for an upload with
create_upload: the file name, type, and exact size. Notez answers with a signedcurlcommand.Runs the command. The file goes from your machine straight to storage and never passes through the conversation, so a large PDF costs no tokens.
Confirms with
confirm_upload, which checks the file really arrived at the size it declared, then returns a one-line snippet the assistant pastes into the note.
Images show inline; anything else becomes a file chip, exactly as if you had dropped it into the editor. Everything in Files and attachments applies: the same formats, the per-file and storage limits of the workspace owner's plan, and the files appear on the Files page.
Worth knowing:
It needs a shell. Chat-only clients such as Claude on the web, desktop or mobile, and ChatGPT, cannot run the upload, and will tell you to add the file in the app instead.
Uploads count against the storage of the workspace's owner, whoever connected the assistant.
Anyone with a file's exact address can open it, the same as an image you paste into the editor. Nothing lists these files, and the addresses cannot be guessed.
An upload has to end up in a note. One that is never inserted is deleted after 3 days. Assistants insert it in the same step, so this only matters if something interrupts them.
Plain links to an upload are refused. Written as
without its file id, an upload would never be tracked and would disappear after 3 days, so Notez rejects the write and the assistant pastes the snippet instead.
Workspace binding
Each key grants access to one workspace. The Integrations page states it directly: the key is bound to the workspace it was generated in, and only grants access to notes and tags within that workspace — switch workspaces to generate a separate key.
This is the main safety property. Keep work and personal notes in separate workspaces and a key in a work project cannot reach personal notes. It is enforced server-side on every tool call.
A sign-in connection works differently: it belongs to your account, reaches every workspace you are a member of, and names the workspace on each call. If you want an assistant that can only ever see one workspace, give it a key. Apps connected by signing in are listed, and can be disconnected, in Settings → Security → Connected apps.
Rotating a key
Rotate MCP key on the same tile issues a new token and invalidates the old one immediately. Do this if a token is committed to a repository or otherwise exposed, then update your client config.
Example prompts
"Find all my notes tagged research and summarize the top 3."
"Create a note titled Daily Standup with my blockers for today."
"What have I written about focus and deep work in my notes?"
"File my scattered meeting notes under a single Meetings note."
"Add a Status property of Done to everything I finished this week."
"What is on my Notez board right now, and what is still in progress?"
"What is on my calendar this week?"
"Remind me to call Anna on Friday at 10."
"Set up a board for Project Apollo with Backlog, Doing, and Done."
"Add ./architecture.png to my System design note, under the Overview heading."
"Turn the action items in this note into a checklist at the end of it", followed by the note's link.
"Who added this note, and which notes link to it?", followed by the note's link.
"Bring back the Q4 roadmap note I deleted yesterday."
Troubleshooting
Tools do not appear. Restart the client fully — most read MCP config only at startup. Check the JSON is valid and the endpoint is complete.
Authentication errors. The most common cause is a missing or malformed Authorization: Bearer header — re-copy the snippet from the Integrations page. The token may also have been rotated.
The assistant cannot find a note. Confirm the key is bound to the workspace holding it — ask it to run get_current_workspace. A key reaches only its own workspace, so a link to a note anywhere else comes back as not found: use a key from that workspace, or connect by signing in.
It offers the wrong tools. Clients cache the tool list at startup. An assistant still offering filter_notes, still claiming it cannot edit or rename a note, or saying it cannot see your reminders, is reading an old tool list — restart it fully and ask what Notez tools it has. filter_notes was removed; its job now belongs to list_notes.
An upload fails. FILE_NOT_UPLOADED means the curl step did not finish — the assistant runs it again and retries. FILE_SIZE_MISMATCH means it declared the wrong size and starts over. FILE_TYPE_NOT_ALLOWED means the format is not accepted; the list is in Files and attachments.
The assistant says it cannot upload. It has no shell. Claude Desktop and other chat-only clients cannot run the upload command — add the file in the app, or use Claude Code or Cursor.
A plain link is refused. The error NOTE_UPLOAD_NOT_LINKED means the assistant wrote the file's address as a plain link, which Notez would not track. Ask it to paste the snippet confirm_upload returned instead.
An app connected by signing in misbehaves. Expired sign-in links, guest accounts, the wrong workspace and password changes are covered under If something goes wrong in Connect Claude, ChatGPT or VS Code.
Notes created over MCP
They are tagged with source: mcp and show an MCP badge, so you can always tell what your assistant wrote versus what you wrote.