# MCP tools reference

> Every Flax MCP tool — discovery and read tools, run_query, and the write tools for building charts, sheets, and dashboards

*[View this page in the Flax docs](https://flax-analytics.com/docs/developers/mcp-tools)*

This is the complete Flax MCP tool set. Each tool maps 1:1 to a [REST API](/docs/api-reference/overview) endpoint. The natural workflow is **discover** what exists, **validate** a query with `run_query`, then **create** or **update** artifacts. This page is for developers and agent authors building with the [MCP server](/docs/developers/mcp-overview).

## Discovery and read

These tools require only the `read` scope.

| Tool | What it does |
| --- | --- |
| `list_semantic_layers` | List the org's semantic layers (projects). Each id feeds `list_models` and chart building. |
| `list_models` | List a semantic layer's models with their dimensions and measures. Requires `projectId`. |
| `list_connections` | List the warehouse connections the caller can access. |
| `list_charts` | List saved charts, optionally filtered by `projectId`. |

## Query

| Tool | What it does |
| --- | --- |
| `run_query` | Compile and run a semantic exploration **without saving** — use it to validate a query and preview columns and rows before `create_chart`. Returns the SQL, columns, and rows, or a compile error. Requires `read`. |

Validating with `run_query` first is the recommended way to catch compile errors before you save anything.

## Write

These tools mutate data and require the `write` scope. All are additionally bounded by the caller's team and row-level-security access.

| Tool | Scope | What it does |
| --- | --- | --- |
| `create_chart` | `write` | Save a chart: a validated exploration plus a viz config. |
| `create_sheet` | `write` | Save a spreadsheet-modelling sheet (bound exploration, calc columns, cell formulas, or a multi-tab workbook). |
| `create_dashboard` | `write` | Create an empty dashboard; add tiles afterwards. |
| `set_dashboard_layout` | `write` | Replace a dashboard's tile layout on a 12-column grid (chart, text, and separator tiles). Replaces the whole layout. |
| `update_dashboard_interactivity` | `write` | Set a dashboard's interactivity spec: layered filters, content tabs, parameters, and default time grain. Replaces the whole spec. |
| `update_chart` | `write` | Update an existing saved chart's exploration and/or viz. |

> [!NOTE]
> `set_dashboard_layout` and `update_dashboard_interactivity` each replace the whole layout or interactivity spec, respectively. Fetch the current dashboard first if you are appending rather than rebuilding.

## Related

- [MCP overview](/docs/developers/mcp-overview)
- [Local MCP server](/docs/developers/mcp-local)
- [API reference](/docs/api-reference/overview)