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.

39 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, etc.) for the workspace. Input schema

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

`blocks.build`

Compile a block’s source files via Vercel Sandbox. Compile the block’s current source files into a deployable artifact. Streams progress events (queued -> building -> succeeded/failed) and returns the final build status. On succeeded, call blocks.publish with the returned buildId to make the build live on the canvas. Input schema

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

`blocks.create`

Builder plan required.

Generate a block from a prompt. Streams progress while an AI model generates a new React block. Returns the saved block id and slug. The block is left unpublished — call blocks.publish after the build pipeline completes. Input schema

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

`blocks.delete`

Delete a block. Permanently delete a block and all its associated data. Input schema

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

`blocks.get`

Get a block. Fetch a block by id, scoped to the current workspace. Input schema

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

`blocks.getFiles`

Read block source files. Read the current source files for one block, plus latest build and published-version state. Use this before calling blocks.setFiles to see what’s there, or after blocks.build to check the build outcome. Input schema

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

`blocks.init`

Initialize a new block. Create a new empty block with a starter file scaffold. Use this when you’re going to author the block’s source files yourself via blocks.setFiles. For one-shot AI generation, use blocks.create instead. Input schema

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

`blocks.list`

List blocks. List blocks in the current workspace. Input schema

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

`blocks.publish`

Publish a block build. Pin a specific successful build as the published version of a block. Pass the buildId returned by a blocks.build call that finished with status=succeeded — publishing without a build first will fail. After publish, the block’s source is served at /api/blocks/<blockId>/render and is available for canvas placement. Optional changelog is shown in version history. Input schema

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

`blocks.setFiles`

Replace block source files. Replace the entire file set for one block. Validates the file set before writing; on validation failure returns validation.ok=false and does NOT mutate. The files array is the complete desired state (any path you omit is deleted). Pair with blocks.build to compile the new code. Input schema

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

`blocks.setWidgetData`

Set block widget data. Hot-update the widget data for a block (bypasses the refresh pipeline). Input schema

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

`blocks.update`

Update block metadata. Update name, description, manifest, or tags for a block. For source code changes use the editor. 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`

Add a BYOK AI provider key. Store a customer-supplied API key for Anthropic, OpenAI, or Google. Validated on add by pinging the provider. Encrypted at rest. Input schema

{
  "type": "object",
  "properties": {
    "provider": {
      "type": "string",
      "enum": [
        "anthropic",
        "openai",
        "google"
      ]
    },
    "plaintext": {
      "type": "string"
    },
    "label": {
      "type": "string"
    }
  },
  "required": [
    "provider",
    "plaintext"
  ]
}

`byokKeys.delete`

Delete a BYOK key. Remove a stored BYOK key. The customer’s provider account is unaffected. Input schema

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

`byokKeys.list`

List BYOK keys. List the workspace’s stored BYOK keys (metadata only — no plaintext). Input schema

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

`canvases.get`

Get a canvas. Fetch a canvas by id, scoped to the current workspace. Input schema

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

`canvases.list`

List canvases. List canvases in the current workspace. Input schema

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

`dataSources.add`

Add a data source. Connect a new data source (stripe, postgres, webhook, or mcp). Webhook type 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. Remove a data source and all associated credentials. Input schema

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

`dataSources.editRefreshPolicy`

Edit data source refresh policy. Change the refresh cadence for a data source. 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, scoped to the current workspace. Input schema

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

`dataSources.introspectSchema`

Introspect Postgres schema. List the top 50 tables in a Postgres data source, sorted by activity. Input schema

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

`dataSources.introspectTable`

Introspect Postgres table. List columns, types, and constraints for a specific Postgres table. Input schema

{
  "type": "object",
  "properties": {
    "dataSourceId": {
      "type": "string"
    },
    "schema": {
      "type": "string"
    },
    "table": {
      "type": "string"
    }
  },
  "required": [
    "dataSourceId",
    "schema",
    "table"
  ]
}

`dataSources.list`

List data sources. List data sources in the current workspace. Input schema

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

`dataSources.listMcpTools`

List tools from an outbound MCP source. Connects to an mcp-typed dataSource and returns the tools it exposes. Use this before binding a block to a specific tool. Input schema

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

`dataSources.testConnection`

Test a data source connection. Streams per-stage progress while testing a data source connection (Stripe / Postgres). Webhook and MCP types return descriptive messages. Input schema

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

`dataSources.triggerRefresh`

Trigger a data source refresh. Schedules an immediate refresh of a data source. Returns once the refresh is queued; 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 the specified coordinates. 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 block placement from its canvas. Input schema

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

`placements.update`

Update a placement. Move or resize a placement on its canvas. 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"
  ]
}

`schedule.delete`

Builder plan required.

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

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

`schedule.history`

Get history for a scheduled run. Returns recent history rows for a scheduled run, sorted 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 current workspace. Input schema

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

`schedule.pause`

Builder plan required.

Pause a scheduled run. Pause an active scheduled run. Input schema

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

`schedule.preview`

Builder plan required.

Preview a scheduled run. Run a one-off preview of a scheduled prompt without saving a recurring schedule. Streams agent progress as SSE events. Input schema

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

`schedule.resume`

Builder plan required.

Resume a paused scheduled run. Resume a paused scheduled run. Input schema

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

`schedule.runNow`

Builder plan required.

Trigger a one-off run of a saved schedule. Triggers a one-off run via Trigger.dev. Doesn’t affect the cron schedule. Input schema

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

`schedule.set`

Builder plan required.

Create or update a scheduled run. Create or update a scheduled AI run for a block. 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"
  ]
}

`workspace.get`

Get current workspace. Fetch metadata about the current workspace. Input schema

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

Get started

Concepts

Authoring blocks

Connecting data

Scheduled runs

MCP server

CLI

Billing

Documentation Index

​39 tools

​auditLog.recent

​blocks.build

​blocks.create

​blocks.delete

​blocks.get

​blocks.getFiles

​blocks.init

​blocks.list

​blocks.publish

​blocks.setFiles

​blocks.setWidgetData

​blocks.update

​byokKeys.add

​byokKeys.delete

​byokKeys.list

​canvases.get

​canvases.list

​dataSources.add

​dataSources.delete

​dataSources.editRefreshPolicy

​dataSources.get

​dataSources.introspectSchema

​dataSources.introspectTable

​dataSources.list

​dataSources.listMcpTools

​dataSources.testConnection

​dataSources.triggerRefresh

​placements.create

​placements.delete

​placements.update

​schedule.delete

​schedule.history

​schedule.list

​schedule.pause

​schedule.preview

​schedule.resume

​schedule.runNow

​schedule.set

​workspace.get

39 tools

`auditLog.recent`

`blocks.build`

`blocks.create`

`blocks.delete`

`blocks.get`

`blocks.getFiles`

`blocks.init`

`blocks.list`

`blocks.publish`

`blocks.setFiles`

`blocks.setWidgetData`

`blocks.update`

`byokKeys.add`

`byokKeys.delete`

`byokKeys.list`

`canvases.get`

`canvases.list`

`dataSources.add`

`dataSources.delete`

`dataSources.editRefreshPolicy`

`dataSources.get`

`dataSources.introspectSchema`

`dataSources.introspectTable`

`dataSources.list`

`dataSources.listMcpTools`

`dataSources.testConnection`

`dataSources.triggerRefresh`

`placements.create`

`placements.delete`

`placements.update`

`schedule.delete`

`schedule.history`

`schedule.list`

`schedule.pause`

`schedule.preview`

`schedule.resume`

`schedule.runNow`

`schedule.set`

`workspace.get`