Update the Same Markdown Document Through MCP Tools

read_file
{ "path": "release-notes/launch.md" }

Connect a client and choose the workspace

EDTR.md exposes its remote MCP endpoint at https://edtr.md/api/mcp. Use the AI connection guide for supported transport, OAuth authorization, and client configuration. Your AI provider may have its own account, plan, or administrator requirements; those are separate from your EDTR.md account.

An authorized client can call list_workspaces to discover the workspaces available to it and the user’s role in each. Owners and editors can write. Viewers have read-only access. Connecting an assistant does not bypass those permissions.

When no workspace is specified, document tools use the dedicated Claude workspace. Despite the name, it is the default destination for connected clients, not only Claude. Pass the optional workspace argument when you mean another accessible workspace, and keep using that same workspace for the read and write operations.

Find the path before editing

Ask the assistant to call list_files or search_files, then read_file. A folder path and filename tell the server which document to change. A topic mentioned in conversation does not provide the same certainty.

For example, an existing document might have the path:

release-notes/launch.md

An illustrative read_file argument object is:

{
  "path": "release-notes/launch.md"
}

These examples are tool arguments, not shell commands or raw HTTP requests. The MCP client handles invoking the named tool after authorization. If the file is in a selected workspace, include that workspace in each call too.

Reading first serves two purposes. It confirms that the path exists, and it gives the assistant the latest content to revise. A draft remembered from an earlier message may be out of date if you have also edited the file in the browser.

Use edit_file for a small change

For a sentence, label, or short paragraph, edit_file replaces one exact occurrence of text:

{
  "path": "release-notes/launch.md",
  "old_text": "Search is ready for review.",
  "new_text": "Search is ready to ship."
}

The old text must match exactly once. If it does not occur, or occurs in several places, the edit fails. Read the file again and include enough surrounding text to identify the intended passage. Do not keep retrying a guessed snippet.

This is a good fit when most of the document should stay untouched. It also makes the requested change easier to review than a full replacement body. The tool’s success response is still worth following with a read when the edit affects a published guide or other important document.

Use target_path for a full revision

For a larger rewrite, pass the existing path to save_document along with the complete replacement Markdown:

{
  "session_name": "release-notes",
  "title": "Launch",
  "target_path": "release-notes/launch.md",
  "content": "# Launch\n\nSearch is ready to ship.\n\n- Search by file name\n- Open a result with Enter"
}

With target_path, the path selects the existing file. The session name, title, and subfolder do not redirect that write. A missing path returns an error rather than creating a replacement somewhere else.

The content field is the whole document, not a patch. Sending only the new paragraph would replace the file with that paragraph. Use edit_file when you intend to change a passage while leaving the rest in place.

A large rewrite does not automatically create a -v2 file. The same target is updated in place. Identical content produces a no-change result. Changed content is saved with the replaced text recorded in history; access to version history in the editor follows the workspace owner’s plan. Keeping a separate Markdown backup is still sensible before a substantial revision.

Understand a needs_target result

Without target_path, save_document looks for a filename matching the document title in the destination folder. A matching title updates that file, even when the new content is very different. In a new or empty folder, it can create the document.

If the folder already contains documents and the title matches none of them, the save logic returns needs_target. The MCP response explains that nothing was saved and lists candidate paths. Similarity helps order those candidates; it does not authorize overwriting the closest match.

Situation	What to do
Revising a listed document	Read it, then retry with its target_path
Writing a separate document	Confirm the destination and use create_new: true
Path is missing	List files again and correct the path
Replacement text is ambiguous	Read the file and use a more specific snippet

Use create_new only when you actually want another document. It is not an override for saving a new version of an existing file, and a conflicting title can still be rejected. Keep the same title for follow-up edits, or pass the exact path when the title changes.

Verify the saved result before publishing

Look at the tool response. “Created,” “Updated,” “No changes,” and “Nothing saved” mean different things. Then read the returned path and compare the relevant section with your request. Do not interpret a conversational “done” as evidence that a file was written.

Saving through MCP changes the workspace document. It does not automatically update a public snapshot. If the document is already published, review the revision and use the publishing update action when it is ready. The Markdown publishing guide explains that separate step.

For a broader drafting process, see the AI Markdown workflow. To try a controlled edit, open EDTR.md, create a short note, connect your client, and ask it to read and revise that exact file. Start with one sentence so the result is easy to check.