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. 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
}