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.

Lists, paging and large results

Every list_* tool answers one page in the same shape, with the counts first so a client can tell a short page from a short collection:

{
  "total": 212,
  "returned": 50,
  "offset": 0,
  "limit": 50,
  "has_more": true,
  "next_offset": 50,
  "truncated": { "reason": "limit" },
  "fields": "summary",
  "detail": "Partial: 50 of 212 models shown. …",
  "items": [ { "id": "…", "name": "…", "column_count": 40 } ]
}

• Items are summaries by default — enough to pick one (id, name, status, the ids it points at, a few counts), with empty fields left out. Fetch one in full with the matching get_* tool, or pass fields: "full" (every field) or a list of field names.
• Find, don’t scan. Lists take limit, offset and the filters their schema lists, such as parent_model_id or status, and most take search (case-insensitive; every word must appear; an exact id or name ranks first). Run histories page newest first by offset only; a search sent to a list that does not take one is refused rather than ignored. A few small catalogues (blueprints, realtime destination types, asset providers) return whole items by default.
• A partial page says so. has_more is true whenever more matched; next_offset is where the next page starts (repeat the call with the same arguments and that offset); truncated.reason is limit (more items exist) or size (the page was ended early to stay within the response budget). A list whose source reads only the newest runs says so with window_exhausted and states no total.
• Large single objects (get_*) take fields to return only some sections. get_model pages its columns in place with column_search, column_limit and column_offset; a paged call reports how many there are in columns_page. An object too large for the budget comes back with _truncated naming what was cut: its largest lists are shortened from the end, each with a <field>_page whose next_offset you pass back as offsets: {"<field>": n} for the rest, and any other large value is replaced by an [omitted: …] marker you can read alone with fields.
• query_warehouse reports row_count, has_more_rows and, when rows or cells were left out, truncated with the reason.

A result is sized to about 8,000 tokens unless the client asks otherwise. The platform’s own agent sends the room left in its conversation as _response_budget_tokens, a reserved argument the server removes before the call is evaluated or audited.

Available Tools

The MCP server registers 107 tools, of which the 100 documented here are generally available — the rest seed demo data and are granted only to demo accounts. They span every CDP surface — schema inspection, audience and computed-attribute authoring, audience canvases, identity resolution, per-profile and per-record reads, realtime events, orchestrations, stores, event streams, and direct warehouse access. Tools are grouped below by domain.

Schema

Audiences

Audience Canvases

Computed Attributes

Models & Schema (Write)

Sources & Warehouses

Destinations & Syncs

Loaders

Stores

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

Identity Resolution

Profiles and Records

Resolved-profile tools read through an identity graph; the two record tools answer the same per-customer question in a workspace that has models and relationships but no graph.

Realtime Events

Orchestrations

Event Streams

Anomalies

Access to what anomaly monitoring and your alert rules found in the workspace. An MCP client cannot open or resolve an anomaly, but it can dismiss one whose change was intended, and acknowledge or mute an alert incident. These three tools need the write:alerting scope, are checked against your workspace’s guardrail policies, and are recorded in the audit log.

Utility

Authentication

The MCP server authenticates requests using API keys.

1. In the Zeotap UI, open API Keys under Governance in the left sidebar and select the AI API Keys tab.
2. 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.
3. Copy the generated key — it starts with sk_ and is shown only once. Store it securely; if you lose it, revoke and regenerate.
4. 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:

A tool call returns an authorization error if the matching scope is missing. A scope says what a key may ask for; the person who created the key still needs the role to do it. Writing to the warehouse needs Sources write access, changing a model’s column settings needs Models write access, and changing Stores and their feeds needs Stores write access (or Stores trigger access to run a feed). Reads follow the same rule: reading Stores needs Stores read access, the event tools need the matching Events read access (event keys, contracts, forwarding rules, transformations), the real-time event tools need Realtime events read access, the anomaly tools need Alerting read access, get_warehouse_context needs Models read access, query_warehouse needs Models write access (as the SQL editor does), and get_workspace_memory needs Agent read access. check_approval_status reads the agent’s own held calls, and anyone else’s only with access to the approvals queue. A key whose creator lacks the permission is refused with an error naming it, even when the key holds the scope.

You can only grant a scope your own role supports in the workspace: each scope needs at least one of the permissions behind its tools (for example write:warehouse needs Sources write access), and asking for one you do not have is refused with the permission it needs. The scopes stay in step with the person afterwards. On every request a key can use only the scopes its creator’s current role supports, so when someone’s role in a workspace narrows, their keys keep working with what the new role allows, and get their original scopes back if the role is restored. When they lose access to the workspace, every key they created there is revoked except serving keys, which belong to the workspace. The agent’s own session works the same way: it carries only the scopes the user’s role supports, so a Member’s agent can read but cannot change anything, and a conversation open when the user’s role narrows carries on with what the new role allows.

check_approval_status, get_workspace_memory, get_model_record and get_model_record_related are all covered by read:schema.

These scopes govern MCP tool calls only. None of them authorises an HTTP read: the Profile API takes its own svk_ serving key and the Membership API a public pk_ membership key, and an sk_ key is refused on both.

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. A person an access policy restricts cannot use query_warehouse at all, as in the SQL editor; otherwise 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.

query_warehouse lets the agent do what its user can do in the SQL editor, and follows the same rules. The person needs Models write access, as the editor does, so a member who can only view models cannot use it through the agent either. A person an access policy restricts cannot use it, in the editor or through the agent, because a free-form query returns the rows the policy hides. The agent then answers with the tools that apply those restrictions: record lookups, audience estimates and column profiles.

Results are masked before they reach the agent. A column that any model in the workspace marks redacted comes back as ***REDACTED***, and one marked sync-only or blocked is left out. So is any column whose name looks like personal data (an email, a phone number, a name), whether or not a model has marked it. The masking is by column name, so it does not survive a renamed or computed column; for a guarantee that does, give the warehouse connection a masked, read-only credential for interactive use. The warehouse then enforces the masking for the SQL editor and the agent alike.

The tool accepts exactly one SELECT statement. Every call, whether run, refused or failed, leaves an entry in the AI audit log with a fingerprint of the query, the columns returned and the row count, never the query text or the rows.

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: