MCP Server

Zeotap exposes its capabilities through a Model Context Protocol (MCP) server, enabling external AI tools to interact with your CDP programmatically.

Overview

The MCP server runs alongside the control plane and provides a standardized interface for AI agents to discover and use Zeotap tools. This allows integration with Claude Desktop, Cursor, and any other MCP-compatible client.

Available Tools

The MCP server registers 60+ tools spanning every CDP surface — schema inspection, audience and computed-attribute authoring, identity resolution, orchestrations, event streams, and direct warehouse access. Tools are grouped below by domain.

Schema

Tool	Description
`list_models`	List all data models in the workspace, including columns, primary keys, entity types, and source references.
`get_model`	Get detailed information about a specific model — columns, types, primary key, entity type, SQL, and column_config (sensitivity, PII types, aliases).
`list_relationships`	List all entity relationships (joins) connecting parent, related, and event models in the workspace.
`list_traits`	List all computed attributes (aggregated values) defined on parent or related models in the workspace.

Audiences

Tool	Description
`list_audiences`	List all audiences in the workspace, with name, parent model, filter tree, estimated size, and status.
`get_audience`	Get an audience’s full filter tree, parent model, estimated size, and sync status.
`estimate_audience_size`	Estimate the row count matching a filter tree against a parent model without creating an audience.
`validate_filter_node`	Validate a FilterNode JSON structure for correctness without executing it.
`compile_filter`	Compile a FilterNode tree into SQL and return the estimated size; useful before saving an audience.
`create_audience`	Create a new audience from a FilterNode tree. The filter is validated and compiled before saving.
`update_audience`	Update an existing audience’s name, description, filter tree, or status. Only provided fields change.

Computed Attributes

Tool	Description
`create_trait`	Create a new computed attribute on a parent entity model. Becomes a column on the materialized attribute table.
`trigger_trait_evaluation`	Trigger computed-attribute evaluation for a parent model and return a run ID for tracking.

Models & Schema (Write)

Tool	Description
`create_model`	Create a model from a warehouse table or custom SQL. Columns auto-infer; entity_type and primary_key_column are required.
`update_model`	Update an existing model’s name, description, columns, SQL, entity type, or status.
`update_column_config`	Set per-column sensitivity levels, PII types, display aliases, and enabled state.
`create_relationship`	Create a relationship (join) between two models, enabling event and relation conditions in audience filters.

Sources & Warehouses

Tool	Description
`list_sources`	List all configured data sources (input warehouses) in the workspace, with type, connection config, and status.
`introspect_source`	List all database schemas available in a source connection.
`list_tables`	List all tables in a specific schema of a source connection.
`list_columns`	List all columns in a specific table, including name, data type, and nullability.
`get_warehouse_context`	Get the full data model context — models, columns, relationships, computed attributes, event schema, and system tables. Use before writing warehouse SQL.
`query_warehouse`	Execute a read-only SQL query against a data warehouse. Honors access-policy filters.
`write_warehouse`	Execute a write SQL statement (INSERT, UPDATE, CREATE TABLE). DELETE, DROP, ALTER, TRUNCATE are blocked.

Destinations & Syncs

Tool	Description
`list_destinations`	List all configured destinations (output targets), with type, connection config, and status.
`create_destination`	Create a new destination (Snowflake, BigQuery, Databricks, webhook, etc.) for syncing audience or model data.
`list_syncs`	List all Reverse ETL syncs in the workspace — model, destination, field mapping, mode, schedule, and status.
`list_audience_syncs`	List all audience syncs — audience, destination, field mapping, mode, schedule, status, and Audience Boost config.
`create_audience_sync`	Create a new audience sync linking an audience to a destination, with field mapping, sync mode, and schedule. Optionally enables Audience Boost.
`trigger_sync`	Trigger a Reverse ETL sync to execute immediately. Returns the sync run ID.
`trigger_audience_sync`	Trigger an audience sync to execute immediately. If Audience Boost is enabled, runs dual pipelines and reports per-identifier metrics.

Identity Resolution

Tool	Description
`list_identity_graphs`	List all ID graphs in the workspace.
`get_identity_graph`	Get the full configuration of an ID graph — metadata plus models, identifiers, merge rules, limits, and probabilistic rules.
`create_identity_graph`	Create a new ID graph with full configuration in one call.
`update_identity_graph`	Update an ID graph’s metadata. Only provided fields change.
`configure_identity_graph_rules`	Configure models, identifiers, merge rules, limit rules, and probabilistic rules for an ID graph (partial update).
`delete_identity_graph`	Delete an ID graph permanently — definition, models, identifiers, rules, run history, and golden-record configs.
`list_identity_graph_runs`	List recent resolution runs for an ID graph (newest first) with status, timing, and metrics.
`get_identity_graph_run`	Get details for a specific ID graph resolution run.
`trigger_identity_graph_run`	Trigger or cancel an ID graph resolution run.
`explore_identity_graph`	Look up a resolved profile by an identifier value — returns the unified profile (`ss_id`) and all source rows.
`configure_golden_record`	Create or update the golden-record configuration (survivorship rules) for an ID graph.

