MCP for AI agents

Connect Claude, Cursor, ChatGPT, Gemini, or another MCP-compatible assistant to Infinite Audience. Your team can explore customer signals, shape segments, and run approved workflows from a conversation.

Understand the objects

A segment defines a population: filters, an uploaded identity list (matched), a lookalike (similarity), or a scored model (propensity). An audience combines saved segments for delivery. It can mix segment types and has no subtype or primary segment. A campaign organizes audiences; an audience belongs to at most one campaign. A delivery is one output operation and its downloadable files.

Explore, save, and deliver

1. Call get_field_catalog; its default purpose: "filter" shows audience filter fields. Use purpose: "enrichment" to browse all output fields. Read filterable, groupable, operators, descriptions, and coded enum_values before constructing filters. Follow next_cursor for more fields. For large value lists, pass field_name and the field’s values_next_cursor as value_cursor. feature_store fields support enrichment outputs; they are filterable only when the catalog says so. Pricing is returned only with include_pricing: true.
2. Use discovery_count to size an unsaved population, and discovery_lookup for up to 25 non-PII sample rows. Optional fields selects the sample columns. Supply exactly one population source: filters, filter_groups, segment_id, audience_id, or segment_ids with set_logic. Counts are records, not prices; obtain customer pricing from a delivery quote.
3. Save the same filters or filter_groups with create_segment(subtype="filter"), then compose it with create_audience. Creation saves a ready definition, not an automatically computed count. Omit the legacy count_snapshot and call count_segment to compute the saved population. Included segments use union (any segment) or intersection (every segment). Excluded segments are always subtracted. A positive record_limit needs State, City, or ZIP Code geography that narrows every OR branch to at most 100 ZIP3 regions. Narrow the geography or omit the limit if the API rejects it.
4. Use list_segments, list_audiences, or list_campaigns to find IDs; pass next_cursor back as cursor. Detail tools retrieve a particular object’s definition, composition, or linked audiences. get_audience includes campaign_id and constituent filters. Lists and detail tools remain separate because discovery and inspecting one object are different operations.
5. patch_segment changes a name or filter definition; patch_audience changes a name or composition. count_segment updates a saved segment’s count, while recount_audience updates a composed audience’s count. Neither is a purchase. refresh_segment and refresh_audience refresh data and can start workflows; they are distinct from counting.
6. Call quote_delivery, show the exact population and cost to the user, and obtain approval before calling deliver_audience. Read the quote and tool input schema for its identifiers and cost ceiling. Poll using get_delivery or wait_for_delivery. Signed download links last 24 hours; artifact retention is a separate expiry.

Filter format

{
  "filters": [
    { "field": "zip5", "op": "=", "value": "10001" },
    { "field": "age", "op": ">=", "value": 35 }
  ]
}

Flat filters are AND-combined. filter_groups uses objects with id, combinator (AND or OR), and a filters array. Conditions within a group use AND; between groups, AND binds more tightly than OR. The first combinator is ignored. IDs prefixed _exclude:: subtract a group. Use one filter representation per request. Saved segment responses always return the active definition as filter_groups, including a single AND group for a flat input. Discover income fields and their coded values in the catalog.

Text comparisons are exact by default. For a STRING field, add "text_comparison": "case_insensitive" to a filter when capitalization should not matter; add "trim_whitespace": true when leading or trailing spaces should not matter. Both settings apply to the stored value and your input for =, !=, IN, NOT IN, and LIKE. For ARRAY<STRING> fields, they apply to each element for ARRAY_CONTAINS and ARRAY_CONTAINS_ANY. They can be combined. They do not change internal spaces, punctuation, accents, or missing values. For example, {"field":"city","op":"=","value":"virginia beach","text_comparison":"case_insensitive"} can match a differently capitalized city. Use exact field_name values from the catalog; the comparison setting applies to values, not field names. Coded enum values still come from the catalog. If multiple codes collapse to one value under case folding or trimming, use text_comparison: "exact" and the exact published code.

Invalid filters return a 400 error with a code, message, issues array, and next_step. Each issue identifies a path such as filter_groups[0].filters[0].field; unknown fields may include a few suggestions from the current public catalog. Correct the indicated filter using get_field_catalog or GET /v1/catalog/fields before submitting again. A temporarily unavailable catalog is a separate retriable service error.

Coverage means the published fraction of non-null values, not the fraction of flags that are true. Array coverage is null until a non-empty array metric is available. A null coverage value does not mean zero coverage.

Interpret results and recover

• active means an object is ready for its next supported operation. record_count: null means unknown, not zero. A returned count_state: "available" does not guarantee that a stored count is fresh; call count_segment or recount_audience when current population size matters.
• discovery_count counts records and does not purchase or export them. With segment_id it also attempts to save the new count; use inline filters for an unsaved preview. Count-only is the default; the total population must contain at least 50 records; smaller demographic buckets do not block the report.
• For a privacy-floor error, broaden the total population to at least 50 records. Switching to count-only does not bypass that minimum. Individual demographic buckets may be smaller.
• For group_by and crosstab dimensions, choose fields with groupable: true; a field can be filterable without supporting grouping. FIELD_NOT_GROUPABLE means select another dimension, not retry the same request.
• Flat filters are AND-combined. BETWEEN includes both endpoints. IN takes an array of alternatives; NOT IN excludes them. ARRAY_CONTAINS takes one value; ARRAY_CONTAINS_ANY takes alternatives. LIKE uses % for any sequence and _ for one character. Use only the operators published for that field. Coded enum_values go in requests; value_labels are for display.
• Optional next_actions give public tool names and arguments using returned IDs and the current grant. They are suggestions, not executed actions or user consent. Review mutations and charges before following them.
• Lists report one page. Use the returned next_cursor as cursor; match-run and file-job history also support a legacy before timestamp, but cursor preserves timestamp ties. An empty page is valid. Keep filters unchanged while paging.
• Use get_segment for a segment, get_audience for an audience, and get_delivery with its returned audience_id and delivery_id. Do not assume a match_id equals an audience ID. To deliver a segment, first compose an audience from its ID.
• For uploads, create a matched segment and HTTP PUT the raw file bytes to the returned signed URL (no MCP bearer token). Use the content type for your format: text/csv, application/avro, application/json, or application/x-ndjson. Then analyze, present mappings and submit the complete approved mapping set. Cancellation retains the segment; inspect or archive it afterward. Do not wait for matching before confirming the mappings.
• A wait timeout does not cancel or fail the operation. Inspect the existing object/workflow instead of repeating creation or delivery. A paused gate requires the user’s choice from the returned options.
• refresh_audience refreshes one selected member segment and the audience version. It does not refresh every member automatically. Recount after the necessary member work finishes.
• quote_delivery returns an expected USD estimate and a maximum estimate; present both when different. Account usage amounts documented as cents must be divided by 100 for dollar display. Pending usage estimates are not finalized invoices.
• get_workflow_status and wait_for_workflow may synchronize a recorded workflow failure onto the segment and send its configured failure notifications. Inspection does not restart the workflow.

Use the catalog’s canonical field_name in saved definitions. ZIP5 also accepts the input aliases zip, zip_code, and postal_code; responses use zip5. The state field publishes two-letter codes and full names; either can be supplied, and responses use the code. No demographic criteria shorthand is supported.

Archive and restore

External agents operate on one object per mutation. Use archive_segment or archive_audience with restore: true to restore an archived object; list with include_archived: true to find it. Campaigns use update_campaign with status: "archived" or "active". Archival preserves composition and history.

The focused MCP catalog replaces delete_audience with reversible archive_audience and removes bulk create/update/archive/delivery tools. REST and SDK bulk endpoints remain supported for application integrations. Refresh the client’s tool list after upgrading. Do not automatically replay failed creation, definition changes, workflow responses, or delivery operations: inspect the object’s current state first.

Tool failures return isError: true with a JSON body containing error, code, and message. Use code for recovery decisions and show message to the user. Protocol/input-schema validation errors can be reported by the MCP client before the handler runs.

Connect the server

Server URL:

https://mcp.infiniteaudience.ai/mcp

Infinite Audience supports OAuth discovery, so compatible clients can open a browser sign-in and manage credentials for you. Add the server with one of the setups below, then choose Authenticate or Sign in when your client prompts you.

OAuth is the recommended connection for an interactive AI workspace. Sign in, review the requested scopes, and let the client renew the connection. Do not paste an API key into a hosted assistant or put a one-hour bearer token in a shared MCP configuration file.

Choose your AI workspace

ChatGPT / Codex

ChatGPT and Codex use separate connection setup. In ChatGPT, enable Developer mode under Settings → Security and login, then open ChatGPT Plugins, add a connection, and enter the HTTPS server URL above (including /mcp). Availability depends on your account and workspace policy. Complete the OAuth sign-in when prompted. See OpenAI’s connection guide.

Add the server from Codex CLI:

codex mcp add infinite-audience --url https://mcp.infiniteaudience.ai/mcp

Codex CLI and its IDE extension share configuration; ChatGPT does not use this local Codex file. The equivalent ~/.codex/config.toml entry for Codex is:

~/.codex/config.toml

[mcp_servers.infinite-audience]
url = "https://mcp.infiniteaudience.ai/mcp"

Then run codex mcp login infinite-audience --scopes discovery to request the narrower initial grant. If you also want usage, balance, and top-up status, request --scopes discovery,account-read instead. See the official OpenAI MCP guide.

Claude

Claude Code can add the remote server from the command line:

claude mcp add --transport http infinite-audience https://mcp.infiniteaudience.ai/mcp

Open /mcp, select Infinite Audience, and complete sign-in. Recent Claude Code versions also support claude mcp login infinite-audience. See Anthropic’s MCP guide.

Cursor

Add the server globally in ~/.cursor/mcp.json, or use .cursor/mcp.json inside one project:

~/.cursor/mcp.json

{
  "mcpServers": {
    "infinite-audience": {
      "url": "https://mcp.infiniteaudience.ai/mcp"
    }
  }
}

Open Cursor’s MCP settings, enable the server, and complete OAuth when prompted. See Cursor’s MCP guide.

Antigravity

In Antigravity’s Agent pane, open MCP Servers → Manage MCP Servers → View raw config, then add this server to the configuration shown there:

mcp_config.json

{
  "mcpServers": {
    "infinite-audience": {
      "serverUrl": "https://mcp.infiniteaudience.ai/mcp"
    }
  }
}

Refresh the server list and attempt sign-in. Google documents this serverUrl form for a remote server, but Infinite Audience’s first-party OAuth flow still needs an end-to-end Antigravity test; do not assume it works until verified. See Google’s Antigravity MCP instructions.

Gemini Apps

In the Gemini web app, open Settings → Connected Apps → Custom apps → Add a custom app, enter https://mcp.infiniteaudience.ai/mcp, select Next, and follow the sign-in prompts. Google says the custom-app setup can use Dynamic Client Registration, so do not enter an API key or choose a no-auth connection for Infinite Audience. Once connected, you can select the app with @ in a chat.

Google’s current eligibility rules require a personal Google Account, age 18 or over, US location, Keep Activity on, and English; work and school accounts are not eligible. Add the custom app on the web, then use it on the web or mobile app. Infinite Audience OAuth and scoped tool listing have not yet been tested in Gemini Apps; this is a documented setup path, not a compatibility claim or a public directory listing.

Gemini CLI

Add the remote HTTP server:

gemini mcp add infinite-audience https://mcp.infiniteaudience.ai/mcp --transport http

Run /mcp auth infinite-audience if sign-in does not begin automatically. Gemini CLI documents OAuth discovery and RFC 9207 issuer validation. Infinite Audience’s production metadata now advertises issuer-response support, but a complete Gemini CLI sign-in and tool call still need a live compatibility test. See Gemini CLI’s MCP guide.

Start with least privilege

If your client lets you choose OAuth scopes, request only discovery initially. When a client requests multiple scopes, Infinite Audience still selects discovery by default on the consent screen. This scope is not purely read-only: some discovery tools run backend queries or update cached state, but do not purchase records. Add account-read only for usage, balance, and existing top-up status; it cannot change your account or open payment links. Enable creator only when you want the assistant to create, enrich, match, or deliver data. Review each tool before using it; you can reconnect later to add a scope.

If the browser blocks sign-in

ERR_BLOCKED_BY_CLIENT usually means a privacy or content-blocking extension stopped the authorization URL before it reached Infinite Audience. Open the URL in a private window or another browser, or allow api.infiniteaudience.ai. Keep the AI client open so its localhost callback remains available.

Unattended API-key clients

For a service you operate, keep the API key in your service’s secret store. Exchange it at POST /v1/auth/token, then send the returned bearer token on each MCP request. The bearer lasts about one hour and has no refresh token. Your client should check expiry before every request and exchange the key again shortly before expiry. See the API-key guide and the TypeScript MCP client example, which performs a safe tool listing with a current bearer for every request.

A client that only accepts a fixed Authorization header cannot keep this connection alive by itself. Use its OAuth sign-in if available, or put a credential-aware client under your control in front of it. Do not depend on a timer rewriting a static configuration file; the host may not reload it.

Start with this prompt

First prompt

List the available read-only Infinite Audience tools and explain three useful ways
they could help a marketing team. Do not create, enrich, deliver, purchase, or modify
anything until I approve the specific action.

Then try a product prompt:

Planning prompt

Help me plan a customer enrichment workflow for a CRM export. First ask what outcome
the marketing team wants, what identity fields the file contains, and which enriched
signals will change a decision. Recommend a simple approach and show any quote before
starting billable work. Wait for my approval before you run it.

Give the agent a good brief

State the business outcome, the source of the customer data, the destination, and any approval boundary. The clearer the brief, the more useful—and less meandering—the agent becomes.

Available tools

The focused server catalog contains 60 tools. An interactive OAuth connection can request discovery, account-read, and creator; account-read exposes only the three account-status tools below, never team administration, plan changes, or credit purchases. Those administrative and commercial actions remain in the authenticated product and REST API, not MCP. A discovery scope alone does not imply every visible tool is a pure read.

For saved filter segments, call create_segment with subtype=filter; compose an audience with create_audience. To soft-archive a campaign, call update_campaign with status=archived. Use list_deliveries for one accessible saved audience, or list_all_deliveries for a paginated search across audiences. Discovery tools accept one population source per call; supplying both an audience and segment ID is rejected.

Discovery & Schema

Tool	Scope	What it does
discovery_count	discovery	Preview the count for one requested population. With segment_id, also updates that saved segment count snapshot. Accepts exactly one population input.
discovery_lookup	discovery	Return up to 25 PII-masked sample rows matching criteria — accepts raw filters, segment_id, audience_id, or segment_ids + set_logic.

Campaigns

Tool	Scope	What it does
list_campaigns	discovery	List a page of campaigns with status and brief; use next_cursor for more and get_campaign for linked audiences.
create_campaign	creator	Create a named campaign workspace with an optional brief and goals.
get_campaign	discovery	Retrieve a campaign brief and customer-facing summaries of its linked audiences.
update_campaign	creator	Update name or brief; set status to archived to soft-archive while preserving linked audiences, or active to restore.
link_audience_to_campaign	creator	Link an existing audience to a campaign. A campaign holds many audiences; each audience belongs to at most one.
unlink_audience_from_campaign	creator	Remove the link between an audience and a campaign, leaving the audience itself untouched.

Segments

Tool	Scope	What it does
list_segments	discovery	List saved segments for your org, with optional subtype filtering and pagination.
get_segment	discovery	Retrieve a segment’s customer-facing definition, including filter_groups, record_count, and current_version.
create_segment	creator	Create a typed segment — filter, matched file upload, similarity, or propensity. Matched uploads accept residential, work, or auto spatial matching. For a saved filter segment reuse filters or filter_groups from discovery_count with subtype=filter. Omit count_snapshot to leave the count unknown, then use count_segment. Matched upload, analysis, and processing are free until first successful delivery. Optional campaign_id records the campaign the segment is built for and links its wrapper audience.
wait_for_segment	discovery	Block until an async segment (matched/similarity/propensity) reaches active or failed status. Polls every 15s up to 15 min.
patch_segment	creator	Rename a segment or replace a filter definition and size limit. Geography is required for positive size limits.
archive_segment	creator	Archive a segment (or restore an archived one with restore: true). Always safe and reversible — never affects audiences that already reference it. Distinct from permanently deleting a segment via the REST API, which does change referencing audiences.
duplicate_segment	creator	Duplicate a segment with lineage tracking, preserving subtype and all subtype-specific data (data referenced, never recomputed). Filter duplicates start with a null count; other subtypes carry the source counts. 409 if a matched source's data is unavailable.
get_segment_demographics	discovery	Profile one segment on its own; audience set logic and exclusions are not applied. Works for every subtype.
get_segment_audiences	discovery	List every audience that references a segment, with campaign linkage. Use before archiving, refreshing, or editing a segment to understand downstream impact.
count_segment	discovery	Refresh the stored record_count of one saved segment. Use discovery_count for an unsaved population preview or recount_audience for a composed audience.

