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.

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. A reviewer can read document content and create review feedback without directly changing prose:

mdedit apikey create \
  --name "Claude reviewer" \
  --scopes articles:read,reviews:write

For direct document edits, create an editing key:

mdedit apikey create \
  --name "Claude editor" \
  --scopes articles:write

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

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 nine tools.

Available tools

Tool	What it does
`list_articles`	Lists documents in a workspace without returning every document body
`read_article`	Reads saved Markdown content and metadata
`edit_article`	Applies anchored live or conditional REST edits
`add_comment`	Adds an anchored review comment
`add_suggestion`	Proposes a replacement for human approval
`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 before changing it:

List the documents in workspace ws_123. Read the document named “Launch notes,” then suggest fixes for ambiguous sentences. Do not directly edit the prose.

For an editing key:

In workspace ws_123, replace the unique phrase “teh quick fox” with “the quick fox” in document article_456. Report any edit conflicts and do not retry blindly.

For review follow-up:

List open review threads on document article_456, reply to the citation comment with what you changed, then resolve that thread.

Live sessions and REST fallback

When collaboration is enabled, mdedit holds one live article session across Claude’s tool calls and closes it after about 60 seconds of inactivity. This provides current CRDT 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.
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 + skill document 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 bundled agent reference instead:

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

The installed skill teaches Claude the JSON-safe article, review, suggestion, and API-key commands. It does not start an MCP server; each CLI command opens only the session it needs. See the CLI guide for all supported targets and commands.

Maintainer launch gate

Before publishing a release, run the repository smoke test against a dedicated test workspace. It seeds a uniquely named article, enables live collaboration, asks Claude Code to exercise the MCP read, review, resolve, and presence flow, verifies the result through the API, and deletes the fixture.

MDEDIT_API_KEY=mdh_launch_gate_key \
MDEDIT_SMOKE_WORKSPACE_ID=workspace_id \
yarn workspace @mdedit/mcp-server smoke:claude

The launch-gate key needs articles:write,reviews:write, access to that workspace, and the collaboration entitlement. Never point the gate at a personal workspace.

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.

AI Agents Agent webhooks