Tool reference - Chatblocks

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

{
  "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: { <key>: { 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

{
  "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

{
  "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.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

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

`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 }. For one-shot AI generation, use blocks.create instead. 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.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

{
  "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

{
  "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 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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

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

`byokKeys.list`

List BYOK keys. List stored BYOK keys (metadata only). Input schema

{
  "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

{
  "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"
  ]
}

`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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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"
  ]
}

`schedule.delete`

Delete a scheduled run. Permanently delete a scheduled run. Builder plan. Input schema

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

`schedule.history`

Schedule run history. Recent run history for a schedule, newest first. Input schema

{
  "type": "object",
  "properties": {
    "scheduleId": {
      "type": "string"
    },
    "limit": {
      "type": "number"
    }
  },
  "required": [
    "scheduleId"
  ]
}

`schedule.list`

List scheduled runs. List scheduled runs in the workspace. Input schema

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

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

`stores.disconnect`

Builder plan required.

Disconnect the workspace’s Stripe Connect account. Calls Stripe deauthorize + flips status to disconnected. Input schema

{
  "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

{
  "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

{
  "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

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

​51 tools

​auditLog.recent

​blocks.bindData

​blocks.build

​blocks.capabilities

​blocks.create

​blocks.get

​blocks.getFiles

​blocks.init

​blocks.list

​blocks.listBindings

​blocks.patchFiles

​blocks.publish

​blocks.publishEmbed

​blocks.setFiles

​blocks.setRetired

​blocks.setWidgetData

​blocks.unbindData

​blocks.update

​byokKeys.add

​byokKeys.delete

​byokKeys.list

​canvases.get

​canvases.list

​canvases.setVisibility

​canvases.update

​dataSources.add

​dataSources.delete

​dataSources.editRefreshPolicy

​dataSources.get

​dataSources.introspect

​dataSources.list

​dataSources.listMcpTools

​dataSources.testConnection

​dataSources.triggerRefresh

​placements.create

​placements.delete

​placements.listForBlock

​placements.update

​placements.upgrade

​schedule.delete

​schedule.history

​schedule.list

​schedule.preview

​schedule.runNow

​schedule.set

​schedule.setStatus

​stores.connect

​stores.disconnect

​stores.list

​stores.refresh

​workspace.get

51 tools

`auditLog.recent`

`blocks.bindData`

`blocks.build`

`blocks.capabilities`

`blocks.create`

`blocks.get`

`blocks.getFiles`

`blocks.init`

`blocks.list`

`blocks.listBindings`

`blocks.patchFiles`

`blocks.publish`

`blocks.publishEmbed`

`blocks.setFiles`

`blocks.setRetired`

`blocks.setWidgetData`

`blocks.unbindData`

`blocks.update`

`byokKeys.add`

`byokKeys.delete`

`byokKeys.list`

`canvases.get`

`canvases.list`

`canvases.setVisibility`

`canvases.update`

`dataSources.add`

`dataSources.delete`

`dataSources.editRefreshPolicy`

`dataSources.get`

`dataSources.introspect`

`dataSources.list`

`dataSources.listMcpTools`

`dataSources.testConnection`

`dataSources.triggerRefresh`

`placements.create`

`placements.delete`

`placements.listForBlock`

`placements.update`

`placements.upgrade`

`schedule.delete`

`schedule.history`

`schedule.list`

`schedule.preview`

`schedule.runNow`

`schedule.set`

`schedule.setStatus`

`stores.connect`

`stores.disconnect`

`stores.list`

`stores.refresh`

`workspace.get`