Tool reference

This page is auto-generated from apps/web/src/lib/mcp/server.ts. Do not edit by hand — your changes will be overwritten by pnpm --filter @chatblocks/web gen-mcp-tool-ref. CI runs gen:check on every PR and fails if this file has drifted from the source.

24 tools

Connect with a cb_live_* API key as a Bearer token. See MCP setup for client configs.

`auditLog.recent`

Recent audit log. Recent audit log entries (credential decrypts, MCP writes, etc.). Input schema

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  }
}

`blocks.build`

Compile block source files. Compile a block’s files via Vercel Sandbox. Streams queued → building → succeeded|failed. Returns buildId on success — pass to blocks.publish. Input schema

{
  "type": "object",
  "properties": {
    "blockId": {
      "type": "string"
    }
  },
  "required": [
    "blockId"
  ]
}

`blocks.capabilities`

Block runtime capabilities. What runs inside a code block: supported libraries, CSP/sandbox rules, blocked APIs. Call BEFORE picking a library to avoid round-trips. Returns structured data + markdown for display. Input schema

{
  "type": "object",
  "properties": {}
}

`blocks.get`

Get a block. Fetch a block by id. Input schema

{
  "type": "object",
  "properties": {
    "blockId": {
      "type": "string"
    }
  },
  "required": [
    "blockId"
  ]
}

`blocks.getFiles`

Read block source files. Read a block’s source files plus latest build + published-version state. Input schema

{
  "type": "object",
  "properties": {
    "blockId": {
      "type": "string"
    }
  },
  "required": [
    "blockId"
  ]
}

`blocks.init`

Initialize a new block. Create an empty block with a starter file scaffold. Returns { blockId }. Input schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "slug": {
      "type": "string"
    }
  },
  "required": [
    "name"
  ]
}

`blocks.list`

List blocks. List blocks in the workspace. Retired blocks hidden unless includeRetired. Input schema

{
  "type": "object",
  "properties": {
    "published": {
      "type": "boolean"
    },
    "includeRetired": {
      "type": "boolean"
    }
  }
}

`blocks.patchFiles`

Patch block source files. Incremental edit: upserts adds/replaces files, deletes removes them. Validates merged set; failure returns validation.ok=false without mutating. Use blocks.setFiles for fresh starts. Input schema

{
  "type": "object",
  "properties": {
    "blockId": {
      "type": "string"
    },
    "upserts": {
      "type": "array",
      "items": {
        "type": "object"
      }
    },
    "deletes": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "snapshotMessage": {
      "type": "string"
    }
  },
  "required": [
    "blockId"
  ]
}

`blocks.publish`

Publish a block build. Pin a successful build (buildId from blocks.build, status=succeeded) as the published version. Placements on your own canvases auto-upgrade. Input schema

{
  "type": "object",
  "properties": {
    "blockId": {
      "type": "string"
    },
    "buildId": {
      "type": "string"
    },
    "changelog": {
      "type": "string"
    }
  },
  "required": [
    "blockId",
    "buildId"
  ]
}

`blocks.publishEmbed`

Publish an embed block. Snapshot-publish an embed-format block (no build). Pass framable: true only for URLs verified iframe-safe (e.g. YouTube /embed/). Placements on your canvases auto-upgrade. Input schema

{
  "type": "object",
  "properties": {}
}

`blocks.setFiles`

Replace block source files. Replace a block’s entire file set (omitted paths are deleted). Validates before writing; failure returns validation.ok=false without mutating. Then blocks.build → publish. Input schema

{
  "type": "object",
  "properties": {
    "blockId": {
      "type": "string"
    },
    "files": {
      "type": "array",
      "items": {
        "type": "object"
      }
    },
    "snapshotMessage": {
      "type": "string"
    }
  },
  "required": [
    "blockId",
    "files"
  ]
}

`blocks.setRetired`

Retire or restore a block. Soft-delete (retired: true) or restore (retired: false) a block. Retired blocks are hidden from lists and resource limits but stay in the DB; existing placements render a ‘Block removed’ tombstone. Restore re-checks the block cap. Use placements.listForBlock first to see affected canvases. Input schema

{
  "type": "object",
  "properties": {
    "blockId": {
      "type": "string"
    },
    "retired": {
      "type": "boolean"
    },
    "reason": {
      "type": "string"
    }
  },
  "required": [
    "blockId",
    "retired"
  ]
}

`blocks.update`

Update block metadata. Patch metadata (name, description, manifest, tags). Source code: use blocks.setFiles. Input schema