Orchestrations

Tool	Description
`list_journeys`	List all orchestrations in the workspace. Each orchestration is a DAG of tiles defining a multi-step engagement flow.
`get_journey`	Get full details of an orchestration — tiles, edges, entry/exit criteria, schedule, status, and last run info.
`create_journey`	Create a new orchestration (starts in `draft` status).
`update_journey`	Update an orchestration’s name, description, tiles, edges, or schedule. Only provided fields change.
`delete_journey`	Delete an orchestration permanently. Warehouse tables created during activation are not auto-deleted.
`validate_journey`	Validate the DAG structure — cycles, dangling edges, missing tiles, schedule correctness.
`activate_journey`	Activate an orchestration (`draft`/`paused` -> `active`), provisioning warehouse tables and scheduling.
`pause_journey`	Pause an active orchestration. Existing member state is preserved.
`resume_journey`	Resume a paused orchestration. Evaluation continues from where it left off.
`trigger_journey`	Manually trigger an evaluation run for an active orchestration.
`list_journey_runs`	List recent evaluation runs for an orchestration with status, timing, and per-tile metrics.
`get_journey_run`	Get details for a specific orchestration run, including evaluation metrics.
`cancel_journey_run`	Cancel a pending or running orchestration evaluation.

Event Streams

Tool	Description
`list_event_keys`	List all event source write keys in the workspace, with name, value, status, topic, and last-used timestamp.
`get_event_volume`	Get hourly event volume metrics for the workspace over the last 7 days, grouped by event type and name.
`list_event_contracts`	List all event contracts — schemas, enforcement modes, and undeclared-field handling.
`list_event_contract_violations`	List event contract violations — type, field path, expected vs received values, sample event ID, count.
`list_event_forwarding_rules`	List event forwarding rules — destination, event filter, transformation, field mapping, consent, rate limit.
`list_event_transformations`	List event transformations — JavaScript functions that modify event payloads before forwarding.
`get_event_warehouse_config`	Get the event warehouse configuration — source ID, schema, staging bucket, and enabled status.

Utility

Tool	Description
`check_approval_status`	Check the status of a pending guardrail approval. Use this when a previous tool call returned `pending_approval`.

Authentication

The MCP server authenticates requests using API keys.

In the Zeotap UI, open API Keys from the left sidebar.
Click Create API Key, give it a name, and select the scopes your MCP client needs (see Scopes below).
Copy the generated key — it starts with sk_ and is shown only once. Store it securely; if you lose it, revoke and regenerate.
Configure your MCP client to send the key as a bearer token in the Authorization header.

The workspace your tool calls run against is derived from the API key itself — there is no separate workspace header.

Scopes

Each MCP tool requires a specific scope on the API key. Grant the minimum set your client needs:

Capability	Required scope
Read schema, models, relationships, computed attributes	`read:schema`
Read audiences and estimate sizes	`read:audience`
Create or modify audiences	`write:audience`
Read sync configuration	`read:sync`
Trigger sync runs	`trigger:sync`
Read connected sources	`read:source`
Configure or introspect sources	`write:source`
Read computed attributes	`read:trait`
Create or modify computed attributes	`write:trait`
Read identity / golden records	`read:identity`
Modify identity rules	`write:identity`
Configure destinations	`write:destination`
Create or modify models	`write:model`
Read orchestrations	`read:journey`
Modify orchestrations	`write:journey`
Trigger orchestration runs	`trigger:journey`
Read event streams	`read:event`
Run warehouse queries	`query:warehouse`

A tool call returns an authorization error if the matching scope is missing.

Integration with Claude Desktop

The Zeotap MCP server speaks JSON-RPC over HTTP, which Claude Desktop cannot connect to directly — it expects a stdio transport. Bridge the two with the mcp-remote proxy (no install needed; npx fetches it on demand).

Add the following block to your Claude Desktop claude_desktop_config.json:


{
  "mcpServers": {
    "zeotap": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.zeotap.com/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Replace YOUR_API_KEY with the key copied at creation time, then fully quit and restart Claude Desktop. The ${AUTH_HEADER} indirection keeps the Bearer prefix intact — passing the full header value directly inside args triggers a Claude Desktop bug that splits the string on whitespace.

The same mcp-remote config works for any MCP-compatible client that supports stdio servers (Cursor, Cline, etc.). Clients that already implement the MCP Streamable HTTP transport can connect to https://mcp.zeotap.com/mcp directly, sending the API key as Authorization: Bearer YOUR_API_KEY.

Available Resources

The MCP server also exposes resources that provide structured context to AI agents:

Resource	Description
`zeotap://schema/models`	All data models with columns, primary keys, entity types, and sensitive-column metadata for PII-safe querying.
`zeotap://schema/relationships`	Entity relationship graph — how parent, related, and event models connect via foreign keys.
`zeotap://schema/traits`	All computed attribute definitions in the workspace, with types and parent models.
`zeotap://schema/filter-node-spec`	The JSON Schema defining the FilterNode structure used for audience filter trees.