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.

MCP works on both self-hosted and managed Cloud. The MCP server is built into the DocPlatform binary — docplatform serve mounts it at /mcp automatically, so the managed DocPlatform Cloud host, app.valoryx.dev, already exposes it: AI tools can connect over Streamable HTTP using an API key, no setup required. Self-hosted deployments (the Community Edition, or any cloud-edition binary you run yourself) additionally expose the local stdio transport (docplatform mcp), which has no Cloud equivalent since it requires running the binary on your own machine.

Prerequisites

• DocPlatform running (binary, Docker, or Fly.io) — or a DocPlatform Cloud workspace, which needs no setup of your own
• 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"]
    }
  }
}

DocPlatform Cloud

Cloud workspaces already run docplatform serve, so /mcp is live with no setup beyond creating an API key. Configure your MCP client to connect via Streamable HTTP at https://app.valoryx.dev/mcp with a Bearer token (dp_live_...).

Remote HTTP transport (self-hosted)

Self-hosted instances running docplatform serve already expose /mcp on the main port — connect via Streamable HTTP at http://your-server:PORT/mcp with a Bearer token (dp_live_...), no extra step needed.

To run MCP as its own standalone process instead — on its own port, independent of the main app — start it directly:

docplatform mcp-server --addr :8081

Then connect at http://your-server:8081/mcp the same way.

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

• On docplatform serve, /mcp listens on the main app port — check that port’s firewall rules. On the standalone docplatform mcp-server, the default listen address is :8081
• For CORS issues on the standalone server, 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: