dev/page MCP tool
create_page
Create and immediately publish a Markdown or HTML page at a stable dev/page URL.
When to use it
When the user wants a new persistent page. Always resolve its destination through list_folders before creating it; reuse the best existing folder or, as an owner, create an appropriate durable folder when none fits.
Behavior
Creates and publishes a page in the selected workspace, or the stable default when workspace is omitted. Give every page a concise 3–8 word title and a one- or two-sentence description that explains its specific purpose, scope, audience, or outcome. Set status to todo when the page itself represents an actionable, unfinished task; use neutral for reference material and done only when the task is already complete. The description must add useful context rather than repeat the title or name the content format. Unless the user requests another visual direction, newly authored standalone HTML defaults to an A4-style report: a muted #e8ebe8 canvas, a centered white sheet up to 210mm wide with 17–18mm padding and a subtle shadow, compact system typography with an approximately 25pt title and 14.5pt ruled section headings, restrained #17211b ink with #1f6b45 green and #b76525 orange accents, and flat bordered metrics, notes, cards, and dense tables where the content benefits from them. Include only components the content needs. At 760px and below, remove the sheet margin and shadow, reduce padding, stack grids, and keep tables readable; for print, use a white background without the shadow and avoid breaks inside structured blocks. User-specified design overrides this default. Markdown authoring and rendering stay unchanged. In Markdown, use valid GFM tables: put the header, delimiter, and every data row on separate lines; never serialize an entire table onto one line. Before every creation, call list_folders in that workspace and supply the best destination's folderId. If no existing folder fits and the effective workspace role is owner, create a durable folder first and use its returned ID. Omitted or null folderId remains a compatibility fallback for automatic classification when explicit placement is not possible. The response confirms the effective workspace and folder.
- Required scopes
- pages:write
- Idempotency
- required
- Side effects
- Creates and publicly publishes one page and immutable revision.
- Cost
- One bounded database transaction.
- Recovery
- Retry an uncertain response with the identical idempotency key and input.
- Stable errors
- validation_error, invalid_folder, idempotency_conflict, workspace_not_found, workspace_access_revoked, rate_limited, service_not_ready
Exact input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"content": {
"type": "string",
"minLength": 1
},
"contentType": {
"type": "string",
"enum": [
"markdown",
"html"
]
},
"description": {
"type": "string",
"minLength": 20,
"maxLength": 300,
"description": "A specific one- or two-sentence summary that elaborates on the title; never a generic format label such as 'Markdown document' or 'HTML document'."
},
"folderId": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"type": "null"
}
]
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
},
"status": {
"default": "neutral",
"description": "Use todo when this page represents an actionable unfinished task, done for an already completed task, or neutral for ordinary reference material.",
"type": "string",
"enum": [
"neutral",
"todo",
"done"
]
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 80,
"description": "A concise 3–8 word title that names the page's subject."
},
"workspace": {
"type": "string",
"minLength": 1,
"maxLength": 80,
"pattern": "^[a-z0-9]+(?:[_-][a-z0-9]+)*$"
}
},
"required": [
"content",
"contentType",
"description",
"idempotencyKey",
"status",
"title"
],
"additionalProperties": false
}Exact success schema
Every successful MCP response uses this validated { contractVersion, requestId, data } envelope.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"contractVersion": {
"type": "string",
"const": "9"
},
"data": {
"type": "object",
"properties": {
"contentSha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"contentType": {
"type": "string",
"enum": [
"markdown",
"html"
]
},
"createdAt": {
"type": "string"
},
"folder": {
"anyOf": [
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"name": {
"type": "string"
},
"path": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"id",
"name",
"path"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"latestRevisionId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"pageId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"publicUrl": {
"type": "string",
"format": "uri"
},
"publishedRevisionId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"status": {
"type": "string",
"enum": [
"neutral",
"todo",
"done"
]
},
"title": {
"type": "string"
},
"updatedAt": {
"type": "string"
},
"workspace": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"isDefault": {
"type": "boolean"
},
"name": {
"type": "string"
},
"role": {
"type": "string",
"enum": [
"owner",
"editor"
]
},
"slug": {
"type": "string",
"minLength": 1,
"maxLength": 80,
"pattern": "^[a-z0-9]+(?:[_-][a-z0-9]+)*$"
}
},
"required": [
"id",
"isDefault",
"name",
"role",
"slug"
],
"additionalProperties": false
}
},
"required": [
"contentSha256",
"contentType",
"createdAt",
"folder",
"latestRevisionId",
"pageId",
"publicUrl",
"publishedRevisionId",
"status",
"title",
"updatedAt",
"workspace"
],
"additionalProperties": false
},
"requestId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"required": [
"contractVersion",
"data",
"requestId"
],
"additionalProperties": false
}