MCP Server Setup

Connect AI agents like Claude to MarkDocs using the Model Context Protocol (MCP). Your AI can create documents, leave comments, make suggestions, and review edit history.

What is MCP?

The Model Context Protocol is an open standard for connecting AI models to external tools and data sources. MarkDocs implements an MCP server that exposes 13 tools and 2 resources, allowing any MCP-compatible AI agent to interact with your documents.

Quick Setup

1. Install the CLI

curl -fsSL https://markdocs.sh/install.sh | bash

2. Get your API key

Go to Settings in your MarkDocs dashboard and create an API key. You'll need this for the MCP server configuration.

3. Configure Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "markdocs": {
      "command": "markdocs-mcp",
      "env": {
        "MARKDOCS_API_KEY": "mdk_your_key_here",
        "MARKDOCS_URL": "https://markdocs.sh"
      }
    }
  }
}

4. Configure Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "markdocs": {
      "command": "markdocs-mcp",
      "env": {
        "MARKDOCS_API_KEY": "mdk_your_key_here",
        "MARKDOCS_URL": "https://markdocs.sh"
      }
    }
  }
}

5. Other MCP clients

Any MCP-compatible client can connect using stdio transport:

# Run the MCP server directly
MARKDOCS_API_KEY=mdk_your_key MARKDOCS_URL=https://markdocs.sh markdocs mcp

Available Tools

Tool	Description
list_documents	List all documents
create_document	Create a new document with title and optional content
get_document	Get document details by ID
delete_document	Soft-delete a document
list_comments	List comments with optional resolved filter
add_comment	Add an inline comment at a position range
resolve_comment	Mark a comment as resolved
delete_comment	Delete a comment
list_suggestions	List suggestions with optional status filter
add_suggestion	Propose a text replacement
accept_suggestion	Accept a pending suggestion
reject_suggestion	Reject a pending suggestion
get_history	Get edit history for a document

Available Resources

URI	Description
markdocs://documents	List all documents as JSON
markdocs://documents/{id}	Get a specific document as JSON

Architecture

┌─────────────────┐     stdio      ┌─────────────────┐
│  AI Agent       │ ◄────────────► │  MCP Server     │
│  (Claude, etc.) │                │  (markdocs-mcp) │
└─────────────────┘                └────────┬────────┘
                                            │ HTTPS + API Key
                                   ┌────────▼────────┐
                                   │  MarkDocs API   │
                                   │  markdocs.sh    │
                                   └────────┬────────┘
                                            │ Prisma
                                   ┌────────▼────────┐
                                   │  PostgreSQL     │
                                   │  (Supabase)     │
                                   └─────────────────┘