Using Adverity MCP (Beta)

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

Note

This feature is in beta available to selected customers. Reach out to your Account Manager for more details.

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, and Microsoft Teams notification subscriptions.

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 specialized tools organized by domain. Write operations follow a two-phase pattern: the tool first previews the change and applies it only after you explicitly confirm.

manage_datastream

Lists, creates, and configures datastreams. View status, enable or disable pipelines, and explore available connector types and their field options. Read and edit a datastream’s configured fields — the metrics and dimensions it collects — to add or remove columns without leaving your AI assistant. Core tool for pipeline management and troubleshooting.

Note

Creating, updating, enabling, and disabling 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.

manage_authorization

Manages authorizations for connected data sources (Google Ads, Facebook Ads, LinkedIn Ads, etc.). Create new connections, check whether a connection is currently authorized, handle OAuth flows, and refresh metadata from external APIs. Also manages which accounts an authorization is permitted to collect from — list, enable, or disable specific permissions and control the grant-all flag. Updating permissions or the grant-all flag requires 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.

manage_fetch

Controls data collection jobs. Trigger fetches on demand or for a specific date range, monitor job status, and stop running jobs. You can also review a datastream’s fetch schedule here; changing a schedule is done through manage_datastream. Critical for troubleshooting and managing data collection.

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; request the full content when you need the complete file.

manage_workspace

Lists workspaces, shows their structure and hierarchy, and lists available storage locations. 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, create new target columns, and map, unmap, or bulk-replace a datastream’s column mappings. 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, and Microsoft Teams. List, retrieve, create, update, and delete subscriptions, optionally scoped to specific datastreams or workspaces. Creating, updating, and deleting a subscription require explicit confirmation.

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