Reference / Authoring

list_connections

List the data connections you can author against, warehouses and the uploaded-file source. The eleven fields, why it takes no arguments, errors and scope.

Lists the data connections you can build a refreshable dashboard against, so you can find the connection id to pass to introspect_schema, explore_data, validate_cube_sql, or source.connection in the spec you publish.

Two kinds of row appear here: the workspace's warehouse connections, and its one uploaded-file source once it has one. Warehouse connections are created and managed in the Dashies web app, never through MCP; the uploaded-file source is the other way round, created by create_file_upload the first time a file is uploaded to the workspace.

Behaviour hints for clients: read-only, not open-world.

Parameters

This tool takes no parameters. Its input schema declares no properties at all, and that is deliberate: which connections you see is decided by how the MCP connection was authorized, not by an argument. See Scope below.

Returns

Eleven fields per connection, every one of them always present. Seven describe how the connection was configured, three describe what actually happened to it, and one says whose it is:

Field	Meaning
`id`	The connection id you pass as `connection`.
`kind`	Always `warehouse`, including on the uploaded-file source. It says where the row is stored, not that the row is a warehouse. Read `engine` to tell them apart.
`label`	The name you gave it in the web app, or `Uploaded files` on the uploaded-file source.
`engine`	What the connection runs on, such as `postgres` or `snowflake`. No list is given here, because an engine list goes stale on the merge that adds the next engine. The one value worth knowing by name is `file`: that row is the workspace's uploaded-file source, not a warehouse.
`status`	`pending`, `active`, `error` or `disabled`. Only `active` can author.
`last_verified_at`	When a Test last succeeded.
`last_error`	A classified token such as `connection_auth`, never raw driver text.
`health_state`	What real refreshes observed. `null` until something has observed it.
`health_error`	The classified reason behind `health_state`.
`health_source`	What made that observation.
`shared_sample`	`true` on the shared "Dashies sample data" connection, `false` on every connection of your own.

No password, secret, Vault reference or internal object name is ever included: the projection is an allowlist, not a filter.

The uploaded files row, and its `uploads`

Once a workspace has uploaded a file, its uploads share one connection, labelled Uploaded files. That row, and no other, carries one more field, uploads: the workspace's newest uploads, each with its upload_id, filename, status, bytes, sha256, failure, created_at, ready_at and table_count. The text lists them indented under the row. uploads is null when they could not be read just now, which is different from an empty list. get_file_upload reads one in full.

The shared "Dashies sample data" connection

One connection is listed in every space, last, with shared_sample: true: a read-only Snowflake warehouse Dashies provides, holding synthetic data, usable on every plan. On a trial or paid plan a dashboard built on it refreshes on a schedule like any warehouse; on a free plan its numbers are built into the page and move only when it is republished, because a cadence and an on-demand refresh both need a paid plan. Its line in the text carries SAMPLE DATA: shared by Dashies, synthetic, read-only. Build on it exactly as on any warehouse, say that the numbers are sample data, and never try to edit, test or delete it - it belongs to nobody, and every such call is refused with the same not-found an unknown id gets.

status and health_state are independent, not two views of one thing

status is what a Test concluded. health_state is what a real refresh observed. status: active beside health_state: failing is a normal and meaningful reading, not a contradiction: the connection is configured and enabled, and the last refresh failed at the connection level. Never collapse them.

Data connections in the "acme-co" workspace (2):
- Analytics Postgres [7a1e...-...] | engine: postgres | status: active | last verified: 2026-07-29T04:12:09Z
- Snowflake Prod [0c22...-...] | engine: snowflake | status: error | last verified: 2026-07-20T11:03:44Z | last error: connection_auth | last observed: failing (connection_auth)

Pass a connection's id as the `connection` argument to introspect_schema / explore_data / validate_cube_sql, and as `source.connection` in the spec you publish with publish_dashboard, to author a dashboard that refreshes from it. Only 'active' connections can be used.

BEGIN_JSON
{"count":2,"connections":[{"id":"...","kind":"warehouse","label":"Analytics Postgres","engine":"postgres","status":"active","last_verified_at":"...","last_error":null,"health_state":null,"health_error":null,"health_source":null,"shared_sample":false}]}
END_JSON

The | last observed: <state> segment appears only when something has actually observed the connection, so one that has never refreshed prints nothing there. With a classified reason it renders last observed: failing (connection_auth).

The header names the space

Every listing heads Data connections in the "<slug>" workspace (N):, or Data connections in this workspace (N): when the authorization carries an id but no slug.

It said Warehouse connections until 2026-09-20

The uploaded-file source is in this listing by design, and it is not a warehouse, so the header was describing one of its own rows wrongly. Its kind column does say warehouse; that is where the row is stored. Issue #3404.

There used to be a second header, and why it went

A grant naming no workspace headed its listing Your personal warehouse connections (N):, and this page argued the word personal there was load-bearing: the bare form reads as "all of yours", and an author on an older authorization who read it that way built against a connection and was refused at the binding call by a deliberately ambiguous message they could not diagnose. That was issue #818.

The header is gone with the listing. The warning it carried is not needed, and not merely stale: by the time it was removed, the only row that branch could still return was the shared sample, which is listed in every space and is not scoped to a person at all, so the sentence was false about the one row it could describe. A grant naming no workspace is now refused before any listing happens.

Empty state

Both lines:

There are no data connections in the "acme-co" workspace.
Connect a warehouse from the Dashies web app (Data sources) with the "acme-co" workspace as the active space, or upload a CSV or Excel file with create_file_upload, to author dashboards that refresh from it. The built-in 'self' connection (Dashies' own no-PII metrics) is always available without a connection id.

An authorization locked to a workspace whose slug is unavailable says this workspace wherever those lines say the "acme-co" workspace. There was a second empty state, for a grant naming no workspace; that grant is refused now.

self is never listed

The built-in self connection is always available and never appears here. Use it by passing connection: "self" or by omitting the argument entirely. An empty list therefore means "no connections of your own", not "nothing to author against".

Errors

Condition	Text
The authorization names no workspace	`Data sources belong to a workspace, and this MCP connection is not authorized for any workspace, so there is no space whose data sources it can list. Re-authorize it and choose the workspace it should use.`
The read failed	`Could not list your connections: <err>`

Scope

The read space comes from the grant alone. A workspace authorization lists that workspace's connections, whoever on the team created them. An authorization that names no workspace is refused, with the sentence under Errors above: a data source belongs to a workspace, so there is no space whose connections such a grant could list.

A connection belongs permanently to the space it was created in and cannot be moved, so a connection you can see in one space is simply absent from the other. Inside a workspace, a member holding a creator seat can use a connection to author. A view-only role cannot: reading a connection's schema or running a statement against it needs a creator seat, so introspect_schema, explore_data and validate_cube_sql refuse and say so. Only the member who added it and workspace admins can rename, re-test, rotate or delete it.

Check it worked

If the list is empty but you expect entries, check which space you authorized for: re-authorizing and choosing the workspace is what switches the read space, and there is no argument that overrides it. The header tells you which space you got, so read it rather than inferring from the contents.

If an entry shows status: error, test the connection in the web app before authoring against it, since an inactive connection is refused at the point of use rather than here. If it shows status: active with last observed: failing, the configuration is fine and the last real refresh was not: read get_refresh_status on a dashboard bound to it for the run that failed.