Use mdedit with Claude Code

The mdedit MCP server gives Claude Code tools for working with your Markdown Documents. For collaborative documents, it keeps a live session open between tool calls so Claude appears in the editor presence UI while it works.

The API and MCP tools retain article in stable names and identifiers. The CLI uses mdedit document; mdedit article is a deprecated alias. All of these refer to the same document resource.

Hosted plugin (coming soon)

A self-contained mdedit plugin for Claude Code is on its way to the plugin marketplace. It connects to https://mcp.mdedit.ai/mcp with browser sign-in, so you will not need to create or paste an API key. Until it is listed, use the local setup below — this page will be updated with the marketplace install command once the plugin is available.

Local stdio and API-key setup

The published @mdedit/mcp-server package runs as a local process authenticated with a scoped API key.

Prerequisites

Node.js 20 or newer
Claude Code installed and signed in
A mdedit.ai API key
The workspace ID and document ID you want Claude to use

1. Create a scoped API key

Use a separate key for each agent integration. Create keys in Settings → Integrations → API Keys in the web app. The CLI can use, list, and revoke existing keys, but it does not create new keys.

A reviewer key should be scoped to read document content and create review feedback without directly changing prose:

Name: Claude reviewer
Scopes: articles:read,reviews:write

For direct document edits, create an editing key:

Name: Claude editor
Scopes: articles:write

articles:write includes document read access. Accepting a suggestion also requires articles:write because acceptance changes document content.

To let Claude publish explicitly confirmed public links, add the separate publishing scope:

Name: Claude publisher
Scopes: articles:read,articles:write,publishing:write

Ordinary editing keys cannot make documents public.

See API Keys for creation and rotation guidance.

2. Add the MCP server

All Claude Code MCP options must come before the server name. Replace the example key with the value shown when you created yours:

claude mcp add --transport stdio \
  --env MDEDIT_API_KEY=mdh_your_key \
  mdedit -- npx -y @mdedit/mcp-server

The default scope is local to the current project. To make mdedit available across projects, add --scope user before mdedit:

claude mcp add --transport stdio \
  --scope user \
  --env MDEDIT_API_KEY=mdh_your_key \
  mdedit -- npx -y @mdedit/mcp-server

The key is stored in your local Claude Code MCP configuration. Do not commit that configuration or use --scope project with a literal key. For shared project configuration, reference an environment variable instead of checking in a secret.

3. Verify the connection

claude mcp get mdedit
claude mcp list

Inside Claude Code, run /mcp. The mdedit server should report twenty tools.

Available tools

Tool	What it does
`list_workspaces`	Lists workspaces available to the authenticated mdedit user
`list_articles`	Lists documents in a workspace without returning every document body
`create_article`	Creates a durable Markdown Document with initial content
`read_article`	Reads saved Markdown content and metadata
`render_article`	Returns a concise fallback and exact mdedit resource link; hosts with MCP Apps UI can also render the rich document reader
`start_article_export`	Starts a Markdown, HTML, PDF, DOCX, or ZIP-with-assets export
`get_article_export_status`	Returns export progress and the completed download resource
`record_article_app_event`	Records bounded privacy-safe component telemetry without document content or visible identifiers
`publish_article`	Publishes or updates an explicitly confirmed Live or Snapshot `mded.it` link
`get_publish_status`	Reads the URL, stored mode, source revision/version, synchronization status, metadata, and view count
`unpublish_article`	Disables an explicitly confirmed public link
`edit_article`	Applies anchored live or conditional REST edits
`add_comment`	Adds an anchored review comment
`add_suggestion`	Proposes a replacement for human approval
`accept_suggestion`	Applies an explicitly accepted suggestion and closes it
`reject_suggestion`	Closes a suggestion without changing the document
`reply_to_thread`	Replies to an existing review thread
`resolve_thread`	Resolves a review thread
`list_review_threads`	Lists comments, highlights, and suggestions
`get_presence`	Lists people and agents in the live document

Example prompts

Ask Claude to identify a document naturally before changing it:

Show me my mdedit document named “Launch notes,” then suggest fixes for ambiguous sentences. Do not directly edit the prose.

For an editing key:

In my mdedit document “Launch notes,” replace the unique phrase “teh quick fox” with “the quick fox.” Report any edit conflicts and do not retry blindly.

For review follow-up:

In “Launch notes,” reply to the open citation comment with what you changed, then resolve it.

For public-link publishing:

Publish my mdedit document “Launch notes” at a public mded.it link. I confirm that anyone with the link may view it. Return the short URL.

Claude must send confirmPublic: true. A new link defaults to Live, so later durable edits update the same public URL automatically. Ask for mode: "snapshot" when you need a frozen artifact:

Publish a frozen Snapshot of “Launch notes.” I confirm that anyone with the link may view it. Return the short URL, source version, and sync status.

For an existing link, omitting mode preserves the stored mode. Supplying mode: "live" or mode: "snapshot" switches it deliberately without replacing the URL. get_publish_status reports the last good source version and syncStatus; if a Live sync fails, the existing public URL remains usable but may be stale.

Links created before Live mode remain Snapshots until explicitly switched.

Live sessions and REST fallback

When collaboration is enabled, mdedit keeps one live document session across Claude’s tool calls and closes it after about 60 seconds of inactivity. This provides current content, conflict reporting, and presence.

For a non-collaborative document, editing uses the conditional REST fallback. Content remains protected by revision/hash checks, but get_presence returns an empty list because there is no live room.

Troubleshooting

Server does not connect

Confirm Node.js is version 20 or newer.
Run claude mcp get mdedit and check that the command is npx -y @mdedit/mcp-server.
Increase Claude Code’s startup timeout temporarily with MCP_TIMEOUT=60000 claude.

Authentication fails

Revoke the affected key and create a new one if it may have been exposed.
Confirm the key begins with mdh_ and is passed as MDEDIT_API_KEY.
Confirm the key owner still has access to the workspace and document.

A tool is denied

Reviewer keys need articles:read,reviews:write.
Direct edits and suggestion acceptance need articles:write.
Public-link status needs publishing:read; publishing and unpublishing need publishing:write.
Scoped keys are fail-closed: missing scopes are rejected rather than silently broadened.

An edit reports conflicts

The edit may already have landed. Read the document again, inspect the reported overlapping ranges, and decide whether a new anchored operation is still necessary.

CLI + agent skills alternative

Use MCP when Claude should keep a live document session across several tool calls. For shell scripts or agents that work one command at a time, install the CLI and its focused CLI-backed skills instead:

npm install -g mdedit-cli
mdedit config login --api-key mdh_your_key
mdedit skill install --target claude --via cli

The five installed skills cover saving, finding, safely revising, reviewing, and explicitly publishing documents. They do not start an MCP server; each CLI command opens only the session it needs. See the skill catalog and installation guide for supported targets and commands.

Other agents

The server uses standard MCP stdio transport, so other MCP clients can run the same package with MDEDIT_API_KEY in its environment. For shell-oriented agents, see the mdedit CLI guide.

See MCP authentication for the hosted endpoint, host-by-host OAuth support, shared local OAuth profiles, API-key compatibility, scopes, and revocation behavior.

MCP authentication Agent webhooks