Moldavite MCP

Moldavite MCP

Use Moldavite's MCP server instead of direct filesystem writes whenever its tools are connected. Client-visible tool names may include a server prefix; match the operation suffix such as read_note or search_notes.

Connection

Moldavite's app binary also runs a headless stdio MCP server:

"/Applications/Moldavite.app/Contents/MacOS/moldavite" --mcp

Pin one connection to a Forge:

"/Applications/Moldavite.app/Contents/MacOS/moldavite" --mcp --forge "Work"

Without --forge, each request uses Moldavite's current active Forge. With --forge, all requests stay pinned to that Forge.

Read Workflow

1. Use search_notes for a concept or list_notes for known folders.
2. Treat search results as candidates, not complete note content.
3. Use read_note before quoting, summarizing, or modifying a note.
4. Use get_backlinks when relationships or incoming context matter.
5. Report locked placeholders without trying to bypass them.

search_notes returns its mode. Semantic mode is used only when local semantic search is enabled and ready; otherwise Moldavite falls back to keyword search. Never claim semantic matching when the response says keyword.

Create Workflow

1. Search or list first to avoid duplicate notes.
2. Choose a valid Forge-relative .md path.
3. Build complete Moldavite-compatible Markdown.
4. Call create_note once. It refuses existing and locked paths.
5. If creation fails because the path exists, read the existing note and ask or merge deliberately. Do not overwrite automatically.

Replace Workflow

write_note replaces the entire raw file; it is not a patch operation.

1. Call read_note immediately before writing and keep its contentHash.
2. Preserve frontmatter, unrelated sections, and formatting.
3. Apply the smallest requested change in memory.
4. Call write_note with the full resulting Markdown and that contentHash as baseHash. If the file changed on disk in between, Moldavite keeps the disk version as a conflict copy and names it in conflictCopy. Omitting baseHash overwrites silently.
5. If the response names a conflictCopy, tell the user. Do not delete or merge it without asking.
6. Do not retry blindly after an error or unexpected concurrent change.

Daily Append Workflow

Use append_to_daily_note for journal entries and logs. Omit date for Moldavite's local today or pass exact YYYY-MM-DD. The tool creates the daily note when absent.

Appending is not deduplicated. Read the daily note first when repeated content would be harmful.

Path Contract

Valid note paths:

daily/YYYY-MM-DD.md
weekly/YYYY-Www.md
notes/name.md
notes/nested/name.md

Nested paths are allowed only under notes/. Never pass an absolute path, hidden component, traversal, symlink, backslash, or locked-note path.

See TOOLS.md for exact arguments and return behavior.

Write Gate

Read tools are available by default. create_note, write_note, and append_to_daily_note appear only when the user enables MCP writes in Settings > AI & Agents. Write permission is global and can be revoked while a server is running.

If a write tool is absent or denied, explain the setting needed. Do not bypass the gate with direct files unless the user explicitly requests a filesystem fallback.

Not Exposed by MCP

Do not invent calls for delete, rename, move, trash, folder management, templates, graph data, locking, Forge management, import, or export. Use Moldavite's UI for those operations.