@mdedit/mcp-server

Use mdedit.ai Markdown Documents from Claude Code and other Model Context Protocol clients. The server runs locally over stdio and authenticates with a scoped API key. It can also share an OS-keychain OAuth profile created by mdedit auth login in environments where the release-gated OAuth endpoint has been enabled.

Claude Code setup

The generally available setup uses a scoped API key:

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

Use --scope user before mdedit if you want the server available in every project. Verify the connection with claude mcp get mdedit or /mcp inside Claude Code.

When OAuth is enabled for your environment, mdedit auth login may be used before the same claude mcp add command without the API-key environment value.

Reviewer agents normally use articles:read,reviews:write. Editing agents need articles:write. Accepting a suggestion also requires articles:write because it changes document content. Agents that publish public links need publishing:write; publication status only needs publishing:read.

Tools

• list_articles
• create_article
• read_article
• publish_article
• get_publish_status
• unpublish_article
• edit_article
• add_comment
• add_suggestion
• reply_to_thread
• resolve_thread
• list_review_threads
• get_presence

publish_article and unpublish_article require explicit confirmation fields in their tool inputs. A published document is readable by anyone with its mded.it link.

For a new link, publish_article defaults to mode: "live". Later durable edits automatically update a Live link at the same stable URL. Pass mode: "snapshot" for a frozen artifact. When updating an existing link, omit mode to preserve the stored mode, or pass "live" / "snapshot" to switch deliberately.

publish_article and get_publish_status return the stored mode, source revision/version, last successful sync time, and synchronization status. A failed Live sync leaves the last good public content and URL available; inspect syncStatus and syncError before claiming the public page is current.

Local stdio keeps one live collaborative session open across tool calls. The hosted HTTP adapter uses operation-scoped sessions and does not depend on process-local state or load-balancer stickiness. Non-collaborative documents use the REST fallback and report an empty live-presence list.

Environment

• MDEDIT_API_KEY - optional scoped API key override; takes precedence over OAuth
• MDEDIT_PROFILE - optional shared OAuth profile name; defaults to the active CLI profile
• MDEDIT_API_URL — optional API host override
• MDEDIT_AGENT_NAME — optional awareness display hint; defaults to mdedit-mcp
• MDEDIT_MCP_IDLE_TIMEOUT_MS — optional positive idle timeout in milliseconds

Never commit API keys to a repository or place them in shared project MCP configuration.

Maintainer launch gate

The repository includes a manual Claude Code smoke test. It creates a uniquely named fixture article in the selected test workspace, enables collaboration, exercises list/read/comment/list/resolve/presence through MCP, verifies the resolved comment through the review 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

Use a test workspace and a key with articles:write,reviews:write. The key owner must have access to the workspace and the collaboration entitlement.