MCP Server — AI Integration Guide

DocPlatform includes a built-in Model Context Protocol (MCP) server that lets AI assistants read, write, search, and manage your documentation directly. Instead of copy-pasting content into chat windows, your AI tools work with your docs natively.

Prerequisites

• DocPlatform running (binary, Docker, or Fly.io)
• An API key (create one in Workspace Settings → API Keys)

Quick start

1. Create an API key

In your DocPlatform instance, go to Workspace Settings → API Keys → Create Key. Copy the key — it starts with dp_live_ and is shown only once.

2. Choose your transport

DocPlatform offers two MCP transports:

3. Configure your AI tool

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "docplatform": {
      "command": "docplatform",
      "args": ["mcp", "--workspace", "my-docs", "--api-key", "dp_live_abc123"]
    }
  }
}

Claude Code

claude mcp add docplatform -- docplatform mcp --workspace my-docs --api-key dp_live_abc123

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "docplatform": {
      "command": "docplatform",
      "args": ["mcp", "--workspace", "my-docs", "--api-key", "dp_live_abc123"]
    }
  }
}

VS Code (GitHub Copilot)

Add to .vscode/mcp.json:

{
  "servers": {
    "docplatform": {
      "command": "docplatform",
      "args": ["mcp", "--workspace", "my-docs", "--api-key", "dp_live_abc123"]
    }
  }
}

Remote HTTP transport

For cloud-hosted DocPlatform or multi-workspace access, start the HTTP server:

docplatform mcp-server --addr :8081

Then configure your MCP client to connect via Streamable HTTP at http://your-server:8081/mcp with a Bearer token (dp_live_...).

Available tools (26)

The MCP server exposes 26 tools across 10 categories.

Content (6 tools)

How write_page works (smart upsert)

The write_page tool provides a single “just write” operation for AI agent convenience:

1. Page doesn’t exist → creates it automatically
2. Page exists → reads the current content hash, then updates with optimistic locking

AI agents never need to check if a page exists before writing. If you need explicit concurrency control, use update_page instead (which requires last_known_hash and fails on conflict).

Discovery (5 tools)

The get_context tool is designed for RAG workflows — it returns everything an AI needs to understand a page in context, including its parent, siblings, wikilink targets, and workspace metadata, in a single call.

The get_manifest tool gives AI agents a complete overview of the workspace structure at a glance, including link relationships (links_to / linked_from).

Quality (2 tools)

Settings (2 tools)

Management (3 tools)

Versioning (2 tools)

Export (1 tool)

AI writing (1 tool)

Requires an AI provider configured on the server (Anthropic or OpenAI).

Activity (1 tool)

Comments (2 tools)

Sync (1 tool, conditional)

This tool proxies to the REST conflict-resolution endpoint and requires the Editor role. It is registered by default — the server URL falls back to http://localhost:3000 when DOCPLATFORM_SERVER_URL is unset; set that variable when the API is reachable at a different address. Triggering a sync itself is REST-only (POST /api/v1/workspaces/:id/sync); there is no trigger_sync MCP tool.

Authentication

API key scopes

API keys support five scopes — read, write, delete, admin, and admin:read (see Authentication for the full model). The three content scopes map to MCP tools as follows:

In addition to scopes, every tool call is checked against your workspace role — a write-scoped key held by a Viewer still can’t write.

By default, new API keys have all three content scopes (read, write, delete). You can restrict scope when creating the key.

Key format

API keys use the dp_live_ prefix:

dp_live_a1b2c3d4e5f6...

Keys are hashed with HMAC before storage — the raw key is shown only once at creation.

Environment variable

Instead of passing --api-key on the command line, set:

export DOCPLATFORM_API_KEY=dp_live_abc123

Security

• Hashed storage: API keys are never stored in plaintext. Only the HMAC hash is persisted.
• Rate limited: Each key is rate-limited based on the organization’s plan.
• Workspace-scoped: Keys can be scoped to a specific workspace (recommended) or org-wide.
• Revocable: Delete a key immediately from Workspace Settings → API Keys.
• Rotatable: Rotate a key without changing its ID or scopes via POST /api/v1/api-keys/:id/rotate.

Rate limits (MCP)

Rate limit headers are included on HTTP transport responses:

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 28
X-RateLimit-Reset: 1712847600

Troubleshooting

“invalid API key”

• Verify the key starts with dp_live_
• Regenerate the key from Workspace Settings — the raw key is shown only once
• Check that the key hasn’t been revoked or expired

MCP not connecting

• Quit your AI tool completely and restart — MCP connections are established at launch
• Verify the docplatform binary is in your PATH
• Check that the DocPlatform server is running (docplatform serve)

“workspace not found”

• Use the workspace slug (not the display name or ULID)
• Verify the workspace exists: docplatform mcp --workspace <slug> --api-key <key> should start without error

Permission denied

• Check the key’s scopes match the operation (e.g., write scope needed for write_page)
• Verify the key is scoped to the correct workspace

HTTP transport issues

• Default listen address is :8081 — check firewall rules
• For CORS issues, pass --cors-origins https://your-domain.com
• Verify the Bearer token is sent in the Authorization header

Tool returns “service not available”

Some tools depend on optional services: