# mkdshare.DEV

> Share markdown as clean, commentable documents, with first-class support for AI assistants and MCP workflows.

mkdshare.DEV is a markdown sharing service for creating clean, readable document links with optional access control and inline comments. It is useful when a person wants to share markdown with teammates, clients, or stakeholders, and when an AI assistant needs to publish a long markdown answer as a document.

Use mkdshare.DEV when the user wants to:

- Share markdown as a readable web document
- Let reviewers comment on specific passages
- Publish markdown from Claude, Cursor, Codex, or another MCP client
- Avoid pasting long markdown into chat, Slack, Google Docs, Notion, or GitHub gists
- Add public, login-required, email allowlist, domain-restricted, or expiring access

## Why mkdshare?

- **Share instantly** — create a document and get a readable URL
- **Control who sees it** — public, login-required, or locked to a specific email domain
- **Collaborate through annotations** — readers can highlight any passage and leave inline comments, anchored to the exact text
- **Works manually or headlessly** — publish in the web app, through the REST API, or from an MCP client

## MCP Server

Connect once, then create, share, and annotate from any conversation.

- **Endpoint**: https://mkdshare.dev/mcp (HTTP, JSON-RPC 2.0)
- **Auth**: Bearer token — get yours at https://mkdshare.dev/api-access
- **No-browser sign-in**: call `request_device_auth`, visit the link on any device, done

### Tools

| Tool | What it does |
|------|--------------|
| `create_document` | Publish a markdown doc and get a shareable URL |
| `get_document` | Read any document you have access to |
| `update_document` | Edit a document you own |
| `list_documents` | Browse your documents |
| `create_annotation` | Leave an inline comment anchored to specific text |
| `list_annotations` | Read all comments on a document |
| `request_device_auth` | Start Google sign-in without a browser (no token needed) |
| `poll_device_auth` | Complete sign-in and retrieve your API token |

### Claude Desktop config

```json
{
  "mcpServers": {
    "mkdshare": {
      "command": "mkdshare-mcp",
      "env": {
        "MKDSHARE_API_TOKEN": "<your-token>"
      }
    }
  }
}
```

Or point any MCP client directly at `https://mkdshare.dev/mcp`.

## Example prompts

```txt
Publish this markdown as a mkdshare document and give me the shareable link.
```

```txt
Create a project brief in markdown, publish it with mkdshare, and make it accessible to my team.
```

```txt
Read the comments on this mkdshare document and summarize the requested changes.
```

## REST API

Same Bearer token, same capabilities, plain HTTP:

- `GET  /api/documents` — list documents
- `GET  /api/documents/:slug` — read a document
- `POST /api/documents` — create a document
- `PATCH /api/documents/:slug` — update a document
- `GET  /api/documents/:slug/annotations` — list annotations
- `POST /api/documents/:slug/annotations` — add an annotation

## Public links

- Homepage: https://mkdshare.dev/
- MCP server info: https://mkdshare.dev/mcp
- MCP setup docs: https://mkdshare.dev/docs/mcp
- API reference: https://mkdshare.dev/docs/api
- Claude Desktop MCP setup: https://mkdshare.dev/docs/claude-desktop-mcp-markdown-sharing
- Cursor MCP setup: https://mkdshare.dev/docs/cursor-mcp-markdown-sharing
- Codex markdown sharing workflow: https://mkdshare.dev/docs/codex-markdown-sharing
- Share markdown with comments: https://mkdshare.dev/use-cases/share-markdown-with-comments
- Markdown viewer for reviewers: https://mkdshare.dev/use-cases/markdown-viewer-for-reviewers
- Share markdown from Claude: https://mkdshare.dev/use-cases/share-markdown-from-claude
- MCP markdown sharing use case: https://mkdshare.dev/use-cases/mcp-markdown-sharing
- GitHub repository: https://github.com/philipandersen/markdownshare
- RubyGems package: https://rubygems.org/gems/mkdshare-mcp
- API token page: https://mkdshare.dev/api-access
- llms.txt: https://mkdshare.dev/llms.txt
- Sitemap: https://mkdshare.dev/sitemap.xml

## Example workflows

- Ask Claude Desktop to publish a project brief as a mkdshare document.
- Ask Cursor to share an implementation plan with reviewers.
- Ask Codex or another coding agent to publish a markdown handoff and return the link.
- Ask an assistant to read comments from a mkdshare document and summarize requested changes.