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 80+ tools spanning every CDP surface — schema inspection, audience and computed-attribute authoring, audience canvases, identity resolution, orchestrations, stores, 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.

Audience Canvases

Tool	Description
`list_audience_canvases`	List all audience canvases in the workspace, with parent model, audience count, and when each was last published.
`get_audience_canvas`	Get a canvas’s draft nodes and edges, its published version, and its parent model.
`validate_canvas_changeset`	Validate proposed nodes and edges before saving or publishing — cycles, unwired tiles, missing audience names.
`create_audience_canvas`	Create a new, empty canvas on a parent model, optionally routed through an identity graph.
`update_canvas_draft`	Replace a canvas’s draft nodes and edges. Autosaved and visible in the editor; nothing is published yet.
`publish_audience_canvas`	Publish the current draft, compiling every Create Audience tile and materialising the audiences it owns.

Computed Attributes

Tool	Description
`create_trait`	Create a new computed attribute on a parent entity model; it is computed on read wherever it is referenced.
`update_trait`	Update a computed attribute’s name, description, configuration, result type, or status. Only provided fields change; setting the status publishes or unpublishes it.
`trigger_trait_evaluation`	Trigger an optional manual refresh of computed attributes for a parent model and return a run ID for tracking. Not required — computed attributes are computed on read.

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. `SELECT` only, capped at 500 rows.
`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.

Stores

Store tools are only available on workspaces where Stores is enabled.

Tool	Description
`list_stores`	List all stores in the workspace, with primary index and status.
`get_store`	Get a single store by ID.
`list_store_feeds`	List the feeds attached to a store — model, field mapping, deletion behaviour, schedule, and last refresh.
`list_store_feed_runs`	List a feed’s recent refresh runs, with rows added, updated and deleted, status, and any error.
`create_store`	Create a store. The primary index is the row key and cannot be changed afterwards.
`archive_store`	Archive a store. Its feeds stop running.
`create_store_feed`	Attach a feed that mirrors one parent-entity model into the store.
`update_store_feed`	Rename, reschedule, or remap a feed, or change its deletion behaviour.
`delete_store_feed`	Delete a feed. Data already written to the store is not removed.
`trigger_store_feed`	Refresh a feed immediately. Returns the run ID.
`resume_store_feed`	Resume a feed that auto-paused after repeated failed refreshes.

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 AI API Keys under Governance in the left sidebar.
Click Create API Key, give it a name, and select the scopes your MCP client needs (see Scopes below). A key needs at least one scope.
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 models, relationships, and warehouse context	`read:schema`
Read computed attributes	`read:trait`
Create or modify computed attributes	`write:trait`
Read audiences and canvases, estimate sizes, validate filters	`read:audience`
Create or modify audiences, canvases, and audience syncs	`write:audience`
Read syncs and destinations	`read:sync`
Trigger sync runs	`trigger:sync`
Read connected warehouses and introspect their tables and columns	`read:source`
Create or modify models and relationships	`write:model`
Configure destinations	`write:destination`
Read identity graphs and resolved profiles	`read:identity`
Modify identity graphs and golden-record rules	`write:identity`
Read orchestrations	`read:journey`
Modify orchestrations	`write:journey`
Trigger orchestration runs	`trigger:journey`
Read event streams	`read:event`
Run read-only warehouse queries	`query:warehouse`
Run warehouse write statements	`write:warehouse`
Read stores and feeds	`read:store`
Create or modify stores and feeds	`write:store`
Trigger or resume feed refreshes	`trigger:store`

A tool call returns an authorization error if the matching scope is missing. check_approval_status is covered by read:schema.

Two scopes are worth granting deliberately rather than as part of a broad selection: query:warehouse lets a client read any table the warehouse connection can reach, and write:warehouse lets it write to that warehouse directly. Unlike the other scopes, neither is bounded to a resource Zeotap manages. Access policies are given to the client as context to apply, not enforced on the query itself, so a warehouse scope is only as narrow as the warehouse credentials behind it. Grant them to clients you would trust with those credentials, and use guardrails to constrain what the agent does with them.

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.