MCP tool reference

All 22 tools the MCP endpoint exposes, with their parameters, their defaults and what refuses a call.

Every connection sees the same catalog. What a call may actually touch is decided by the per-folder access of the person the token belongs to, so two tokens in the same vault can get different answers from the same tool.

Conventions

vaultIdstring: Comes from list_vaults. Most tools that work across a vault need it.
docIdstring: A note's stable id, from list_notes or search_notes. It survives renames and moves.
relPathstring: A vault-relative path, such as Ideas/draft.md. Folders in it must already exist.
revisionstring: Returned by read_note. Pass it as expectedRevision on a write to refuse rather than merge if the note changed.
Annotations: Each tool is marked read-only, write or destructive, so a client can decide what to confirm before calling.
Unknown properties: Refused. Every input schema is closed.

Access tools are owner and admin only. Everything else answers within the caller's own permissions.

Discovery

list_vaults

Lists the top-level note collections you can reach, each with a vaultId. Start here. Takes no parameters.

list_folders

Lists every folder in a vault, with its path and parent.

vaultIdstringrequired: From list_vaults.

list_notes

Lists the notes you can access in a vault, optionally within one folder. Each row carries the note's docId, title, path and your permission on it.

vaultIdstringrequired: From list_vaults.
folderIdstring: Restrict the listing to one folder.

search_notes

Semantic and keyword search across everything you can access: notes, and the text extracted from files such as docx, xlsx, pdf, csv and code. Each hit carries a kind of note or file, so you know whether to follow it with read_note or read_attachment_text.

vaultIdstringrequired: From list_vaults.
querystringrequired: What to search for.
knumber: Maximum results. Default 10, capped at 50.
includeFilesboolean: Search the text of files as well as notes. Default true.

Reading

read_note

Reads a note's full Markdown by docId, and returns its current revision alongside the content.

docIdstringrequired: From list_notes or search_notes.

list_attachments

Lists the files, as opposed to notes, that you can access: spreadsheets, documents, PDFs, images and other attachments. Each row's hasText says whether read_attachment_text has anything for it.

vaultIdstringrequired: From list_vaults.
folderstring: A vault-relative folder to list within, such as Team/Reports.
limitnumber: Maximum files. Default 50, capped at 200.

read_attachment_text

Reads the extracted plain text of a file, not the file itself. A file that has not been indexed yet returns empty text rather than an error.

vaultIdstringrequired: From list_vaults.
relPathstring: The file's vault-relative path, such as Team/q3.xlsx. Use this or blobId.
blobIdstring: The file's blob id, from list_attachments or a file search hit.
maxCharsnumber: Maximum characters. Default 20,000, capped at 200,000. The reply's truncated says whether there was more.

Writing notes

create_note

Creates a new Markdown note. Every folder in relPath must already exist, so create folders first if you are building a tree.

vaultIdstringrequired: From list_vaults.
relPathstringrequired: Vault-relative path ending in .md, such as Ideas/draft.md.
titlestring: Display title. Defaults to the file name.
folderIdstring: Usually omitted. If given it must be the folder whose path is relPath's directory.
contentstring: Initial Markdown content.

update_note

Replaces a note's entire content. Prefer edit_note when you are changing part of a note, so you are not resending text you did not touch.

docIdstringrequired: The note to replace.
contentstringrequired: The new full Markdown content.
expectedRevisionstring: The revision from read_note. If the note no longer matches, the write is refused as a conflict: read again and retry.

append_note

Appends text to the end of a note.

docIdstringrequired: The note to append to.
textstringrequired: Markdown to append.
expectedRevisionstring: Refuses the append if the note changed since you read it.
idempotencyKeystring: A caller-chosen key, such as a UUID. A repeat with the same key returns the first result instead of appending twice. Use it whenever a call may be retried.

edit_note

Makes targeted edits without resending the body: replace exact text, insert before or after an anchor, or delete exact text. Edits apply in order, each matched against the text as the previous edit left it.

