Skip to main content

​
Overview

The Commerce Grid Audience Briefs MCP lets your AI application or agent work with Commerce Grid audience planning briefs. Your agent can research AI-recommended audience segments, review audience insights, create briefs, find existing briefs, and share them through a link. This is the MCP surface of the Commerce Grid Audience Planner — the planning tool in the Commerce Grid UI (Data tab) that turns a campaign brief into recommended audiences. It lets your agent create and review audience planning briefs programmatically instead of through the UI. Typical uses include:
  • Researching audiences for a campaign before committing to a brief
  • Creating audience planning briefs from campaign details in natural language
  • Reviewing and sharing existing briefs with stakeholders

​
Add the endpoint

Add the Audience Briefs MCP as an MCP server in your MCP-compatible client or agent environment:
Refer to Access Flows for the step-by-step setup on Claude, ChatGPT, or other platforms. Refer to MCP Troubleshooting if you run into connection, authentication, or tool discovery issues.
Access to the Commerce Grid Audience Briefs MCP is set up by Criteo. Please reach out to your Criteo representative to get credentials for your use case before connecting.

​
Client selection

Most tools operate under a single Commerce Grid client (contract) and require a clientId parameter.
  • Call get_available_clients first to list the clients available to the connected credentials.
  • If more than one client is returned, the agent asks you which one to use.
  • The selected client ID is then passed as clientId to every client-scoped tool.
Results are limited to the clients accessible to the credentials used by the MCP client. A brief can only be retrieved or shared under the client it belongs to.

​
Tools

The Audience Briefs MCP exposes eight tools:
ToolTypeDescription
get_available_clientsReadLists the clients (contracts) available to you.
get_recommended_segmentsReadReturns AI-recommended audience segments for campaign parameters, without creating a brief.
get_segment_insightsReadReturns audience insights for a list of segments.
create_briefWriteCreates and processes a brief, then returns recommended segments.
create_brief_with_segmentsWriteCreates a brief with pre-selected segments.
query_briefsReadSearches existing briefs for a client.
get_brief_by_idReadReturns the details of one brief.
share_briefWriteCreates a shareable link for a brief.
Read tools do not persist anything. Write tools create briefs or share links under the selected client.

​
Client discovery

get_available_clients Returns the clients (contracts) available to you. If more than one client is returned, choose the one to use; its ID must then be passed as clientId to client-scoped tools. This tool takes no parameters.

​
Segment research

These tools are read-only and do not persist anything. Use them to explore segments before deciding whether to create a brief. get_recommended_segments Returns AI-recommended audience segments based on campaign parameters, without creating a brief. Returns up to 30 recommended segments with relevance scores, audience sizes, and targeting details.
ParameterTypeRequiredDefaultDescription
clientIdstringYes—Client ID returned by get_available_clients.
brandstringYes—Brand name for the campaign.
countryCodestringYes—Country code, e.g. US, GB, FR, DE.
descriptionstringYes—Description of the campaign goals and target audience.
productsstringNonullComma-separated product keywords to narrow segment matching.
get_segment_insights Returns audience insights for a list of segments across five dimensions: product categories (UCs, from the Universal Catalog), brands, publisher content categories (PCAs), gender, and buying power. Each insight is benchmarked against a country baseline with an affinity score. Use it to analyze segments before deciding which ones to include in a brief.
ParameterTypeRequiredDefaultDescription
countryCodestringYes—Country code, e.g. US, GB, FR, DE.
segmentsJsonstringYes—JSON array of segments. Each segment must include skuKeywords (string) and segmentSize (number).
Example segmentsJson value:

​
Brief creation

