Using Adverity MCP

How the tools are named

Almost every tool name says what it does to your data:

*_search

Reads only. Never changes anything.

*_write

Changes data: creates, updates, or acts on a resource, such as fetch_write triggering and stopping fetches. Some resources name this tool after the operation instead, such as error_resolve, extract_requeue, and monitor_assign.

*_delete

Removes something. Often irreversible: see the note on each tool below for what a specific delete takes with it.

Three read-only tools predate the convention and keep their original names: get_warehouse_schema, query_warehouse, and read_docs.

Each tool also declares to your AI assistant whether it only reads data or can destroy it. Every *_delete tool declares itself destructive, and so do the write tools whose worst case is destructive: authorization_write, fetch_write, destination_write, data_mapping_write, user_write, error_resolve, and extract_requeue. Most AI assistants use that declaration to run read tools without interrupting you and to ask before running a destructive one, though the behavior depends on the client and on the tool permissions you have set. The confirmation step described below applies either way.

Confirmation for write actions

Every tool action that creates, changes, or deletes data is two-phase. The confirm parameter defaults to false, and the two phases are split between your AI assistant and you:

1. The assistant calls the action with confirm: false (the default) and receives confirmation_required: true together with a preview of the change. Fields such as will_create, will_update, or warning describe the impact of the change. Nothing is written at this point.

2. The assistant shows you the preview. After you approve it, the assistant calls the same action with confirm: true to apply the change.

You never set confirm yourself. It is the assistant’s signal that a human has approved this specific change, and the tool descriptions instruct the assistant to obtain that approval first. If you script against MCP without an AI assistant, your code follows the same contract: call, inspect the preview, call again with confirm: true. Triggering fetches (trigger, trigger_fixed, stop_job, retry_job in fetch_write) and updating OAuth tokens or refreshing metadata (update_token, refresh_metadata in authorization_write) follow the same two-phase pattern. The one exception is authorize in authorization_write, which returns the OAuth URL for a connection straight away, without a preview.

datastream_search, datastream_write, datastream_delete

Core tool for pipeline management and troubleshooting, capable of:

• Listing, creating, configuring, and deleting datastreams

• Viewing status, enabling or disabling pipelines, and filtering the datastreams that are scheduled for deletion

• Duplicating a datastream, including its source columns, schedules, and target bindings

• Viewing a datastream’s dashboard KPIs

• Exploring available connector types and their field options

• Reading and editing a datastream’s configured fields (the metrics and dimensions it collects) to add or remove columns without leaving your AI assistant

• Listing the transformations applied to a datastream, and attaching or detaching a transformation

datastream_tag_search, datastream_tag_write, datastream_tag_delete

Organizes datastreams with tags. List the tags in a workspace, list datastreams with their tags and filter them by tag, and read the tags of many datastreams at once. Create and rename tags, and assign or unassign up to 50 tags across up to 500 datastreams in one step. Assigning can create tags that do not exist yet. Creating, renaming, assigning, unassigning, and deleting a tag require explicit confirmation. For more information about tags, see Tagging datastreams in Management API.

authorization_search, authorization_write, authorization_delete

Manages authorizations for connected data sources (Google Ads, Facebook Ads, LinkedIn Ads, etc.). List every authorization in a workspace across all connection types in one call, or filter to a single type. Create new connections, check whether a connection is currently authorized, handle OAuth flows, manually update stored OAuth tokens, and refresh metadata from external APIs. Generate connection-invite links so someone else can authorize a connection on your behalf. Also manages which accounts an authorization is permitted to collect from — list, enable, or disable specific permissions and control the grant-all flag. Creating, updating, or deleting an authorization, updating its OAuth tokens, refreshing its metadata, generating an invite, and updating permissions or the grant-all flag all require explicit confirmation. Getting the OAuth URL to re-authorize a connection does not. Generating an invite emails the invitee unless you ask the assistant not to. Essential for preventing pipeline failures.

fetch_search, fetch_write, fetch_schedule_delete

Controls data collection jobs. Trigger fetches on demand or for a specific date range, monitor job status and import status, stop a running job, and retry a failed job within its existing job group. Triggering for a date range runs the scheduled fetches that fall in that range; a fixed-range fetch collects exactly the dates you give.

