> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chatblocks.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Tool reference
> All MCP tools exposed by the Chatblocks server at /api/mcp/v1.
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.
## 51 tools
Connect with a `cb_live_*` API key as a Bearer token. See [MCP setup](/mcp/setup) for client configs.
Tools marked **Builder plan required** are gated server-side; calling them on a Free workspace returns a JSON-RPC error with code `-32603` and a `PRO_REQUIRED` message body.
***
### `auditLog.recent`
**Recent audit log.** Recent audit log entries (credential decrypts, MCP writes, etc.).
**Input schema**
```json theme={null}
{
"type": "object",
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100
}
}
}
```
***
### `blocks.bindData`
Builder plan required.
**Bind a block to a data source.** Wire a block to live data: queryConfig picks the query (e.g. stripe.mrr, postgres.sql, webhook.latest, mcp.tool — must match the source's type), projection maps the raw result into `manifest.widget.data` (shape: \{ fields: \{ \: \{ source: "\$.path" } | \{ literal: ... } } }), which code-block renders expose as window.**CHATBLOCKS\_DATA**. Replaces any existing binding for the same block + source and schedules an immediate refresh. Note: data bound to a publicly-rendered block is publicly readable.
**Input schema**
```json theme={null}
{
"type": "object",
"properties": {
"blockId": {
"type": "string"
},
"dataSourceId": {
"type": "string"
},
"queryConfig": {
"type": "object"
},
"projection": {
"type": "object"
}
},
"required": [
"blockId",
"dataSourceId",
"queryConfig",
"projection"
]
}
```
***
### `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**
```json theme={null}
{
"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**
```json theme={null}
{
"type": "object",
"properties": {}
}
```
***
### `blocks.create`
**Generate a block from a prompt.** Stream-generate a React block from a prompt. Saved unpublished; call blocks.build then blocks.publish. Builder plan.
**Input schema**
```json theme={null}
{
"type": "object",
"properties": {
"prompt": {
"type": "string"
},
"slug": {
"type": "string"
}
},
"required": [
"prompt"
]
}
```
***
### `blocks.get`
**Get a block.** Fetch a block by id.
**Input schema**
```json theme={null}
{
"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**
```json theme={null}
{
"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 }`. For one-shot AI generation, use blocks.create instead.
**Input schema**
```json theme={null}
{
"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**
```json theme={null}
{
"type": "object",
"properties": {
"published": {
"type": "boolean"
},
"includeRetired": {
"type": "boolean"
}
}
}
```
***
### `blocks.listBindings`
**List a block's data bindings.** Data-source bindings for a block, with source label/type, queryConfig, and the active projection. binding ids feed blocks.unbindData.
**Input schema**
```json theme={null}
{
"type": "object",
"properties": {
"blockId": {
"type": "string"
}
},
"required": [
"blockId"
]
}
```
***
### `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**
```json theme={null}
{
"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**
```json theme={null}
{
"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**
```json theme={null}
{
"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**
```json theme={null}
{
"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 plan 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**
```json theme={null}
{
"type": "object",
"properties": {
"blockId": {
"type": "string"
},
"retired": {
"type": "boolean"
},
"reason": {
"type": "string"
}
},
"required": [
"blockId",
"retired"
]
}
```
***
### `blocks.setWidgetData`
**Set block widget data.** Hot-update a block's widget data (bypasses the refresh pipeline).
**Input schema**
```json theme={null}
{
"type": "object",
"properties": {
"blockId": {
"type": "string"
},
"data": {
"type": "object"
}
},
"required": [
"blockId",
"data"
]
}
```
***
### `blocks.unbindData`
**Remove a data binding.** Delete a block↔data-source binding (bindingId from blocks.listBindings). The block keeps its last widget data; it just stops refreshing.
**Input schema**
```json theme={null}
{
"type": "object",
"properties": {
"bindingId": {
"type": "string"
}
},
"required": [
"bindingId"
]
}
```
***
### `blocks.update`
**Update block metadata.** Patch metadata (name, description, manifest, tags). Source code: use blocks.setFiles.
**Input schema**
```json theme={null}
{
"type": "object",
"properties": {
"blockId": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"manifest": {
"type": "object"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"blockId"
]
}
```
***
### `byokKeys.add`
Builder plan required.
**Add a BYOK key.** Store a customer key for Anthropic/OpenAI. Validated on add, encrypted at rest.
**Input schema**
```json theme={null}
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"enum": [
"anthropic",
"openai"
]
},
"plaintext": {
"type": "string"
},
"label": {
"type": "string"
}
},
"required": [
"provider",
"plaintext"
]
}
```
***
### `byokKeys.delete`
**Delete a BYOK key.** Remove a stored BYOK key. Provider account unaffected.
**Input schema**
```json theme={null}
{
"type": "object",
"properties": {
"keyId": {
"type": "string"
}
},
"required": [
"keyId"
]
}
```
***
### `byokKeys.list`
**List BYOK keys.** List stored BYOK keys (metadata only).
**Input schema**
```json theme={null}
{
"type": "object",
"properties": {}
}
```
***
### `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**
```json theme={null}
{
"type": "object",
"properties": {
"canvasId": {
"type": "string"
}
},
"required": [
"canvasId"
]
}
```
***
### `canvases.list`
**List canvases.** List canvases in the workspace.
**Input schema**
```json theme={null}
{
"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**
```json theme={null}
{
"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**
```json theme={null}
{
"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"
]
}
```
***
### `dataSources.add`
Builder plan required.
**Add a data source.** Connect a data source (stripe | postgres | webhook | mcp). Webhook returns a one-time whsec\_\* secret.
**Input schema**
```json theme={null}
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"stripe",
"postgres",
"webhook",
"mcp"
]
},
"label": {
"type": "string"
},
"apiKey": {
"type": "string"
},
"webhookSecret": {
"type": "string"
},
"connectionString": {
"type": "string"
},
"serverUrl": {
"type": "string"
},
"authToken": {
"type": "string"
},
"refreshPolicy": {
"type": "object"
}
},
"required": [
"type",
"label"
]
}
```
***
### `dataSources.delete`
**Delete a data source.** Delete a data source and its credentials.
**Input schema**
```json theme={null}
{
"type": "object",
"properties": {
"dataSourceId": {
"type": "string"
}
},
"required": [
"dataSourceId"
]
}
```
***
### `dataSources.editRefreshPolicy`
Builder plan required.
**Edit refresh policy.** Change a data source's refresh cadence.
**Input schema**
```json theme={null}
{
"type": "object",
"properties": {
"dataSourceId": {
"type": "string"
},
"refreshPolicy": {
"type": "object"
}
},
"required": [
"dataSourceId",
"refreshPolicy"
]
}
```
***
### `dataSources.get`
**Get a data source.** Fetch a data source by id.
**Input schema**
```json theme={null}
{
"type": "object",
"properties": {
"dataSourceId": {
"type": "string"
}
},
"required": [
"dataSourceId"
]
}
```
***
### `dataSources.introspect`
Builder plan required.
**Introspect a Postgres source.** Postgres only. Default: list top 50 tables by activity. With `schema` + `table` set, returns columns/types/constraints for that one table.
**Input schema**
```json theme={null}
{
"type": "object",
"properties": {
"dataSourceId": {
"type": "string"
},
"schema": {
"type": "string"
},
"table": {
"type": "string"
}
},
"required": [
"dataSourceId"
]
}
```
***
### `dataSources.list`
**List data sources.** List data sources in the workspace.
**Input schema**
```json theme={null}
{
"type": "object",
"properties": {}
}
```
***
### `dataSources.listMcpTools`
Builder plan required.
**List tools from an MCP source.** Connect to an mcp-typed data source and list its tools. Use before binding a block.
**Input schema**
```json theme={null}
{
"type": "object",
"properties": {
"dataSourceId": {
"type": "string"
}
},
"required": [
"dataSourceId"
]
}
```
***
### `dataSources.testConnection`
Builder plan required.
**Test a data source connection.** Stream a connection test (Stripe/Postgres). Webhook/MCP return a descriptive message.
**Input schema**
```json theme={null}
{
"type": "object",
"properties": {
"dataSourceId": {
"type": "string"
}
},
"required": [
"dataSourceId"
]
}
```
***
### `dataSources.triggerRefresh`
Builder plan required.
**Trigger a data source refresh.** Queue an immediate refresh. Poll dataSources.get for lastRefreshAt.
**Input schema**
```json theme={null}
{
"type": "object",
"properties": {
"dataSourceId": {
"type": "string"
}
},
"required": [
"dataSourceId"
]
}
```
***
### `placements.create`
**Create a placement.** Place a published block on a canvas at (x, y). Block must be published.
**Input schema**
```json theme={null}
{
"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**
```json theme={null}
{
"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**
```json theme={null}
{
"type": "object",
"properties": {
"blockId": {
"type": "string"
}
},
"required": [
"blockId"
]
}
```
***
### `placements.update`
**Update a placement.** Move, resize, or lock a placement.
**Input schema**
```json theme={null}
{
"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**
```json theme={null}
{
"type": "object",
"properties": {
"placementId": {
"type": "string"
},
"targetPublishedVersionId": {
"type": "string"
},
"approverNote": {
"type": "string"
}
},
"required": [
"placementId"
]
}
```
***
### `schedule.delete`
**Delete a scheduled run.** Permanently delete a scheduled run. Builder plan.
**Input schema**
```json theme={null}
{
"type": "object",
"properties": {
"scheduleId": {
"type": "string"
}
},
"required": [
"scheduleId"
]
}
```
***
### `schedule.history`
**Schedule run history.** Recent run history for a schedule, newest first.
**Input schema**
```json theme={null}
{
"type": "object",
"properties": {
"scheduleId": {
"type": "string"
},
"limit": {
"type": "number"
}
},
"required": [
"scheduleId"
]
}
```
***
### `schedule.list`
**List scheduled runs.** List scheduled runs in the workspace.
**Input schema**
```json theme={null}
{
"type": "object",
"properties": {}
}
```
***
### `schedule.preview`
**Preview a scheduled run.** One-off preview of a scheduled prompt without saving. Streams agent progress. Builder plan.
**Input schema**
```json theme={null}
{
"type": "object",
"properties": {
"apiKeyId": {
"type": "string"
},
"prompt": {
"type": "string"
},
"modelId": {
"type": "string"
},
"blockId": {
"type": "string"
}
},
"required": [
"apiKeyId",
"prompt",
"modelId"
]
}
```
***
### `schedule.runNow`
**Run a schedule now.** One-off run via Trigger.dev. Doesn't affect the cron. Builder plan.
**Input schema**
```json theme={null}
{
"type": "object",
"properties": {
"scheduleId": {
"type": "string"
}
},
"required": [
"scheduleId"
]
}
```
***
### `schedule.set`
**Create or update a scheduled run.** Create or update a scheduled AI run. Builder plan.
**Input schema**
```json theme={null}
{
"type": "object",
"properties": {
"scheduleId": {
"type": "string"
},
"blockId": {
"type": "string"
},
"apiKeyId": {
"type": "string"
},
"prompt": {
"type": "string"
},
"cronExpression": {
"type": "string"
},
"modelId": {
"type": "string"
}
},
"required": [
"apiKeyId",
"prompt",
"cronExpression",
"modelId"
]
}
```
***
### `schedule.setStatus`
**Pause or resume a scheduled run.** Set a schedule's status to active (resume) or paused. Builder plan.
**Input schema**
```json theme={null}
{
"type": "object",
"properties": {
"scheduleId": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"active",
"paused"
]
}
},
"required": [
"scheduleId",
"status"
]
}
```
***
### `stores.connect`
Builder plan required.
**Start Stripe Connect OAuth.** Returns a Stripe Connect OAuth URL. Open it in a browser to authorize.
**Input schema**
```json theme={null}
{
"type": "object",
"properties": {}
}
```
***
### `stores.disconnect`
Builder plan required.
**Disconnect the workspace's Stripe Connect account.** Calls Stripe deauthorize + flips status to disconnected.
**Input schema**
```json theme={null}
{
"type": "object",
"properties": {
"connectionId": {
"type": "string"
}
},
"required": [
"connectionId"
]
}
```
***
### `stores.list`
**List the workspace's Stripe Connect connection.** Returns the current store connection + cached product summary, or null.
**Input schema**
```json theme={null}
{
"type": "object",
"properties": {}
}
```
***
### `stores.refresh`
Builder plan required.
**Refresh the workspace's cached products from Stripe.** Pulls active products + prices from Stripe and updates the store's cached payload.
**Input schema**
```json theme={null}
{
"type": "object",
"properties": {
"connectionId": {
"type": "string"
}
},
"required": [
"connectionId"
]
}
```
***
### `workspace.get`
**Get current workspace.** Workspace metadata, plan, 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**
```json theme={null}
{
"type": "object",
"properties": {}
}
```