Use mdedit with Claude Code

The API and tools use article in command names and identifiers. In these docs, an article is the same thing as a document.

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.

Hosted plugin release candidate

The self-contained Claude Code plugin is currently a release candidate and is not yet available from the public claude-community marketplace. It connects to https://mcp.mdedit.ai/mcp with browser OAuth, so users do not create or paste an API key after launch. OAuth sign-in is not yet enabled for Claude Code in production; the corrected scopes, client admission, and live verification must complete before this candidate is presented as usable.

Repository contributors can validate and load the exact candidate:

claude plugin validate --strict ./plugins/claude-code/mdedit
claude --plugin-dir ./plugins/claude-code/mdedit

The plugin starts disabled because enabling it connects Claude Code to an external service. The commands above are for package validation and inspection, not production sign-in. After the live gate passes, users will enable mdedit in /plugin and sign in through /mcp. The public marketplace install command will be added here only after Anthropic approves and syncs the pinned candidate.

Local stdio and API-key alternative

The published @mdedit/mcp-server package remains available for users who prefer a local process or 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 fourteen 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
`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
`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.

For public-link publishing:

Publish document article_456 in workspace ws_123 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 document article_456. 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 + 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 document (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.

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, the release-gated OAuth matrix, shared local OAuth profiles, API-key compatibility, scopes, and revocation behavior.

MCP authentication Agent webhooks