API & Agentic

Install the mdtidy skill into your agent, connect over MCP, or call the API directly. Pick the path that fits your workflow.

Install the mdtidy skill

Teach your agent to clean, convert, save, and share Markdown — across 20+ tools. Install with skills.sh, or as a Claude Code plugin.

Get an API key

Create a key so your client can authenticate.

Install the skill

Jump to the one-line skills.sh command.

Claude plugin

Jump to the Claude Code plugin steps.

Any agent — skills.sh

One command installs the skill into your tool of choice. It uses the mdtidy MCP tools when present, otherwise the REST API — so it works with or without MCP.

npx skills add mdtidy/mdtidy-agents

Works in

Claude Code
Cursor
Codex
GitHub Copilot
Windsurf
Gemini
Cline
AMP
Antigravity
ClawdBot
Droid
Goose
Kilo
Kiro CLI
Nous Research
OpenCode
Roo
Trae
VS Code
Zed

Claude Code — plugin

The plugin bundles the skill and the MCP server (all 12 tools), pre-wired — no JSON to edit.

1.Add the marketplace

/plugin marketplace add mdtidy/mdtidy-agents

2.Install the plugin

/plugin install mdtidy@mdtidy

3.Activate it

/reload-plugins

Loads the mdtidy tools into the session — they aren't live until you reload (or restart Claude Code).

4.Set your API key

export MDTIDY_API_KEY=mt_live_…

Export it in the shell before you launch Claude Code, so the bundled server can authenticate.

View the plugin source

Either way, you'll need an API key. Create one and set MDTIDY_API_KEY (or paste it when the skill asks).

Connect mdtidy to your agent

One package, two ways in: a hosted endpoint or a local npx server. Works in Claude, Cursor, Codex, and any MCP client. Authenticate with the same X-API-KEY as the REST API.

Get an API key

Create a key so your client can authenticate.

@mdtidy/mcp

The published MCP server on npm.

Source & tool docs

Open-source server, client, and full tool reference.

Hosted endpoint

Nothing to install — point your client at https://www.mdtidy.com/mcp with an X-API-KEY header.

claude mcp add --transport http mdtidy https://www.mdtidy.com/mcp \
  --header "X-API-KEY: mt_live_…"

Local server (npx)

Run it on your machine. Reads MDTIDY_API_KEY; override the origin with MDTIDY_BASE_URL.

claude mcp add mdtidy \
  --env MDTIDY_API_KEY=mt_live_… \
  -- npx -y @mdtidy/mcp

Tools

The 12 tools your agent can call. Reads are free; credits apply only to renders, saves, and shares.

Tool	Cost	Description
`tidy_markdown`	1 credit	Clean & repair Markdown and render it to HTML, text, PDF, DOCX, or PNG.
`save_document`	1 / free	One-step upsert — find or create a project and save (or update) a document.
`save_file`	1 credit	First-save a Markdown file into a known project (idempotent).
`update_file`	Free	Autosave, rename, or move a file — If-Match for safe concurrent edits.
`create_project`	Free	Create a workspace project to hold files.
`list_projects`	Free	List your projects — mine, shared, or archived.
`get_project`	Free	Fetch a project with its folders and files.
`get_file`	Free	Read a saved file's Markdown plus its version/ETag.
`check_usage`	Free	Your credit balance and recent API calls.
`get_entitlement`	Free	Your plan and workspace gates (can save / can share).
`get_project_share`	Free	A project's current share state and public URL.
`share_project_public`	1 credit	Turn on a project's public link (mdtidy.com/p/…).

Example prompts

Once connected, drop one of these into your agent.

“Clean this Markdown with mdtidy and return only the final Markdown.”
“Use mdtidy to normalize this document before summarizing it.”

See all example prompts

No MCP client? The mdtidy skill works in any agent — see the Skills tab.

Call mdtidy directly

One endpoint, JSON in and JSON out. Authenticate with the X-API-KEY header.

Get an API key

Create a key on your account so your scripts can authenticate.

Full API documentation

Quickstart, request/response shapes, and error semantics.

OpenAPI spec

Machine-readable schema for SDKs, Swagger UI, and codegen.

Endpoint

The customer-facing surface of the API.

Method & path: POST /api/v1/convert
Auth: X-API-KEY: mt_live_…
Rate limit: 60 requests / minute, per key
Max payload: 200 KB of Markdown per call
Credit cost: 1 credit per successful call (4xx/5xx is free)

Quickstart

Render a Markdown document as a PDF. Replace $MARKDOWN_TIDY_KEY / MARKDOWN_TIDY_KEY with a key from your account page.

curl -X POST https://mdtidy.com/api/v1/convert \
  -H "X-API-KEY: $MARKDOWN_TIDY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "markdown": "# Hello\n\nWorld.",
    "format": "pdf"
  }' \
  | jq -r .outputBase64 | base64 -d > out.pdf

Response

What you get back — status codes, headers, and the body shape for both successes and errors.

Status codes

200: Successful conversion. 1 credit charged.
400: invalid_request — missing or malformed body, unknown format, etc.
401: missing_api_key / invalid_api_key — bad or absent X-API-KEY.
402: out_of_credits — your wallet has no credits left this period.
413: payload_too_large — Markdown body exceeds 200 KB.
429: rate_limited — more than 60 requests / minute on this key.
500: internal_error — pipeline failure. Credit is refunded automatically.

Headers

X-Request-ID: Unique ID for the call. Returned on every response — quote it when you contact support.
X-Credits-Remaining: Wallet balance after this call. Sent on 200 and 402.
RateLimit-Limit: Per-key ceiling (60 / min). Sent on 429.
RateLimit-Remaining: Calls left in the current window. Sent on 429.
RateLimit-Reset: Unix epoch when the window resets. Sent on 429.
Retry-After: Seconds to wait before retrying. Sent on 429.

Body — success (200)

For html / text, output is a string. For pdf / docx / png, the body is base64-encoded in outputBase64.

{
  "format": "pdf",
  "contentType": "application/pdf",
  "byteSize": 12345,
  "designSystem": "minimal-clean",
  "outputBase64": "JVBERi0xLjQK…",
  "warnings": [
    { "rule": "table_pipe_balance", "fixes": 2 }
  ],
  "creditsCharged": 1,
  "creditsRemaining": 1999,
  "requestId": "f0c7…"
}

Body — error

Every 4xx/5xx shares the same envelope. The requestId matches the X-Request-ID header.

{
  "error": {
    "code": "invalid_request",
    "message": "format: required",
    "requestId": "f0c7…"
  }
}