MCP authentication

mdedit keeps two authentication paths:

Scoped API keys work with local stdio, hosted MCP clients that can send X-API-Key, CI, and headless automation.
Browser OAuth signs you in through the browser using authorization code with PKCE. It is supported only for verified hosts and is not universal MCP OAuth.

Browser OAuth is rolling out host by host: a host is enabled only after its complete sign-in and document workflow has been verified end to end. Until a host is listed as supported, use a scoped API key with it.

Current host support

Host	Local stdio with API key	Hosted API key	Hosted browser OAuth
mdedit CLI	Not an MCP host	Not an MCP host	Supported
Claude Code	Supported	Supported when custom headers are available	Not yet available
Gemini CLI	Supported	Supported when custom headers are available	Not yet available
Cursor	Supported	Supported when custom headers are available	Not yet available
ChatGPT	Not applicable	Depends on custom-header support	Not yet available
Perplexity	Not applicable	Depends on custom-header support	Not yet available

Local stdio with a scoped API key

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

API keys are a first-class path, not a deprecated fallback. Create separate, least-privilege keys for each agent and keep literal keys out of shared project configuration.

Local stdio with the shared OAuth profile

Once browser OAuth is enabled for your account:

mdedit auth login
claude mcp add --transport stdio mdedit -- npx -y @mdedit/mcp-server

The MCP package reads the same OS-keychain profile directly. It does not spawn the mdedit executable. Set MDEDIT_PROFILE=work to select a named profile.

Generic hosted API-key setup

Clients that support Streamable HTTP and custom headers can connect to:

https://mcp.mdedit.ai/mcp

Send:

X-API-Key: mdh_your_key

Browser-origin requests and caller-supplied session IDs are rejected. Hosted MCP is stateless, so clients must not depend on load-balancer stickiness.

Scopes

Common least-privilege sets:

Review only: articles:read,reviews:write
Direct editing: articles:write
Read publication state: publishing:read
Explicit publish and unpublish: publishing:write

Write scopes satisfy the corresponding read operation. Missing scopes fail closed and MCP tools return an incremental authorization challenge.

Public-link modes

publish_article always requires confirmPublic: true because it changes public visibility. For a new link, omitting mode creates a Live link: later durable edits update the same URL. Pass mode: "snapshot" for a frozen artifact.

For an existing link, omit mode to preserve its stored setting, or pass "live" / "snapshot" to switch deliberately. get_publish_status returns the stable URL, mode, source revision/version, last successful sync, and sync status. A failed Live sync leaves the last good public content available.

Existing links created before Live mode are Snapshots until explicitly changed.

Revocation

Browser OAuth sessions cannot be revoked one host at a time. Settings offers Revoke all sessions, which signs out all mdedit web and OAuth refresh sessions for the account. It does not revoke API keys.

Already-issued access tokens may remain usable for up to 15 minutes. After that bound, refresh and new MCP or collaboration connections fail until the user signs in again.

Troubleshooting

A callback mismatch means the host is not yet supported for browser OAuth. Use a scoped API key with that host instead.
invalid_client means the host is not yet supported for browser OAuth or used the wrong public client ID.
insufficient_scope means the tool needs an additional listed permission.
Headless machines should use a scoped API key. --no-browser still requires a browser on the same machine and is not device flow.
Unknown OAuth clients are rejected. Use an API key if the host supports custom headers.

AI Agents Use mdedit with Claude Code