Using Adverity MCP

This guide explains what you can do with Adverity MCP and the tools available.

Introduction

What is Adverity MCP?

Adverity Model Context Protocol (MCP) connects your AI assistant to Adverity, allowing you to monitor, configure, and control your data pipelines using natural language. Instead of navigating the Adverity interface, you can ask your AI tool to check authorization status, troubleshoot failed fetches, set up new datastreams, or download data extracts on demand.

What are the benefits of using Adverity MCP?

With Adverity MCP you can:

• Monitor your data pipelines without leaving your AI assistant.

• Get instant answers about datastream status, fetch history, and authorization status.

• Download data extracts on demand through simple prompts.

• Troubleshoot failed jobs by asking questions in plain language.

What can I do with Adverity MCP?

With Adverity MCP you can monitor, configure, and control your data pipelines:

• Create and manage datastreams, their configurations, and current status.

• Create and manage authorizations and check whether each connection is currently authorized.

• Configure which accounts an authorization is permitted to collect from.

• Trigger fetches, review job history, and troubleshoot errors.

• Download data extracts from successful datastream executions.

• Create, update, and explore workspaces and their storage.

• Create and manage transformations as part of datastream setup.

• Manage mapping table entries for data harmonization.

• Map datastream source columns to target columns.

• Create and manage destinations and their column mappings.

• List and manage instance users.

• Manage email, Slack, Microsoft Teams, and webhook notification subscriptions.

• Review data-quality monitors and manage which datastreams they watch.

• Look up answers from the official Adverity documentation.

Is my data secure?

Adverity MCP uses your existing MAPI key for authentication, so the AI assistant only has access to data permitted by your key’s permissions. All communication happens through secure, authenticated connections.

How do I connect my AI tool to Adverity MCP?

For connection instructions, see Setting up Adverity MCP.

Available MCP tools and use cases

The MCP server provides 16 specialized tools organized by domain. Tools that filter, create, or update within a workspace take its numeric workspace_id — the same id returned by manage_workspace’s list action — as the primary identifier; older stack_id and workspace_slug parameters, where a tool still exposes them, continue to work as aliases.

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.

Note

Changed: Triggering fetches (trigger, trigger_fixed, stop_job, retry_job in manage_fetch) and updating OAuth tokens or refreshing metadata (update_token, refresh_metadata in manage_authorization) now require confirmation, the same two-phase pattern used elsewhere in the MCP tools. Existing automations that call these actions must review the preview and pass confirm: true to apply the change.

manage_datastream

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

Note

Creating, updating, enabling, disabling, duplicating, and deleting a datastream, and changing its collected fields, require explicit confirmation. Enabling can create a default schedule and start recurring fetches; disabling stops all data collection.

Warning

Deleting a datastream through the MCP server is immediate and irreversible: the datastream and all of its data extracts are removed right away, with no scheduled-deletion grace period. The tool previews the datastream and the number of extracts that will be lost, and waits for your confirmation. To stop collection without losing data, disable the datastream instead.

manage_authorization

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 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. Essential for preventing pipeline failures.

Warning

Updating permissions replaces the full set: any account not included in the update is disabled for data collection. The tool previews exactly which accounts will be disabled and waits for your confirmation before applying the change. Use the list_permissions action to review available accounts first.

Warning

Deleting an authorization also deletes every datastream that uses it. Depending on your instance settings the removal is either scheduled for the nightly deletion run or applied immediately, and in both cases it cannot be undone. The tool previews the affected datastreams and waits for your confirmation; the result tells you which of the two happened.

manage_fetch

Controls data collection jobs. Trigger fetches on demand or for a specific date range, monitor job status, stop a running job, and retry a failed job within its existing job group. You can also list a datastream’s schedules here and delete a single schedule; changing a schedule is done through manage_datastream. Critical for troubleshooting and managing data collection.

Note

Triggering a fetch, stopping a job, retrying a job, and deleting a schedule all require explicit confirmation. If you delete a datastream’s only schedule, scheduled collection stops while the datastream itself stays enabled. Listing jobs without a date range returns only running and scheduled jobs; pass a start date to include finished and failed jobs too.

manage_monitors

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.

Note

Assigning and unassigning datastreams require explicit confirmation. Assigning is additive — existing assignments are kept.

manage_error

Lists errors and their state, retrieves details for a single error by ID, retries failed operations, and acknowledges errors. Retry and confirm actions require explicit confirmation and can be applied to a single error or to every error in the same error group.

manage_extract

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.

Note

Re-importing extracts requires explicit confirmation. Extracts in an inaccessible state (overwritten, deleted, or with personal data already removed) cannot be re-imported.

manage_workspace

Lists workspaces, shows their structure and hierarchy, lists available storage locations, and shows a workspace’s dashboard KPIs. Also creates and updates workspaces. Useful for multi-workspace environments. Creating or updating a workspace requires explicit confirmation.

manage_transformation

Creates, lists, and edits transformations as part of datastream setup, and retrieves the schema of supported processing operations. Only the name and description of a transformation can be edited after creation. Creating, updating, and deleting a transformation each require explicit confirmation.

manage_mapping_table

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.

Note

Mapping tables cannot be created or deleted through the API. To create a new table, use the Adverity user interface.

manage_data_mapping

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. All write operations require explicit confirmation.

Warning

Bulk-replacing column mappings is a full replacement: any source column not included is unmapped, which drops that field from everything downstream. The tool previews the change and waits for your confirmation.

manage_destinations

Creates and manages destinations — where harmonized data is delivered (BigQuery, Snowflake, Google Sheets, etc.). List available destination types, configure destinations, and manage the column mappings that control how source columns land in each destination. Creating, updating, and deleting a destination require explicit confirmation.

Warning

Deleting a destination is irreversible, and a full replace overwrites every field. The tool previews the change and waits for your confirmation.

manage_user

Lists and manages instance users (identified by ID). 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.

Warning

Deleting a user is irreversible and also removes their Data Conversations, Notebooks, and AI-assistant conversations, and drops their workspace memberships. To revoke access without deleting, deactivate the user instead.

manage_notifications

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.

Note

Webhook subscriptions are tenant-wide rather than scoped to a datastream or workspace, and validate against a separate, smaller set of event names than the topics used for email and Slack.

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 30 seconds — write narrow, aggregated queries rather than ones that scan everything. Any statement other than SELECT/WITH is rejected before it reaches the warehouse.

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. 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 for the Facebook Ads datastream that renames campaign_name to Campaign.”

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.”

• “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.”