Each datastream collects data either on a schedule or with smart pulling. You can see which mode is active, switch between the two, and configure smart pulling here. You can also list a datastream’s schedules and delete a single schedule. On a datastream that uses schedules, change a schedule through datastream_write; on one that uses smart pulling, change its configuration here. Critical for troubleshooting and managing data collection.

monitor_search, monitor_assign

Lists custom data-quality monitors and shows which datastreams each one watches. Discover datastreams that could be assigned to a monitor, then assign or unassign them. Monitors themselves — creating, editing, or deleting a monitor — are managed in the Adverity interface; this tool only manages the monitor-to-datastream assignments.

error_search, error_resolve

Lists errors and their state, retrieves details for a single error by ID, retries failed operations, and acknowledges errors. Listing returns only errors that have not been acknowledged, unless you ask for acknowledged ones too. Retry and confirm actions require explicit confirmation and can be applied to a single error or to every error in the same error group. Before retrying a single error, the tool checks that its job can be retried, so it does not use up your data source quota on a retry that cannot succeed.

extract_search, extract_requeue

Lists and downloads data extracts from successful datastream executions. Download a specific extract or the latest one for a datastream; downloads return a preview of the first rows by default, and you can request the full content when you need the complete file. Read an extract’s stored metadata or its row data, and re-import existing extracts to their destinations without re-fetching the source data.

workspace_search, workspace_write

Lists workspaces, shows their structure and hierarchy, lists available storage locations, and shows a workspace’s dashboard KPIs. Also creates and updates workspaces. Creating a workspace needs a name and a storage location, so the assistant lists the available storage locations first. Updating can rename a workspace, change its storage, move it under another parent workspace, and change its other settings. Useful for multi-workspace environments. Creating or updating a workspace requires explicit confirmation. Workspaces cannot be deleted through MCP.

transformation_search, transformation_write, transformation_delete

Creates, lists, and edits transformations as part of datastream setup, and retrieves the schema of supported processing operations. Creating a transformation does not apply it to a datastream: the assistant attaches it in a second step with datastream_write. Only the name and description of a transformation can be edited after creation. Creating, updating, and deleting a transformation each require explicit confirmation.

mapping_table_search, mapping_table_write, mapping_table_entry_delete

Lists, retrieves, and updates mapping tables used for data harmonization. Manages individual mapping table entries — add, edit, or delete match-to-value pairs. All write operations require explicit confirmation because changes affect data harmonization for every datastream that uses the table. Read-only access to value tables — a separate reference resource used by transformations — is also available.

data_mapping_search, data_mapping_write, data_mapping_delete

Maps a datastream’s source columns to target columns — the Data Mapping step that controls which harmonized field each incoming column populates. List source and target columns, view a connector type’s default mapping, create new target columns, and map, unmap, bulk-replace, or copy a datastream’s column mappings from another datastream of the same connector type. Also lists, sets, and removes a connector type’s default mappings, which decide how newly discovered columns are mapped. All write and delete operations require explicit confirmation.

New target columns are created for the whole instance, with one of these data types: String, Long, Float, Date, DateTime, Boolean, Percentage, Currency, JSON, Formula, or Duration. A metric also takes an aggregation: SUM, AVG, COUNT, MIN, MAX, or NONAGG.

destination_search, destination_write, destination_delete

Creates and manages destinations — where harmonized data is delivered (BigQuery, Snowflake, Google Sheets, etc.). List available destination types and the fields each type requires, configure destinations, and manage which datastreams load into each destination, including whether each one is enabled and which table it writes to. Each destination type has its own required fields, so the assistant reads them before creating a destination. Creating, updating, and deleting a destination or a datastream assignment require explicit confirmation. The assistant does not ask for destination credentials in the chat; it sends you to enter them on the destination page in Adverity.

To control which source column populates which field, use data_mapping_write.

user_search, user_write, user_delete

Lists and manages instance users (identified by UUID). List users, retrieve a single user, and create, update, or delete users. Any assignable platform role can be set — see Managing user permissions. Creating, updating, and deleting a user require explicit confirmation.

notification_search, notification_write, notification_delete

Manages notification subscriptions across email, Slack, Microsoft Teams, and webhook channels. List, retrieve, create, update, and delete subscriptions, optionally scoped to specific datastreams or workspaces. Creating, updating, and deleting a subscription require explicit confirmation.

Each channel needs different details:

Email

A recipient email address that belongs to an existing Adverity user, and one or more notification topics.

