Available Tools
The BEEM MCP server exposes 68 tools organized into the categories below. All tools use your BEEM account permissions — you can only access resources you have access to in BEEM.
Start with the Workflows — they bundle the most common multi-step tasks (create-and-deploy a dataset, build a dashboard, explore a schema) into a single call. The remaining categories expose the underlying granular operations.
Workflows (Composite Tools)
| Tool | Description |
|---|---|
| Get Workspace Overview | Get a complete workspace overview in a single call. Returns workspace info (including SQL schema names), folder tree, all datasets (with status/rowCount), sources, flows, dashboards, and recent failures. Use this as the first call when orienting in a workspace — replaces the need to call get_workspace + list_folders + list_datasets + list_sources separately. |
| Search Workspace | Search for objects by name across the workspace. Searches datasets (by name and viewName), sources (by name and connection name), folders, dashboards, and flows. Case-insensitive contains match. Use to quickly find objects without listing everything. |
| Explore Schema | Get complete SQL-writing context in a single call. Returns all source tables (with column schemas) and deployed hub datasets (with view names), plus the correct schema prefixes. Use this before writing SQL queries to discover available tables and columns. Excludes the internal beem_file_no column automatically. |
| Get Dataset Details | Get comprehensive dataset details in a single call. Returns dataset metadata (including status, rowCount, columns from cloudResourceInfo), current SQL query, tests, recent events, and visualizations. Use instead of calling get_dataset + get_sql_queries + list_tests + list_events + list_visualizations separately. |
| Create & Deploy Dataset | Create a new dataset AND deploy its SQL in a single call. This is the recommended way to create datasets — it auto-derives the SQL view name from the dataset name and deploys immediately, avoiding the "broken undeployed dataset" problem. Deployment is async — poll beem_get_dataset for cloudResourceInfo.status === "SUCCESS". |
| Create & Deploy Dataset Test | Create a new dataset test AND deploy its SQL in a single call. Test SQL must return these 4 columns in order: number (INT), category (VARCHAR), reason (VARCHAR), blocking (BOOLEAN). Zero rows = pass; any rows = failure. If blocking is true, the dataset "latest" view is NOT updated on refresh. Ensure the parent dataset is deployed with data before creating tests. |
| Edit Dataset Schedule | Change a dataset's refresh schedule in one step. Set trigger to CRON with an EventBridge cron expression to enable automatic refreshes, or MANUAL to disable them. Handles the EventBridge rule update and redeploy automatically. The dataset must already be deployed (not a draft). |
| Build Dashboard | Create a complete dashboard with visualizations and widgets in a single call. Automatically creates visualizations for VISUALIZATION-type widgets and auto-lays them out in a 12-column grid (default: 2 columns at w=6). For each visualization widget, provide datasetId, chartType, and configurations — the configurations JSON must contain the keys that chart type requires (same contract as beem_create_visualization, e.g. TABLE needs {"columns":[...]}, BAR_CHART needs xAxisColumn/yAxisColumns/etc.) or the call fails with a validation error. For text/heading widgets, provide text content. Replaces manual create_dashboard + create_visualization + create_widget calls. |
| Deploy & Wait | Deploy a dataset SQL query and wait for the Redshift view to be created. Polls beem_get_dataset until cloudResourceInfo shows a new version with SUCCESS or FAIL status. Returns the final status, row count, and elapsed time. Use instead of beem_deploy_dataset_sql_query when you need to confirm deployment succeeded before proceeding. |
| Await Operation | Wait for an async operation to complete by polling events. Monitors events for a dataset, data object, source, or flow until a terminal event (SUCCESS/FAIL) appears. Optionally wait for a specific action type. Use after triggering a deploy, refresh, or ingestion when you need to confirm completion. |
| Get Pipeline Health | Get an actionable pipeline health summary for a workspace. Categorizes all datasets as healthy (recent success), failing (recent failure), running (in progress), stale (scheduled but no recent events), or draft. Shows failure messages and timing. Use to quickly identify problems without scanning individual events. |
Workspaces & Organizations
| Tool | Description |
|---|---|
| Get Current User | Get the authenticated user's info. Use this first to get your userId (needed as ownerId for creating datasets and tests). |
| Get Workspace | Get workspace details including seq number (needed for SQL schema names: ws{seq}_catalog, ws{seq}_hub). |
| List Workspaces | List all accessible workspaces. Step 2 of orientation — call after beem_list_user_organizations. |
| Get Organization | Get details about a specific BEEM organization by ID, including workspaces and limits. |
| List User Organizations | List all organizations the user belongs to. Step 1 of orientation — call this first to get organizationIds. |
| Get Organization Source Config | Get the in-app source ingestion config (schedules, primary keys, S3 paths, etc.) for a BEEM organization. Returns the parsed wholeSourceConfig JSON. Optionally narrow to a specific source key (e.g. 'tempo') and/or table key (e.g. 'worklogs'). Large blob — only request when debugging ingestion pipeline configuration. Returns { hasConfig: false, sourceConfig: null } when the organization has not been migrated to the in-app source config model. |
Folders
| Tool | Description |
|---|---|
| Get Folder | Get details about a specific BEEM folder including its parent, subfolders, and datasets. |
| List Folders | List folders in a workspace or under a parent folder. |
| Create Folder | Create a new folder in BEEM. |
| Update Folder | Update an existing folder in BEEM (rename or move). |
Datasets
| Tool | Description |
|---|---|
| Get Dataset | Get details about a specific BEEM dataset including metadata, owner, and configuration. Returns full dataset metadata including cloudResourceInfo (timing, rowCount, status). Parse the parents field for lineage. |
| List Datasets | List datasets in a BEEM workspace or folder. Use to discover available datasets in a workspace. Returns name, viewName, status, trigger, and folder info. |
| Create Dataset | Create a new dataset in BEEM. The dataset starts as a draft until SQL is deployed. IMPORTANT: You must deploy SQL immediately after creating — an undeployed dataset is broken and causes "version undefined" errors in the app. |
| Update Dataset | Update an existing dataset in BEEM (description, folder, AI search settings). To rename a dataset, use beem_rename_dataset instead. |
| Rename Dataset | Rename a dataset in BEEM. Updates the dataset name, derives a new SQL-compatible view name, and redeploys the Redshift view under the new name. Warning: renaming changes the Redshift view name. Downstream datasets referencing the old viewName will break. |
| Get Dataset SQL Query History | Get the SQL query history for a dataset, including both deployed and draft versions. |
| Get Dataset SQL Query | Get a specific SQL query version for a dataset. |
| Save Dataset SQL Query | Step 1 of SQL update: saves SQL as a draft without executing. Follow with beem_deploy_dataset_sql_query to create the Redshift view. Never use SELECT — always list columns explicitly. Include a SQL header comment with name, description, and changelog. For CRON triggers, use bare 6-field format (min hour dom month dow year) without cron() wrapper — cannot use in both day-of-month and day-of-week, use ? for one. |
| Deploy Dataset SQL Query | Step 2 of SQL update: deploys the saved SQL. This creates the view in Redshift and schedules execution if needed. Deployment is async — data is NOT ready when this returns. Poll beem_get_dataset and check cloudResourceInfo until rowCount > 0, version changed from pre-deploy value, and status = SUCCESS (poll every 30s, timeout 5min). |
| Refresh Dataset | Trigger a manual refresh of a deployed dataset without redeploying SQL. Use after upstream data changes. The dataset must have been deployed at least once. Will not trigger if the dataset is already refreshing. |
Dataset SQL & Content
| Tool | Description |
|---|---|
| Query Dataset Content | Query and retrieve rows from a deployed BEEM dataset. Returns results as a Markdown table by default (set format to "json" for raw data). This is an async operation that may take time for large datasets. |
| Preview SQL Query | Preview the results of a SQL query without deploying it. Useful for testing queries before saving. Returns results as a Markdown table by default. Source tables use ws{seq}_catalog schema; datasets use ws{seq}_hub schema (get seq from beem_get_workspace). Avoid $ in REGEXP_REPLACE — the platform wraps SQL in a subquery that mangles $ anchors. Use RIGHT()/LEFT() instead. |
Dataset Tests
| Tool | Description |
|---|---|
| Get Dataset Test | Get details about a specific BEEM dataset test. |
| List Dataset Tests | List all tests for a specific dataset. |
| Create Dataset Test | Create a new test for a dataset. After creating, you MUST deploy test SQL immediately. Tests validate data quality with SQL assertions. Test SQL must return these 4 columns first in exact order: number (INT), category (VARCHAR), reason (VARCHAR), blocking (BOOLEAN). Zero rows = pass; any rows = failure. If blocking is true, the dataset "latest" view is NOT updated. |
| Update Dataset Test | Update a dataset test (rename). |
| Delete Dataset Test | Delete a dataset test and all its SQL query history. |
| Get Test SQL Query History | Get the SQL query history for a dataset test. |
| Save Test SQL Query | Save a SQL query as a draft for a dataset test (does not execute). Follow with beem_deploy_dataset_test_sql_query to deploy. |
| Deploy Test SQL Query | Step 2 of test creation: deploys the test SQL. This executes the test query. Ensure the parent dataset has been deployed and has data before deploying tests — tests run against the hub table. |
Sources & Ingestion
| Tool | Description |
|---|---|
| Get Source | Get details about a specific BEEM source (catalog) by ID, including its connection information. |
| List Sources | List data connections in a workspace. Use to discover available source tables before writing SQL. |
| Get Data Object | Get a source table's details including column schema in cloudResourceInfo. Parse cloudResourceInfo.columns for column names when writing SQL. Exclude the internal beem_file_no column. |
| List Data Objects | List source tables for a data connection. Parse cloudResourceInfo.columns for column schemas. When writing SQL from source tables, exclude the internal beem_file_no column — skip objects with null cloudResourceInfo. |
| Create Data Object | Create a new data object (source table) in BEEM. Data objects represent tables within a source/catalog. |
| Start Data Ingestion | Trigger a manual data ingestion (sync) for a source data object. Equivalent to "Sync Now" in the BEEM app. The ingestion runs asynchronously — use beem_list_events_by_object to check status. |
Dashboards
| Tool | Description |
|---|---|
| Get Dashboard | Get details about a specific BEEM dashboard. |
| List Dashboards | List dashboards in a workspace. |
| Create Dashboard | Create a new dashboard in BEEM. |
| Update Dashboard | Update an existing dashboard in BEEM (rename). |
| Get Dashboard Widget | Get details about a specific dashboard widget. |
| List Dashboard Widgets | List all widgets in a dashboard. |
| Create Dashboard Widget | Create a new widget on a dashboard. Position uses a 12-column grid. Common layout: w=6 for half-width, w=12 for full-width. Widget types and their required configurations keys: VISUALIZATION → set componentId and configurations {"visualizationId":"<id>"}. HEADING / TEXT_BLOCK → configurations {"content":"<text>"} (the key MUST be "content", not "text", or the dashboard renders blank). DYNAMIC_FILTERS → configurations {"filters":[{"label":...,"type":...,"columns":["{visualizationId}.{columnName}.remote"]}]} — filters must be a non-empty array of complete filters, and columns must use the fully-qualified {visualizationId}.{columnName}.remote format (bare column names and empty filters will not work). IMAGE_UPLOAD → configurations with the image reference. |
| Update Dashboard Widget | Update an existing dashboard widget. |
| Delete Dashboard Widget | Delete a widget from a dashboard. Use this to remove a widget that was created incorrectly or is no longer needed. |
Visualizations
| Tool | Description |
|---|---|
| Get Visualization | Get details about a specific dataset visualization. |
| List Visualizations by Dataset | List all visualizations for a specific dataset. |
| List Visualizations by Workspace | List all visualizations in a workspace (includes dataset name). |
| Create Visualization | Create a new visualization for a dataset. The configurations JSON must match the chart type exactly or the chart will not render: BAR_CHART/LINE_CHART → {"isStacked":bool,"isHorizontal":bool,"xLabel":str,"yLabel":str,"xAxisColumn":str,"yAxisColumns":[str],"groupBy":str OR "series":[...]}. PIE_CHART/DOUGHNUT_CHART → {"xAxisColumn":str,"yAxisColumn":str}. GAUGE_CHART → {"column":str,"metric":str,"description":str,"maxValue":num OR "maxValueColumn":str}. COLUMN_METRIC → {"column":str,"metric":str,"description":str}. TABLE → {"columns":[str]}. Column values are dataset column names. |
| Update Visualization | Update an existing visualization. If configurations is provided it must match the chart type exactly (same per-type keys as beem_create_visualization) or the chart will not render. When changing configurations without passing type, the existing chart type is used for validation. |
| Delete Visualization | Delete a visualization. Also decrements the vizCount on the parent dataset. |
Flows
| Tool | Description |
|---|---|
| Get Flow | Get details of a specific flow (reverse ETL / data activation) by ID. Flows connect datasets to destination connections with scheduling. Returns flow configuration, trigger type, linked dataset/destination, and cloud resource info. |
| List Flows | List data flows (reverse ETL / data activation) in a workspace. Returns flow names, triggers, enabled status, and linked datasets/destinations. |
Events & Usage
| Tool | Description |
|---|---|
| List Workspace Events | List pipeline events filtered by object type, status, and date range. Use to check pipeline health. Events track data object syncs, dataset transformations, and flow runs. |
| List Object Events | List events for a specific data object or dataset. Use to monitor deployment/refresh status. |
| List User Events | List pipeline execution events triggered by a specific user. |
| Get DPU Usage | Get DPU (data processing unit) billing/consumption data for the organization. Returns daily DPU usage records, total consumption, allowance, and billing cycle info. By default returns usage for the current billing cycle. |