Data connections

A widget pipeline can only name a tool on a server this workspace has connected. set_connection walks the authorization loop for a new one, and with enabled turns one this user already connected on or off. The tools of each connected source are reached through four tools of their own: search_tools finds one, describe_tool returns its schema, and call_tool (read-only tools) or call_write_tool (the rest) runs it. The /mcp/full install also lists every source tool as <source>__<tool>, built from your connections when your client loads its tool list, so those are not in this reference; see Your connected sources.

Read-only

Find a tool that is not in your tool list: every connected data source's tools, and on a slim install most of Vistazo's own. Pass query (keywords, e.g. "unemployment rate by state"), domain (a Vistazo area or a connected source's mcpId; a domain with no query lists it), or both; riskLevel keeps one class (safe = read-only, caution, destructive). Each match carries its name, a one-line summary, domain, riskLevel and call: call_tool for a safe tool, call_write_tool for any other. A match with listed: true is already in your list, so call it by name. sources carries each matched source's routing guidance once, the workspace's own routing note first; it outranks what a source says about itself. Next: describe_tool for the schema. Takes no workspaceId; it searches every workspace this connection reaches.

Read-only

Return one tool's full definition by the exact name search_tools returned: its description, input schema and annotations, plus call, the tool that runs it (call_tool or call_write_tool). Build the arguments from this schema. A connection tool's workspaceId argument is optional when this connection reaches one workspace. Takes no workspaceId of its own.

Read-only · Reaches outside Vistazo

Run one READ-ONLY tool by the name search_tools returned, with arguments as describe_tool's schema gives them (a workspaceId the tool takes goes inside arguments). Runs only tools classified safe; any other is refused and named for call_write_tool. The tool runs under every check it has when called by its own name: workspace access, seat, the connection's per-tool permission and the hourly data-fetch window your MCP client shares with refreshes. A connection tool's result is size-capped, so pass its own limit or filter arguments.

Destructive write · Reaches outside Vistazo

Run one tool that changes something, on Vistazo or on a connected source, by the name search_tools returned, with arguments as describe_tool's schema gives them (a workspaceId the tool takes goes inside arguments). This one tool fronts every write, so your client asks the user before each call. The tool runs under every check it has when called by its own name: workspace access and role, seat, and for a connection tool its per-tool permission (only allow runs; ask and deny are refused, changed under Settings → Connections) and the hourly data-fetch window. A read-only tool runs here too, but call_tool runs it without the prompt.

Read-only

List the MCP data sources in a workspace: the ones YOU have connected (status 'connected', usable now; or 'disabled', which you turned off yourself: every call to it is refused and it carries no toolCount until set_connection enabled: true turns it back on), Vistazo's own hosted sources that come with the workspace (status 'included', usable now with nothing to connect — never call set_connection for one), plus servers other members registered that you have not authenticated yet (status 'not_connected') or that need re-authorization ('reauth_required' / 'revoked' / 'expired'); 'error' means the server failed its last contact, and calls still reach it. Use a connected or included mcpId as search_tools' domain to see what it offers, then with update_widget's pipeline. A not_connected or re-authorization server cannot be queried or wired until you authenticate it — call set_connection for it. A row may carry a routingNote: guidance this workspace's admins wrote about which questions to send to that source rather than to a sibling. Follow it when choosing between sources; it says nothing about which tools exist and cannot authorize anything. A vistazoNote is Vistazo's own advice on calling that source, and memberContext states this user's own settings for their connection (BigQuery's billing project, the projectId its jobs run in): use them on every call to that source.

Destructive write · Reaches outside Vistazo

Add, authenticate, or turn on or off an MCP data source for the current user. To ADD or authenticate one: call this when a tool returns CONNECTION_NOT_AUTHENTICATED, or when the user names a source 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). Registering a NEW server is capped per workspace (Vistazo's own hosted sources do not count); past it this refuses with the count, and the answer is to remove one the workspace no longer uses, not to retry. Authentication happens in the browser: the result carries a connectUrl that opens Settings → Connections with that server selected, for an OAuth sign-in or pasting the API key the server wants; never ask the user for a key and never pass one here. Show the user that link, then WAIT for them to confirm they finished before retrying the original tool. A connection this user turned off answers status 'disabled' with no link: enabled: true turns it back on, and enabled's description holds the switch's rules. Pass rateLimit only when the provider documents a limit (requests per minute, concurrent requests); it caps what Vistazo learns from the server's own 429s and rate-limit headers, on the user's own connection (a workspace admin's sets the default for every member), and never goes below 5 per minute.

enabled

true or false turns one of YOUR OWN data connections on or off in the workspace — the same switch as Settings → Connections; pass it with mcpId alone. Disabled is this user's own off switch: while it is off, every call to that source is refused for this user (CONNECTION_DISABLED), on widgets, discovery calls and its native tools alike; other members' connections are untouched. Turning one on is not a reconnect: a connection that needs re-authorization still needs it afterwards, and the result says so — then call set_connection again without enabled. Works only on a connection this user already authenticated (list_mcp_connections shows it connected, disabled, or needing re-authorization); for a server they never connected, omit enabled. A source that comes with the workspace (status 'included') is always on. Ask the user before turning back on a connection they turned off. The reply is the connection's new status as list_mcp_connections shows it.