Both tools persist a new brief under the selected client and return it, including the generated briefId (UUID) that get_brief_by_id and share_brief require. Use parameter values exactly as provided by the user — if a required value is missing, the agent should ask for it rather than infer it. create_brief Creates and processes an audience planning brief from campaign details, then returns AI-recommended audience segments.
Processing may take 10–30 seconds.
ParameterTypeRequiredDefaultDescription
clientIdstringYes—Client ID returned by get_available_clients.
namestringYes—Name of the brief.
brandstringYes—Brand name for the campaign.
briefstringYes—Description of the campaign goals and target audience.
budgetnumberYes—Campaign budget in US dollars, e.g. 50000.00. Always USD, regardless of countryCode — there is no currency parameter.
countryCodestringYes—Country code, e.g. US, GB, FR, DE.
startDatestringYes—Campaign start date in YYYY-MM-DD format.
endDatestringYes—Campaign end date in YYYY-MM-DD format.
advancedSettingsbooleanNofalseEnables advanced targeting settings.
keywordsstringNonullComma-separated targeting keywords.
productsstringNonullComma-separated product keywords for targeting.
excludeTermsstringNonullComma-separated terms to exclude from targeting.
create_brief_with_segments Creates a brief with pre-selected segments, typically taken from get_recommended_segments output. Unlike create_brief, it skips the segment recommendation step: it fetches insights for the provided segments and persists everything.
ParameterTypeRequiredDefaultDescription
clientIdstringYes—Client ID returned by get_available_clients.
namestringYes—Name of the brief.
brandstringYes—Brand name for the campaign.
descriptionstringYes—Description of the campaign goals and target audience.
budgetnumberYes—Campaign budget in US dollars, e.g. 50000.00. Always USD, regardless of countryCode — there is no currency parameter.
countryCodestringYes—Country code, e.g. US, GB, FR, DE.
startDatestringYes—Campaign start date in YYYY-MM-DD format.
endDatestringYes—Campaign end date in YYYY-MM-DD format.
segmentsJsonstringYes—JSON array of segments to include. See Segment format.
keywordsstringNonullComma-separated targeting keywords.
productsstringNonullComma-separated product keywords.
excludeTermsstringNonullComma-separated terms to exclude.
Segment format Each segment in segmentsJson contains:
  • Required: skuKeywords, segmentSize, segmentType, description, relevanceScore
  • Optional: dataProviderId, externalSegmentId, alreadyCreated
Some segment types also require a targeting configuration: Other segment types do not require a configuration.
Copy the complete configuration from the recommendation or segment details, even for segments that are already created. Preserve empty lists and a null gender, and never invent targeting values.

​
Brief management

query_briefs Searches existing briefs for the selected client.
ParameterTypeRequiredDefaultDescription
clientIdstringYes—Client ID returned by get_available_clients.
searchTermstringNonullFilters by brief name or brand.
brandstringNonullFilters by brand name.
countrystringNonullFilters by ISO country code, e.g. US.
statusstringNonullFilters by brief status: SUBMITTED, PROCESSING, PROCESSED, or ARCHIVED.
pageintegerNo1Page number, 1-based.
pageSizeintegerNo10Results per page, maximum 100.
get_brief_by_id Returns detailed information about one brief. The brief must belong to the selected client.
ParameterTypeRequiredDefaultDescription
clientIdstringYes—Client ID returned by get_available_clients.
briefIdstring (UUID)Yes—Unique identifier of the brief.
share_brief Creates a shareable link for a brief. If the brief is already shared, returns the existing share link with the brief details.
ParameterTypeRequiredDefaultDescription
clientIdstringYes—Client ID returned by get_available_clients.
briefIdstring (UUID)Yes—Unique identifier of the brief.
emailstringNonullEmail address of the recipient.
expirationDaysintegerNo30Number of days from now until the link expires.

​
Typical workflow

1

Select the client

Call get_available_clients to get the clientId. If several clients are available, pick the right one.
2

Research segments

Call get_recommended_segments, then get_segment_insights to explore and compare segments. Nothing is saved at this stage.
3

Create the brief

Call create_brief_with_segments with the segments you selected, or create_brief to let the MCP recommend segments for you. The response includes the new brief’s briefId — keep it for the next steps.
4

Review the brief

Call get_brief_by_id with the briefId from the previous step to review the full brief, or query_briefs to search by name, brand, country, or status when you do not have the ID.
5

Share the brief

Call share_brief to get a shareable link.

​
Example questions

  • “Which Commerce Grid clients can I access through this connection?”
  • “Recommend audience segments for a running shoes campaign by Acme in the US targeting active millennials.”
  • “Show me audience insights for the top five recommended segments.”
  • “Create a brief named ‘Acme Spring Running’ for Acme in the US, budget $50,000, from 2026-03-01 to 2026-04-30, using the segments we selected.”
  • “List my processed briefs for Acme in the US.”
  • “Share the ‘Acme Spring Running’ brief with jane.doe@example.com for 14 days.”