Publishing to external agents (MCP server)

In Settings (⚙) → the “Connectors” tab, “Publish to external agents” at the top lets agents outside the app, such as Claude Code, read the notes in the vault you have open. It is off by default.

• Turn on “Publish” and the endpoint and a token appear. Use “Copy command” and run it in a terminal to register monthlet with Claude Code. What gets registered is the path to a command bundled with monthlet (monthlet-mcp) — no token is written into the agent config. The token and port are read from monthlet on every connection. Running that command requires Node.js.

• For agents that cannot use that, there is also a “Direct HTTP (with token)” command. That one puts the token in the agent config, so you have to re-register it whenever you regenerate the token.

• Publishing alone allows reading only. Writing is enabled separately with “Allow writing” in the same place (off by default). With it on, external agents can create notes, folders and spreadsheets, rewrite the body of a note, and change the values and formats of spreadsheet cells.

• Moving and renaming are enabled separately with “Allow moving and renaming” in the same place (off by default; writing must also be allowed). Internal links are updated to the new location, and a note you are editing (with unsaved changes) is not moved. Deleting is enabled separately with “Allow deleting” (off by default; writing must also be allowed). Deleted items go to the system trash, and links from other notes and the change history are kept, so restoring from the trash puts everything back. A note you are editing is not deleted.

• Editing spreadsheet cells: agents can change values, formulas (values starting with “=”) and formats. Formulas that refer to the changed cells are recalculated when the sheet is saved, and charts and kanban boards linked to the sheet follow. The version before the change is kept in the history. Inserting or deleting rows and columns, sorting and filtering are not available yet. A sheet you are editing (with unsaved changes) is not written.

• Rewriting a body either replaces all of it or replaces just one piece of text in it, leaving the rest as it was. Leave a placeholder line, such as the one standing in for a chart, and the original element is kept; delete the line and that element goes with it.

• The version before a rewrite is kept in the note’s history (“⋯” at the top right of the note → “Version history”). For a note you have open, ⌘Z also undoes it.

• A rewrite of a note you are editing (with unsaved changes) is refused. So is a rewrite of a note that changed after the agent read it — the agent is told to read it again. To rewrite a note, the agent passes the version it received when reading it; a rewrite without a version, or after another agent has already changed the note, is refused too. Large notes can be read in part by giving a range of lines; a rewrite of a note that was only read in part is refused (it replaces the whole note, so the unread part would be lost).

• Only the vault you have open is published. Switching vaults switches what is published.

• Agents can connect only while the app is running; quitting the app ends the connection.

• Connections are limited to this device (127.0.0.1). Other machines and browsers cannot connect, and a token is always required.

• If you think the token has leaked, press “Regenerate”. The previous token stops working. Agents registered with the bundled command keep working as-is (they hold no token); only agents registered with “Direct HTTP” need to be re-registered.

• External agents can list notes and spreadsheets, search full text, read a note’s body as Markdown, read spreadsheet cells, read the numbers behind a chart, and — when writing is allowed — create notes, rewrite bodies, create folders, create spreadsheets and change cell values and formats, and — when moving and renaming are allowed — move and rename notes and folders. A note’s frontmatter (keys other than title and tags, in the `---` block at the top of the Markdown) is added to the top of the body when reading and saved as-is when rewriting (leaving it out keeps the current one). When reading, the frontmatter also starts with OKF’s `type` key (`type: Note` if the note has none).

• After you change the writing setting, an already-connected agent may hold the old list of operations until it reconnects. Every call is checked against the current setting, so an operation you have not allowed will not run.

• When a note contains something Markdown cannot express, such as a chart, it is passed along as a placeholder with an id. When the numbers are needed, that id reads the chart’s data.

• Besides full-text search, agents can search for an exact string or a regular expression. Matching lines come back with line numbers, and the total count is reported even when not every line is returned. The search can be limited to a folder or a path pattern.

• To the agent receiving them, your notes are text from outside. Whether it ignores anything in them that looks like an instruction depends on how that agent is built.

• With writing allowed, agents can also add and remove tags on notes and spreadsheets, and `[[Note name]]` in a note they create or rewrite becomes an internal link (a name that matches no note stays as text, and the agent is told). The list of notes that link to a note (“Linked from”) is available with reading alone.

• Attachments on a note are supported too. Listing the attachments on that note and reading their contents (images as images, the text of a PDF, the body of a text file) works with reading alone. With writing allowed, agents can add attachments to a note (images, video, audio, PDF and text only; saved in the note’s folder, never overwriting a file with the same name).

• The full list of operations, with their arguments, what they return, and what each one guarantees, is at monthlet.ai/docs/mcp. Point to it when setting up the agent side.

• The folder structure can be read as a tree, including empty folders (with the number of documents in each). The files in a folder (images, PDFs, etc.) can be listed too.