Audiences

Tool	Scope	What it does
list_audiences	discovery	List a page of saved audiences with status, segment composition, record count, and campaign_id. Filter to one campaign with campaign_id, or to audiences in no campaign with unlinked=true.
get_audience	discovery	Retrieve details and segment composition for a specific saved audience.
get_audience_demographics	discovery	Profile a saved audience after applying its segment composition, set logic, and exclusions.
create_audience	creator	Save an audience from existing segment_refs with include/exclude roles and set_logic. Audiences are the delivery payload; use create_segment for typed cohort creation. Optional record_count must be verified for this exact composition. Optional campaign_id links the new audience to a campaign; omit it to leave the audience unlinked.
patch_audience	creator	Partially update — rename, add/remove segments, change set_logic (union/intersection), or transition status (active/archived).
recount_audience	discovery	Refresh the stored record_count of one saved audience from its current composition. Use discovery_count for a preview or count_segment for a saved segment.
archive_audience	creator	Archive an audience or restore it with restore=true, preserving composition and delivery history.
duplicate_audience	creator	Duplicate an audience with lineage tracking (parent + root ancestor, segment versions pinned). Carries composition; the duplicate starts with a null record count — recount to populate.
refresh_audience	creator	Refresh one named member segment (segment_id is required) and bump this audience's version/expiry/status. Matched refreshes accept the established file format, optional gzip compression, and same-format shards. Other member segments and audiences remain untouched; recount separately.
refresh_segment	creator	Re-derive one segment without touching its audiences. Filter is synchronous; matched returns fresh upload URL(s) for the established format with optional gzip compression and same-format shards; similarity/propensity relaunch their workflow. The response lists affected_audiences.

Enrichment & Catalog

Tool	Scope	What it does
get_field_catalog	discovery	Browse filter fields by default, or enrichment outputs with purpose=enrichment. Fields include descriptions, filter operators, grouping support, coded values, and coverage definitions. Follow next_cursor; pricing is opt-in.
get_data_release	discovery	Return the platform current data-release version. Compare against a match result's resolution_action to tell whether a direct Refresh returned unchanged data.
analyze_audience_upload	discovery	After uploading a csv/json/jsonl/avro file (plain or gzip) to the presigned URL, run bounded streaming column inference. Returns analysis.columns[], unmapped_columns[], and recommendations[].
confirm_column_mappings	creator	Confirm column mappings for a staged matched-segment upload, moving the file into place and starting identity resolution.
cancel_matched_upload	creator	Abort a staged (hitl:true) matched-segment upload without confirming. The segment is left untouched.
discovery_overlap	discovery	Calculate overlap count, percentage, and demographic deltas between two segments or audiences.
discovery_crosstab	discovery	Generate a cross-tabulation pivot table across two demographic dimensions for a segment, audience, or raw filter expression.
match_records	creator	Synchronous micro-batch identity resolution for up to 100 contact records submitted inline. A tier-01 Person ID from a prior match or licensed audience delivery can refresh; include I in match_level for direct lookup. Spatial mode accepts residential, work, or auto (commercial workplace routing). Returns records with iag_person_id and enrichment fields. Records usage per matched record; amount_charged is a pending estimate.
list_match_runs	discovery	List past micro-batch match calls — run_id, match_count, match_rate, conservative pending-usage estimate (amount_charged), field_list, created_at. Cursor-paginated via before= timestamp.
get_match_run	discovery	Retrieve a single micro-batch run by run_id. Returns full details including input_record_count, match_rate, conservative pending-usage estimate (amount_charged), and expires_at.
list_integration_runs	discovery	List safe partnership activity with provenance, counts, selected fields, and billing rail. Accepts at most one of provider, connection_id, kind, or status; continue with cursor.
get_integration_run	discovery	Retrieve one safe partnership-run projection by run_id without exposing private workflow artifacts.
list_saved_integration_matches	discovery	Refresh and list aggregate counts of saved integration matches available to preview and build into segments.
preview_saved_integration_segment	discovery	Preview exact unique, duplicate, expired, suppressed, overlap, and net-addition counts without mutation or usage.
build_saved_integration_segment	creator	Create a matched segment or replace the current version of a compatible standalone matched segment from already-settled integration matches. Completion or failure can notify configured webhooks, subscriptions, and opted-in user email; no matching rerun or new audience.
get_saved_integration_segment_build	discovery	Read aggregate status and the durable segment ID for a queued saved-match materialization.
list_file_match_jobs	discovery	List async file-based identity resolution jobs with status, match rate, and the one-time match estimate once first delivered (amount_charged is null beforehand), plus format/compression and segment/audience IDs.
get_file_match_job	discovery	Get one file match job by match_id (= segment_id), including the one-time match estimate once first delivered (amount_charged is null beforehand), format/compression, matching status, field counts, lineage, audience ID, and errors.

Delivery

Tool	Scope	What it does
quote_delivery	discovery	Quote a download with explicit output_format and output_compression axes. A fresh quote persists a pending quote and updates the audience quote reference, but does not purchase or deliver records. Returns itemized cost, balance sufficiency, and already_delivered for a free re-export of the same paid audience/version/template.
deliver_audience	creator	Deliver a download with explicit output format/compression. CSV/JSON/JSONL may use gzip; Avro uses native DEFLATE and rejects outer gzip. LiveRamp/Narrative stay unavailable until their partner pushes confirm egress.
deliver_file_match	creator	Trigger download delivery for a matched audience with explicit output format/compression. Returns a processing delivery_id; follow with wait_for_delivery.
wait_for_delivery	discovery	Block until a delivery completes or fails (polls every 15 s, up to 15 min). Call after deliver_audience or deliver_file_match when status is processing. Returns 24-hour signed download_urls[] on success; expires_at is the separate artifact-retention date.
list_deliveries	discovery	List up to 100 deliveries for one accessible saved audience with audience and member-segment checks. Use list_all_deliveries for an org-wide paginated search. Signed links are omitted.
list_file_match_deliveries	discovery	List deliveries for a file match, including output format/compression and exact output bytes. Signed links are omitted from history.
list_all_deliveries	discovery	Search org delivery history with status, destination, or audience filters and pagination. Its fields and access checks differ from list_deliveries; use that tool for one saved audience. Signed links are omitted.
get_delivery	discovery	Get delivery status, artifact axes, exact bytes, and every output part URL. Signed URLs are regenerated on each GET and last 24 hours; expires_at is the separate artifact-retention date.

Workflows

Tool	Scope	What it does
wait_for_workflow	discovery	Wait briefly for a segment workflow (30 seconds by default). A timeout leaves the job running; use get_workflow_status to continue.
respond_to_workflow_gate	creator	Submit a user response to a paused HITL gate in a running workflow. Only used when hitl=true on audience creation.
get_workflow_status	discovery	Check workflow progress, gate choices, or a failure reason and next action.

Account Status

Tool	Scope	What it does
check_balance	account-read	View the authorized REST billing status: contract, rated current-period spend, credits, automatic recharge, safety overlays, payment readiness, and projection staleness. The response can include provider and routing identifiers.
check_topup_status	account-read	Read verified durable status for an existing top-up without creating a charge. Payment URLs remain in Account → Billing, not MCP output.
get_account_usage	account-read	Retrieve operational counts, rated current-period spend and projection time, and compute ceiling usage.

Short status waits

MCP wait tools default to 30 seconds. A *_TIMEOUT means only that this wait ended; the job continues. Use get_segment, get_delivery, or get_workflow_status with the returned IDs to check again. Do not recreate work because a wait expired. Explicit longer waits remain available for clients that support them.

Segment, audience and campaign lists default to compact summaries (10 per page). Use the corresponding get tool for a complete definition, or pass compact: false. Continue pages with the returned next_cursor as the next request’s cursor.

Optional overlap distributions are empty when unavailable. They are not zero-count populations. The privacy minimum applies to total populations, not individual demographic buckets.

Account-status results include money_display: currency amounts keyed by the original _cents field path. Use these strings directly when explaining balances; do not divide them again. The original cents fields remain authoritative, and missing/null amounts remain unknown. Preserve any projection-staleness caveat.