AI-powered IDE workflows with markdown

Why markdown is the output format of AI coding

Every AI coding assistant thinks in markdown. Implementation plans, architecture notes, code reviews, migration checklists, incident timelines — when you ask Cursor or Claude Code to write something down, what comes out is a .md file. The format is not an accident: markdown survives copy-paste, renders anywhere, diffs cleanly in git, and both humans and models parse it without ambiguity.

The gap is distribution. The artifact your assistant just produced lives in your working tree or your chat scroll-back. The person who needs it — a reviewer, a PM, an on-call engineer — is in Slack or Linear or a PR thread. The usual options all lose something: pasting into Slack mangles tables and code fences, committing to the repo is overkill for a document with a two-week lifespan, and Notion means leaving the terminal and reformatting by hand.

A markdown-native share link fixes this: the document renders with syntax highlighting, tables, and mermaid diagrams at a URL anyone can open, and your assistant can publish it without you leaving the editor. That is what the Docs MD MCP server does.

What your assistant can do once connected

• share_markdown — publish any markdown as a public URL. Choose expiry: 1 day, 7 days, 30 days, or never. Returns the share link, a raw-markdown link, and a private edit token.
• update_share — replace the content at the same URL using the edit token. The link you already posted in Slack keeps working and shows the new version.
• delete_share — remove a share early when the document is no longer needed.

No account, no API key. The edit token returned at creation is the only credential, and it scopes to that single document.

Setup by editor

Cursor

Add the server to ~/.cursor/mcp.json (or per-project in .cursor/mcp.json), then restart Cursor:

{
  "mcpServers": {
    "md-share": {
      "url": "https://docs-md.com/api/mcp"
    }
  }
}

Claude Code

One command in your terminal:

claude mcp add --transport http md-share https://docs-md.com/api/mcp

VS Code (GitHub Copilot)

Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "md-share": {
      "type": "http",
      "url": "https://docs-md.com/api/mcp"
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "md-share": {
      "serverUrl": "https://docs-md.com/api/mcp"
    }
  }
}

Zed

Add a context server in settings.json:

{
  "context_servers": {
    "md-share": {
      "source": "custom",
      "url": "https://docs-md.com/api/mcp"
    }
  }
}

Any MCP client that speaks streamable HTTP works the same way — the endpoint is always https://docs-md.com/api/mcp.

Four workflows that earn their keep

1. Design review without the repo dance

Your assistant drafts an implementation plan before touching code. Instead of committing a PLAN.md to the repo or pasting 200 lines into Slack:

"Share this plan as markdown with 7-day expiry and give me the link."

Reviewers get a rendered document with a table of contents and highlighted code. When the review lands changes, ask the assistant to update_share — the same link now shows v2, so the Slack thread never points at a stale doc.

2. Incident postmortems on a deadline

During an incident, the assistant assembles a timeline from logs and git history. Share it with a 30-day expiry for the review meeting; once the formal postmortem lands in your wiki, the working document quietly deletes itself. Ephemeral by default is a feature here — no stale incident docs floating around with half-correct conclusions.

3. Handoff between agents and humans

Long-running agents produce state: what was tried, what failed, what is left. A share link is the cheapest durable handoff — the agent publishes its status document and posts one URL, instead of dumping its context into a channel. The next agent (or human) reads the raw endpoint (/raw/id) to pick up exactly where things stood.

4. Permanent docs linked from READMEs

Some documents deserve to live forever: setup guides, API references for internal tools, onboarding checklists. Share with expiry: never and link them from your README. Permanent shares keep a stable URL and render mermaid diagrams — useful for architecture docs that outgrow ASCII art.

Practices that make shared docs get read

• One decision per document. A share link with a focused question gets read in two minutes; a kitchen-sink document gets skimmed and forgotten.
• Front-load the ask. Put the decision needed and the deadline in the first paragraph — the rest is supporting evidence.
• Match expiry to the document's half-life. Review artifacts: 7 days. Working documents: 30 days. Reference material: never. Defaulting everything to permanent recreates the stale-wiki problem you were escaping.
• Keep the edit token. Your assistant receives it when publishing — ask it to note the token in the conversation or a local file, so later sessions can update the same link instead of minting a new one.
• Use mermaid for anything with arrows. Sequence diagrams and flowcharts in mermaid fences render as real diagrams in the shared view.

FAQ