MCP Protocol Reference

MDER provides a Model Context Protocol (MCP) server that gives AI agents direct access to document operations. Agents can create, update, publish, and manage documents using structured tool calls — no HTTP knowledge required.

Setup

VS Code / GitHub Copilot

Add this to your .vscode/mcp.json file:

.vscode/mcp.jsonjson

{
  "servers": {
    "mder": {
      "command": "npx",
      "args": ["-y", "@mder/mcp"],
      "env": {
        "MDER_API_KEY": "mder_YOUR_API_KEY",
        "MDER_API_URL": "https://api.mder.pro"
      }
    }
  }
}

Claude Desktop

Add this to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

claude_desktop_config.jsonjson

{
  "mcpServers": {
    "mder": {
      "command": "npx",
      "args": ["-y", "@mder/mcp"],
      "env": {
        "MDER_API_KEY": "mder_YOUR_API_KEY",
        "MDER_API_URL": "https://api.mder.pro"
      }
    }
  }
}

Environment Variables

Parameter	Type	Required	Description
`MDER_API_KEY`	string	Required	Your MDER API key (starts with mder_)
`MDER_API_URL`	string	Optional ("https://api.mder.pro")	API base URL

Tools

MCP tools are actions your agent can invoke. Each tool maps to an MDER API operation.

create_document

Create and optionally publish a new document. Supports both simple single-block content and rich multi-block documents.

Parameter	Type	Required	Description
`title`	string	Required	Document title
`content`	string	Optional	Simple mode: markdown content for a single-block document
`blocks`	Block[]	Optional	Rich mode: array of typed content blocks
`document_type`	string	Optional ("document")	"document", "report", "memo", or "summary"
`summary`	string	Optional	Brief summary of the document
`status`	string	Optional ("published")	"published" or "draft"
`access_mode`	string	Optional ("unlisted")	"unlisted" or "public"
`ttl_hours`	number	Optional	Auto-expire after N hours (e.g. 168 = 7 days)
`password`	string	Optional	Password-protect the document
`idempotency_key`	string	Optional	Prevent duplicate creation on retries

💡 Simple vs Rich mode

Use content when you just need a single markdown block. Use blocks when you need multiple blocks, code highlighting, tables, callouts, etc.

agent exampletext

Agent: "Create a document with today's meeting notes"

→ Tool call: create_document
  title: "Engineering Sync — April 20, 2026"
  content: "# Meeting Notes\n\n## Decisions\n- Ship v2.1 Monday\n- Delay PDF to v2.2"
  status: "published"
  ttl_hours: 168

← Result:
  {
    "document_id": "doc_...",
    "viewer_url": "https://mder.pro/d/xY7mK2",
    "status": "published"
  }

update_document

Update a draft document. Only works for documents in draft status.

Parameter	Type	Required	Description
`document_id`	string	Required	The document ID to update
`title`	string	Optional	New title
`content`	string	Optional	New markdown content (simple mode)
`blocks`	Block[]	Optional	New blocks array (rich mode)
`summary`	string	Optional	New summary

publish_document

Publish a draft document, making it accessible via its viewer URL.

Parameter	Type	Required	Description
`document_id`	string	Required	The document ID to publish

create_revision

Create a new revision of a published document with updated content. The viewer URL stays the same but shows the latest revision.

Parameter	Type	Required	Description
`document_id`	string	Required	The document ID
`title`	string	Optional	Updated title
`content`	string	Optional	Updated content (simple mode)
`blocks`	Block[]	Optional	Updated blocks (rich mode)
`summary`	string	Optional	Updated summary

list_documents

List all documents in the workspace with optional status filtering.

Parameter	Type	Required	Description
`status`	string	Optional	"draft", "published", "expired", "revoked", or "archived"
`page`	number	Optional (1)	Page number
`limit`	number	Optional (20)	Items per page (max 100)

revoke_document

Revoke access to a published document. The viewer URL will stop working immediately.

Parameter	Type	Required	Description
`document_id`	string	Required	The document ID to revoke

renew_document

Renew the TTL on a published or expired document.

Parameter	Type	Required	Description
`document_id`	string	Required	The document ID to renew
`ttl_hours`	number	Optional (168 (7 days))	New TTL in hours

archive_document

Archive a document. Removes it from active lists but preserves it.

Parameter	Type	Required	Description
`document_id`	string	Required	The document ID to archive

export_document

Export a document in a specific format.

Parameter	Type	Required	Description
`document_id`	string	Required	The document ID to export
`format`	string	Optional ("markdown")	"pdf", "markdown", or "json"

get_usage

Get current usage metrics and limits for the workspace. Takes no parameters.

get_capabilities

Get the capabilities and limits for the current plan. Takes no parameters.

Resources

MCP resources let agents read data without performing actions. They use mder:// URI scheme.

RESOURCEmder://documents/{document_id}

Get document metadata including status, viewer URL, dates, and access policy.

RESOURCEmder://documents/{document_id}/raw

Get the raw document content including all blocks.

RESOURCEmder://documents/{document_id}/revisions

Get the revision history of a document.

RESOURCEmder://usage

Current workspace usage metrics and plan limits.

RESOURCEmder://capabilities

Plan capabilities, limits, and feature flags.

Block Schema (for tools)

When using blocks in MCP tools, each block follows this schema:

Parameter	Type	Required	Description
`id`	string	Required	Unique block ID (e.g. "blk_1", "intro")
`type`	string	Required	Block type: markdown, code, image, table, heading, callout, divider, quote, list, embed, html
`content`	string	Required	Block content (interpretation depends on type)
`props`	object	Optional	Type-specific properties
`order`	number	Optional	Display order (0-based)

See the full Block Types Reference for all type-specific props and examples.

Typical Agent Workflow

workflowtext

1. Agent generates content (report, summary, analysis)
2. Agent calls create_document with content/blocks
3. MDER returns viewer_url
4. Agent shares the URL with the human (chat, email, Slack)
5. Human clicks the link and reads the beautifully rendered document

Optional follow-up:
6. Agent calls create_revision to update the content
7. Agent calls renew_document to extend the TTL
8. Agent calls revoke_document when the document is no longer needed

ℹ️ Idempotency for agents

Always use idempotency_key when creating documents from automated pipelines. If your agent retries a failed request, the same document will be returned instead of creating a duplicate.