> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vistazo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Data connections

> List and add the MCP servers a workspace's widgets can read from.

A widget pipeline can only name a tool on a server this workspace has connected. `add_connection` walks the authorization loop for a new one.

| Tool                                              | What it does                    |                |
| ------------------------------------------------- | ------------------------------- | -------------- |
| [`list_mcp_connections`](#list_mcp_connections)   | List data connections           | Read-only      |
| [`add_connection`](#add_connection)               | Add data connection             | Additive write |
| [`list_connection_tools`](#list_connection_tools) | List connection tools           | Read-only      |
| [`call_connection_tool`](#call_connection_tool)   | Run a read-only connection tool | Read-only      |

## list\_mcp\_connections

`Read-only`

List the MCP data sources in a workspace: the ones YOU have connected (status 'connected', usable now) plus servers other members registered that you have not authenticated yet (status 'not\_connected') or that need re-authorization ('reauth\_required' / 'revoked'). Use a connected mcpId with list\_connection\_tools to see what it offers, then with set\_widget\_pipeline. A not\_connected / degraded server cannot be queried or wired until you authenticate it — call add\_connection for it.

## add\_connection

`Additive write` · `Reaches outside Vistazo`

Register and/or authenticate an MCP data source for the current user. Call this when a tool returns CONNECTION\_NOT\_AUTHENTICATED, or when the user names a data source that list\_mcp\_connections shows as not\_connected. Pass the mcpId of an existing workspace server, or a new mcpId + serverUrl (+ displayName) to register a server the workspace has not used before — the record is created for the whole workspace and its URL is validated (public https only in production). Authentication itself happens in the browser: the result carries a `connectUrl` that opens Vistazo Settings → Connections with that server selected so the user can authorize it. Show the user that link, then WAIT for them to confirm they finished — do not retry the original tool until they say so; OAuth completes out of band.

## list\_connection\_tools

`Read-only` · `Reaches outside Vistazo`

List the tools a connected MCP data source exposes — name, description, input schema, and a risk level (safe | caution | destructive). Use this to choose a tool and build its arguments when configuring a widget. "safe" tools are read-only and fine to refresh automatically; "caution"/"destructive" tools should not be wired to auto-refreshing widgets. To try a safe tool once before wiring it (resolve an id, inspect the response shape), use call\_connection\_tool.

## call\_connection\_tool

`Read-only` · `Reaches outside Vistazo`

Run ONE tool on a connected MCP data source directly and return its result. The target is a data source THIS WORKSPACE registered and the caller authenticated (list\_mcp\_connections lists them, list\_connection\_tools enumerates what each one offers) — never an arbitrary URL. The discovery lane for building pipelines: resolve ids the schemas tell you not to guess (search/lookup tools), check coverage, or fetch a small sample to see the exact response shape before authoring a transform. Only tools classified 'safe' (read-only) may be called; caution/destructive tools are refused. Persists nothing — no widget, dashboard, or pipeline is touched — and results are size-capped, so keep sample fetches small (use the tool's own limit/filter arguments). The result is unwrapped exactly as a pipeline transform would receive it.