Docs

MCP server

Claude can connect with OAuth. Direct HTTP clients can still use a bearer API key.

https://www.mdfiles.io/api/mcp
Authorization: Bearer mdf_live_YOUR_KEY

Privacy settings

New Markdown files default to private, which is visible only to the owner and invited collaborators. Use link when anyone with the URL can view the file, or public for public files.

Claude connector

Add a custom connector in Claude Desktop or claude.ai and use this remote MCP server URL.

https://www.mdfiles.io/api/mcp

Example MCP configuration

{
  "mcpServers": {
    "mdfiles": {
      "url": "https://www.mdfiles.io/api/mcp",
      "headers": {
        "Authorization": "Bearer mdf_live_YOUR_KEY"
      }
    }
  }
}

List MCP tools

curl -X POST https://www.mdfiles.io/api/mcp \
  -H "Authorization: Bearer mdf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Create with MCP

Omit visibility to keep the new file private by default.

curl -X POST https://www.mdfiles.io/api/mcp \
  -H "Authorization: Bearer mdf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "mdfiles_create",
      "arguments": {
        "title": "Agent draft",
        "content_md": "# Draft"
      }
    }
  }'

Change privacy with MCP

curl -X POST https://www.mdfiles.io/api/mcp \
  -H "Authorization: Bearer mdf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "mdfiles_set_visibility",
      "arguments": {
        "id": "DOCUMENT_UUID",
        "visibility": "link"
      }
    }
  }'

List files with MCP

curl -X POST https://www.mdfiles.io/api/mcp \
  -H "Authorization: Bearer mdf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "mdfiles_list",
      "arguments": {}
    }
  }'

Read comments with MCP

curl -X POST https://www.mdfiles.io/api/mcp \
  -H "Authorization: Bearer mdf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
      "name": "mdfiles_list_comments",
      "arguments": {
        "id": "DOCUMENT_UUID",
        "status": "open"
      }
    }
  }'

Resolve comments with MCP

curl -X POST https://www.mdfiles.io/api/mcp \
  -H "Authorization: Bearer mdf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 6,
    "method": "tools/call",
    "params": {
      "name": "mdfiles_resolve_comment",
      "arguments": {
        "id": "DOCUMENT_UUID",
        "comment_id": "COMMENT_UUID"
      }
    }
  }'

List files

curl https://www.mdfiles.io/api/v1/files \
  -H "Authorization: Bearer mdf_live_YOUR_KEY"

Create a file

Omit visibility to create a private file, or send link or public explicitly.

curl -X POST https://www.mdfiles.io/api/v1/files \
  -H "Authorization: Bearer mdf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Agent brief",
    "content_md": "# Agent brief\n\n- [ ] Review this draft",
    "status": "in_progress",
    "external_id": "local-brief-123"
  }'

Change privacy with REST

curl -X PATCH https://www.mdfiles.io/api/v1/files/DOCUMENT_UUID \
  -H "Authorization: Bearer mdf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "visibility": "private"
  }'

Update or re-upload

curl -X POST https://www.mdfiles.io/api/v1/files/DOCUMENT_UUID/versions \
  -H "Authorization: Bearer mdf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content_md": "# Agent brief\n\nUpdated after user feedback.",
    "status": "review",
    "change_summary": "Addressed review notes"
  }'

Fetch latest Markdown

curl https://www.mdfiles.io/api/v1/files/DOCUMENT_UUID \
  -H "Authorization: Bearer mdf_live_YOUR_KEY"

Read review comments

curl "https://www.mdfiles.io/api/v1/files/DOCUMENT_UUID/comments?status=open" \
  -H "Authorization: Bearer mdf_live_YOUR_KEY"

Resolve a review comment

curl -X POST https://www.mdfiles.io/api/v1/files/DOCUMENT_UUID/comments/COMMENT_UUID/resolve \
  -H "Authorization: Bearer mdf_live_YOUR_KEY"

Upsert by external ID

curl -X POST https://www.mdfiles.io/api/v1/files \
  -H "Authorization: Bearer mdf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Agent brief",
    "external_id": "local-brief-123",
    "upsert": true,
    "content_md": "# New version"
  }'