docIdstringrequired: The note to edit.
editsarrayrequired: One or more edits, applied in order.
edits[].typereplace · insert_before · insert_after · deleterequired: What to do at the anchor.
edits[].findstring: Exact text to replace or delete. Matched exactly first, then ignoring differences in whitespace, quotes, dashes and Unicode form.
edits[].replacestring: Replacement text, for replace.
edits[].anchorstring: Exact text to insert next to, for the insert types.
edits[].textstring: Text to insert, for the insert types.
edits[].allboolean: For replace and delete: apply to every occurrence instead of requiring exactly one.
expectedRevisionstring: Also refuse the whole call if the note changed since you read it.

An anchor that is missing, or that matches more than once without all, refuses the entire call and writes nothing. A partial edit is never left behind.

delete_note

Deletes a note. The delete is soft: its edit history is preserved and the server's Trash can restore it.

docIdstringrequired: The note to delete.

Folders and files

create_folder

vaultIdstringrequired: From list_vaults.
namestringrequired: Folder name.
pathstringrequired: Vault-relative folder path, such as Ideas/Drafts.
parentIdstring: Parent folder id, when you have it.

delete_folder

folderIdstringrequired: From list_folders.
recursiveboolean: Delete the contents too: notes are soft-deleted and subfolders removed. Default false, which refuses a folder that is not empty.

move_note

Renames, moves or retitles a note. It keeps its docId and its full history, so links and edits survive.

docIdstringrequired: The note to move.
relPathstring: New vault-relative path ending in .md. Its directory must be an existing folder, which becomes the note's folder.
titlestring: New display title.
folderIdstring | null: Re-parent the note while keeping its file name. null means the vault root. Omit to leave it where it is.

move_folder

Renames or moves a folder. Its notes and subfolders move with it: every descendant path is rewritten in place and every id preserved, so backlinks and history survive.

folderIdstringrequired: The folder to move.
pathstring: New vault-relative folder path.
namestring: New name. Defaults to the last segment of path.
parentIdstring | null: New parent folder id, or null for the vault root.

move_file

Renames or moves a file that is not a note, keeping its id.

fileIdstringrequired: The id list_attachments reports.
pathstringrequired: New vault-relative path, such as Archive/report.pdf. Its directory must be an existing folder.

delete_file

Deletes a file such as a PDF, image, Office document or CSV, for everyone. Teammates' stale copies are set aside rather than re-uploaded.

fileIdstringrequired: The id list_attachments reports.

Access

These four are owner and admin only, and they write the same rows the Members and access page writes.

get_access_default

Reads what future members will see when they join, which is the New members row: open for Can edit, readonly for Can view, private for No access. Takes no parameters.

set_access_default

Sets that default. Existing members are unchanged.

modeprivate · readonly · openrequired: The level future members get for content that already exists.

list_resource_access

Lists every member's effective access to one folder or file, after each person's own vault level, the team's access and any locks.

resourceTypefolder · filerequired: What kind of thing resourceId names.
resourceIdstringrequired: A folder id, or a file or note docId.

manage_access

Replaces access on one or more folders and files, or on the whole vault. An org audience clears the custom per-person overrides in the selected subtrees, while a users audience changes only those people. A users audience on the vault resource writes that person's absolute vault level.

resourcesarrayrequired: 1 to 1000 targets, each { resourceType, resourceId }, where resourceType is folder, file or vault. For vault, the id is the organization id.
audienceobjectrequired: { type: "org" } for everyone, or { type: "users", userIds: [...] } for named people.
modeprivate · readonly · openrequired: No access, Can view or Can edit.

Refusals and conflicts

What happened	What you get back
The note changed since you read it	A conflict refusal. Read it again and retry with the new `revision`
An `edit_note` anchor is missing or ambiguous	The whole call is refused and nothing is written
The caller cannot see the target	The same answer as if it did not exist, rather than a hint that it does
The caller may read but not write	A permission refusal on the write, with reads still working
An access tool called by a plain member	Refused: those four are owner and admin only
A token that has been revoked	401, with a header pointing an OAuth-capable client at the authorization server

Tool annotations let a client separate a read from a destructive write before calling, which is what makes an approval prompt meaningful. delete_note, delete_folder, delete_file, update_note and the two access writes are marked destructive.

This page is written from app/apps/server/src/mcp/tools.ts and app/apps/server/src/http/routes/mcp.ts in the repository. Those documents go further, and they are the ones that change first.

Read it on GitHub

Was this page helpful?

PreviousBuild from source NextSettings reference