{
  "type": "object",
  "properties": {
    "blockId": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "manifest": {
      "type": "object"
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "blockId"
  ]
}

`blocks.view`

View a block. Display a published self-contained code block from this workspace in an MCP Apps host; external network, embeds, stores and live-data blocks are unsupported. Input schema

{
  "type": "object",
  "properties": {
    "blockId": {
      "type": "string"
    }
  },
  "required": [
    "blockId"
  ]
}

`canvases.get`

Get a canvas. Fetch a canvas with placements (current layout) and suggested_next_position (server-computed gap — use instead of guessing x/y). Input schema

{
  "type": "object",
  "properties": {
    "canvasId": {
      "type": "string"
    }
  },
  "required": [
    "canvasId"
  ]
}

`canvases.list`

List canvases. List canvases in the workspace. Input schema

{
  "type": "object",
  "properties": {}
}

`canvases.setVisibility`

Set canvas visibility. Set to private | workspace | public. public is viewable without login at /<username>/<slug> and returns that shareUrl. Input schema

{
  "type": "object",
  "properties": {
    "canvasId": {
      "type": "string"
    },
    "visibility": {
      "type": "string",
      "enum": [
        "private",
        "workspace",
        "public"
      ]
    }
  },
  "required": [
    "canvasId",
    "visibility"
  ]
}

`canvases.update`

Update canvas settings. Patch canvas title, description, interaction, badge, and search/social preview settings. Use canvases.setVisibility for public/private changes. Input schema

{
  "type": "object",
  "properties": {
    "canvasId": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "localEditsEnabled": {
      "type": "boolean"
    },
    "hideBadge": {
      "type": "boolean"
    },
    "seoTitle": {
      "type": "string"
    },
    "seoDescription": {
      "type": "string"
    },
    "socialImageUrl": {
      "type": "string"
    },
    "seoNoindex": {
      "type": "boolean"
    }
  },
  "required": [
    "canvasId"
  ]
}

`placements.create`

Create a placement. Place a published block on a canvas at (x, y). Block must be published. Input schema

{
  "type": "object",
  "properties": {
    "canvasId": {
      "type": "string"
    },
    "blockId": {
      "type": "string"
    },
    "x": {
      "type": "number"
    },
    "y": {
      "type": "number"
    },
    "width": {
      "type": "number"
    },
    "height": {
      "type": "number"
    }
  },
  "required": [
    "canvasId",
    "blockId",
    "x",
    "y"
  ]
}

`placements.delete`

Delete a placement. Remove a placement from its canvas. Input schema

{
  "type": "object",
  "properties": {
    "placementId": {
      "type": "string"
    }
  },
  "required": [
    "placementId"
  ]
}

`placements.listForBlock`

List a block’s placements. Every canvas this block appears on, with placement_id (for placements.delete) and position. Preflight before blocks.setRetired. Input schema

{
  "type": "object",
  "properties": {
    "blockId": {
      "type": "string"
    }
  },
  "required": [
    "blockId"
  ]
}

`placements.update`

Update a placement. Move, resize, or lock a placement. Input schema

{
  "type": "object",
  "properties": {
    "placementId": {
      "type": "string"
    },
    "x": {
      "type": "number"
    },
    "y": {
      "type": "number"
    },
    "width": {
      "type": "number"
    },
    "height": {
      "type": "number"
    },
    "locked": {
      "type": "boolean"
    }
  },
  "required": [
    "placementId"
  ]
}

`placements.upgrade`

Upgrade a placement. Pin a placement to a newer published version. Use for others’ blocks on your canvas; your own blocks auto-upgrade. Omit targetPublishedVersionId for the latest. Input schema

{
  "type": "object",
  "properties": {
    "placementId": {
      "type": "string"
    },
    "targetPublishedVersionId": {
      "type": "string"
    },
    "approverNote": {
      "type": "string"
    }
  },
  "required": [
    "placementId"
  ]
}

`workspace.get`

Get current workspace. Workspace metadata, per-resource limits/usage, and fresh viewer context such as the most recent canvas selection. Call first to preflight. Flow: getFiles → setFiles → build → publish → placements.create. Input schema

{
  "type": "object",
  "properties": {}
}

Get started

Concepts

Authoring blocks

MCP server

24 tools

`auditLog.recent`

`blocks.build`

`blocks.capabilities`

`blocks.get`

`blocks.getFiles`

`blocks.init`

`blocks.list`

`blocks.patchFiles`

`blocks.publish`

`blocks.publishEmbed`

`blocks.setFiles`

`blocks.setRetired`

`blocks.update`

`blocks.view`

`canvases.get`

`canvases.list`

`canvases.setVisibility`

`canvases.update`

`placements.create`

`placements.delete`

`placements.listForBlock`

`placements.update`

`placements.upgrade`

`workspace.get`