dev/page MCP tool
create_folder
Create a root or nested folder in the selected or default workspace.
When to use it
When list_folders shows that no existing folder appropriately represents a durable category for a page being created, including in an empty workspace.
Behavior
Creates a workspace folder. Folder hierarchy changes are restricted to the workspace owner.
- Required scopes
- pages:write
- Idempotency
- required
- Side effects
- Creates one workspace folder.
- Cost
- One bounded database transaction.
- Recovery
- Retry an uncertain response with the identical idempotency key and input.
- Stable errors
- owner_required, 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": {
"description": {
"anyOf": [
{
"type": "string",
"maxLength": 500
},
{
"type": "null"
}
]
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"parentId": {
"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"
}
]
},
"workspace": {
"type": "string",
"minLength": 1,
"maxLength": 80,
"pattern": "^[a-z0-9]+(?:[_-][a-z0-9]+)*$"
}
},
"required": [
"idempotencyKey",
"name"
],
"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": {
"createdAt": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"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"
},
"pageCount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"parentId": {
"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"
}
]
},
"path": {
"type": "array",
"items": {
"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": [
"createdAt",
"description",
"id",
"name",
"pageCount",
"parentId",
"path",
"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
}