Slack

An incoming webhook URL and one or more notification topics. A channel name is optional.

Microsoft Teams

An incoming webhook URL only. Topics and channel names are not supported.

Webhook

The URL to send events to, and one or more event names. You can store a signing secret, but payloads are not signed yet.

A new subscription does not send a test message. It fires the next time a matching event happens, such as a fetch job failing.

get_warehouse_schema

Queries the schema: lists the columns Adverity has loaded into a workspace’s warehouse, scoped to that workspace’s own tracked data. Call this before running a query to see what’s available.

query_warehouse

Interrogates the data: runs a read-only SQL query (SELECT or WITH only) against a workspace’s warehouse and returns the results. Results are capped at 100 rows and time out after 45 seconds — write narrow, aggregated queries rather than ones that scan everything. Any statement other than SELECT/WITH is rejected before it reaches the warehouse. Queries on the facts view are also rejected if they use SELECT * or do not filter on a date column.

read_docs

Answers questions about Adverity from the official documentation at docs.adverity.com. The default search mode returns short excerpts with links back to the source page; an alternative mode returns a synthesised written answer with its sources. A third mode returns Adverity’s implementation guides for specific connectors and topics. Read-only, with no confirmation required.

Use cases

To get the most relevant results, include timeframes, workspace names, or datastream names in your prompts.

Morning health check

Check the status of all pipelines without opening Adverity. Ask for failed datastreams, connections that are no longer authorized, and active errors — in a single prompt.

• “Show me all failed datastreams and any connections that are no longer authorized.”

• “Which datastreams are currently disabled?”

• “List all datastreams in the Marketing workspace.”

Troubleshooting a pipeline failure

Diagnose why a datastream stopped collecting data, review the error details, and retry failed jobs once you have identified the root cause.

• “Why did my Facebook Ads fetch fail? Show me the errors.”

• “What were the results of recent fetches for the Pinterest datastream?”

• “Retry this error, and every other error in the same group.”

• “Acknowledge this error so it no longer shows in the interface.”

Setting up a new data connection

Create a new datastream and configure its authorization through a guided conversation, without navigating the Adverity interface.

• “Help me set up a new Pinterest Ads datastream in the Marketing workspace.”

Adjusting what a datastream collects

Read a datastream’s current metrics and dimensions and add or remove fields through a guided conversation.

• “What fields is my Facebook Ads datastream collecting? Add adset_name and adset_id.”

Downloading data on demand

Retrieve the latest data extract for any datastream directly in your AI tool — useful for ad hoc analysis or when a scheduled report is delayed.

• “Download the latest Google Ads data extract.”

• “Get the most recent data extract for the LinkedIn Ads datastream.”

Checking connection status

Review which authorizations are currently authorized so you can re-connect any that have dropped before they cause pipeline failures.

• “Which of my authorizations are no longer authorized?”

• “What is the status of my Google Ads authorization?”

• “Re-authorize my Facebook Ads connection.”

Adding data processing to a datastream

Set up transformations for a datastream through a guided conversation — describe the processing you need and let the AI configure the steps.

• “Create a transformation that renames campaign_name to Campaign and attach it to the Facebook Ads datastream.”

Exploring workspaces and mapping tables

Understand your workspace structure and manage the mapping tables used for data harmonization.

• “What workspaces do I have access to?”

• “Which datastreams belong to the Production workspace?”

• “List all mapping tables.”

• “Show me all entries in the Country Codes mapping table.”

• “Add an entry to the Region mapping table: match ‘DE’, value ‘Germany’.”

Delivering data to a destination

Configure where harmonized data is delivered and how a datastream’s source columns map into each destination.

• “List my BigQuery destinations.”

• “Load the Google Ads datastream into my BigQuery destination.”

• “Map the Google Ads datastream’s source columns to my reporting schema.”

Staying notified

Set up email, Slack, or Microsoft Teams notifications for pipeline events, scoped to the workspaces or datastreams you care about.

• “Notify the #data-alerts Slack channel when any datastream in the Marketing workspace fails.”

• “List my current email notification subscriptions.”

Querying the warehouse

Explore the columns Adverity has loaded into a workspace’s warehouse and run read-only SQL against them without leaving your AI tool.

• “What columns are available in the Marketing workspace’s warehouse?”

• “Total spend by campaign for the last 7 days from the Marketing workspace warehouse.”