> ## Documentation Index
> Fetch the complete documentation index at: https://developers.criteo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Audience Briefs MCP

> Connect your agent to the Commerce Grid Audience Briefs MCP to research audience segments, create audience planning briefs, and share them.

## 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:

```
https://mcp.criteo.com/commerce-grid-supply-audience-briefs/mcp
```

Refer to [Access Flows](https://developers.criteo.com/mcp/docs/access-flows.md) for the step-by-step setup on Claude, ChatGPT, or other platforms.

Refer to [MCP Troubleshooting](https://developers.criteo.com/mcp/docs/mcp-troubleshooting.md) if you run into connection, authentication, or tool discovery issues.

> [!NOTE]
>
> 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.

> [!NOTE]
>
> 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:

<table>
  <colgroup>
    <col />

    <col />

    <col />
  </colgroup>

  <thead>
    <tr><th>Tool</th><th>Type</th><th>Description</th></tr>
  </thead>

  <tbody>
    <tr><td>[`get_available_clients`](#get_available_clients)</td><td>Read</td><td>Lists the clients (contracts) available to you.</td></tr>
    <tr><td>[`get_recommended_segments`](#get_recommended_segments)</td><td>Read</td><td>Returns AI-recommended audience segments for campaign parameters, without creating a brief.</td></tr>
    <tr><td>[`get_segment_insights`](#get_segment_insights)</td><td>Read</td><td>Returns audience insights for a list of segments.</td></tr>
    <tr><td>[`create_brief`](#create_brief)</td><td>Write</td><td>Creates and processes a brief, then returns recommended segments.</td></tr>
    <tr><td>[`create_brief_with_segments`](#create_brief_with_segments)</td><td>Write</td><td>Creates a brief with pre-selected segments.</td></tr>
    <tr><td>[`query_briefs`](#query_briefs)</td><td>Read</td><td>Searches existing briefs for a client.</td></tr>
    <tr><td>[`get_brief_by_id`](#get_brief_by_id)</td><td>Read</td><td>Returns the details of one brief.</td></tr>
    <tr><td>[`share_brief`](#share_brief)</td><td>Write</td><td>Creates a shareable link for a brief.</td></tr>
  </tbody>
</table>

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.

<table>
  <colgroup>
    <col />

    <col />

    <col />

    <col />

    <col />
  </colgroup>

  <thead>
    <tr><th>Parameter</th><th>Type</th><th>Required</th><th>Default</th><th>Description</th></tr>
  </thead>

  <tbody>
    <tr><td>`clientId`</td><td>string</td><td>Yes</td><td>—</td><td>Client ID returned by `get_available_clients`.</td></tr>
    <tr><td>`brand`</td><td>string</td><td>Yes</td><td>—</td><td>Brand name for the campaign.</td></tr>
    <tr><td>`countryCode`</td><td>string</td><td>Yes</td><td>—</td><td>Country code, e.g. `US`, `GB`, `FR`, `DE`.</td></tr>
    <tr><td>`description`</td><td>string</td><td>Yes</td><td>—</td><td>Description of the campaign goals and target audience.</td></tr>
    <tr><td>`products`</td><td>string</td><td>No</td><td>`null`</td><td>Comma-separated product keywords to narrow segment matching.</td></tr>
  </tbody>
</table>

**`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.

<table>
  <colgroup>
    <col />

    <col />

    <col />

    <col />

    <col />
  </colgroup>

  <thead>
    <tr><th>Parameter</th><th>Type</th><th>Required</th><th>Default</th><th>Description</th></tr>
  </thead>

  <tbody>
    <tr><td>`countryCode`</td><td>string</td><td>Yes</td><td>—</td><td>Country code, e.g. `US`, `GB`, `FR`, `DE`.</td></tr>
    <tr><td>`segmentsJson`</td><td>string</td><td>Yes</td><td>—</td><td>JSON array of segments. Each segment must include `skuKeywords` (string) and `segmentSize` (number).</td></tr>
  </tbody>
</table>

Example `segmentsJson` value:

```json theme={null}
[{"skuKeywords": "running shoes", "segmentSize": 150000}]
```

***

### 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.

> [!NOTE]
>
> Processing may take 10–30 seconds.

<table>
  <colgroup>
    <col />

    <col />

    <col />

    <col />

    <col />
  </colgroup>

  <thead>
    <tr><th>Parameter</th><th>Type</th><th>Required</th><th>Default</th><th>Description</th></tr>
  </thead>

  <tbody>
    <tr><td>`clientId`</td><td>string</td><td>Yes</td><td>—</td><td>Client ID returned by `get_available_clients`.</td></tr>
    <tr><td>`name`</td><td>string</td><td>Yes</td><td>—</td><td>Name of the brief.</td></tr>
    <tr><td>`brand`</td><td>string</td><td>Yes</td><td>—</td><td>Brand name for the campaign.</td></tr>
    <tr><td>`brief`</td><td>string</td><td>Yes</td><td>—</td><td>Description of the campaign goals and target audience.</td></tr>
    <tr><td>`budget`</td><td>number</td><td>Yes</td><td>—</td><td>Campaign budget in US dollars, e.g. `50000.00`. Always USD, regardless of `countryCode` — there is no currency parameter.</td></tr>
    <tr><td>`countryCode`</td><td>string</td><td>Yes</td><td>—</td><td>Country code, e.g. `US`, `GB`, `FR`, `DE`.</td></tr>
    <tr><td>`startDate`</td><td>string</td><td>Yes</td><td>—</td><td>Campaign start date in `YYYY-MM-DD` format.</td></tr>
    <tr><td>`endDate`</td><td>string</td><td>Yes</td><td>—</td><td>Campaign end date in `YYYY-MM-DD` format.</td></tr>
    <tr><td>`advancedSettings`</td><td>boolean</td><td>No</td><td>`false`</td><td>Enables advanced targeting settings.</td></tr>
    <tr><td>`keywords`</td><td>string</td><td>No</td><td>`null`</td><td>Comma-separated targeting keywords.</td></tr>
    <tr><td>`products`</td><td>string</td><td>No</td><td>`null`</td><td>Comma-separated product keywords for targeting.</td></tr>
    <tr><td>`excludeTerms`</td><td>string</td><td>No</td><td>`null`</td><td>Comma-separated terms to exclude from targeting.</td></tr>
  </tbody>
</table>

**`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.

<table>
  <colgroup>
    <col />

    <col />

    <col />

    <col />

    <col />
  </colgroup>

  <thead>
    <tr><th>Parameter</th><th>Type</th><th>Required</th><th>Default</th><th>Description</th></tr>
  </thead>

  <tbody>
    <tr><td>`clientId`</td><td>string</td><td>Yes</td><td>—</td><td>Client ID returned by `get_available_clients`.</td></tr>
    <tr><td>`name`</td><td>string</td><td>Yes</td><td>—</td><td>Name of the brief.</td></tr>
    <tr><td>`brand`</td><td>string</td><td>Yes</td><td>—</td><td>Brand name for the campaign.</td></tr>
    <tr><td>`description`</td><td>string</td><td>Yes</td><td>—</td><td>Description of the campaign goals and target audience.</td></tr>
    <tr><td>`budget`</td><td>number</td><td>Yes</td><td>—</td><td>Campaign budget in US dollars, e.g. `50000.00`. Always USD, regardless of `countryCode` — there is no currency parameter.</td></tr>
    <tr><td>`countryCode`</td><td>string</td><td>Yes</td><td>—</td><td>Country code, e.g. `US`, `GB`, `FR`, `DE`.</td></tr>
    <tr><td>`startDate`</td><td>string</td><td>Yes</td><td>—</td><td>Campaign start date in `YYYY-MM-DD` format.</td></tr>
    <tr><td>`endDate`</td><td>string</td><td>Yes</td><td>—</td><td>Campaign end date in `YYYY-MM-DD` format.</td></tr>
    <tr><td>`segmentsJson`</td><td>string</td><td>Yes</td><td>—</td><td>JSON array of segments to include. See [Segment format](#segment-format).</td></tr>
    <tr><td>`keywords`</td><td>string</td><td>No</td><td>`null`</td><td>Comma-separated targeting keywords.</td></tr>
    <tr><td>`products`</td><td>string</td><td>No</td><td>`null`</td><td>Comma-separated product keywords.</td></tr>
    <tr><td>`excludeTerms`</td><td>string</td><td>No</td><td>`null`</td><td>Comma-separated terms to exclude.</td></tr>
  </tbody>
</table>

**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:

| Segment type | Required configuration | Fields |
| :- | :- | :- |
| InMarket | `inMarketConfiguration` | `country`, `buyingPower`, `gender`, `interestIds`, `brandIds`, `priceRange` |
| Affinity | `affinityConfiguration` | `country`, `targetingCategoryIds`, `customCategoryIds`, `lookbackDays`, `numberOfEvents` |

Other segment types do not require a configuration.

> [!WARNING]
>
> 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.

<table>
  <colgroup>
    <col />

    <col />

    <col />

    <col />

    <col />
  </colgroup>

  <thead>
    <tr><th>Parameter</th><th>Type</th><th>Required</th><th>Default</th><th>Description</th></tr>
  </thead>

  <tbody>
    <tr><td>`clientId`</td><td>string</td><td>Yes</td><td>—</td><td>Client ID returned by `get_available_clients`.</td></tr>
    <tr><td>`searchTerm`</td><td>string</td><td>No</td><td>`null`</td><td>Filters by brief name or brand.</td></tr>
    <tr><td>`brand`</td><td>string</td><td>No</td><td>`null`</td><td>Filters by brand name.</td></tr>
    <tr><td>`country`</td><td>string</td><td>No</td><td>`null`</td><td>Filters by ISO country code, e.g. `US`.</td></tr>
    <tr><td>`status`</td><td>string</td><td>No</td><td>`null`</td><td>Filters by brief status: `SUBMITTED`, `PROCESSING`, `PROCESSED`, or `ARCHIVED`.</td></tr>
    <tr><td>`page`</td><td>integer</td><td>No</td><td>`1`</td><td>Page number, 1-based.</td></tr>
    <tr><td>`pageSize`</td><td>integer</td><td>No</td><td>`10`</td><td>Results per page, maximum `100`.</td></tr>
  </tbody>
</table>

**`get_brief_by_id`**

Returns detailed information about one brief. The brief must belong to the selected client.

<table>
  <colgroup>
    <col />

    <col />

    <col />

    <col />

    <col />
  </colgroup>

  <thead>
    <tr><th>Parameter</th><th>Type</th><th>Required</th><th>Default</th><th>Description</th></tr>
  </thead>

  <tbody>
    <tr><td>`clientId`</td><td>string</td><td>Yes</td><td>—</td><td>Client ID returned by `get_available_clients`.</td></tr>
    <tr><td>`briefId`</td><td>string (UUID)</td><td>Yes</td><td>—</td><td>Unique identifier of the brief.</td></tr>
  </tbody>
</table>

**`share_brief`**

Creates a shareable link for a brief. If the brief is already shared, returns the existing share link with the brief details.

<table>
  <colgroup>
    <col />

    <col />

    <col />

    <col />

    <col />
  </colgroup>

  <thead>
    <tr><th>Parameter</th><th>Type</th><th>Required</th><th>Default</th><th>Description</th></tr>
  </thead>

  <tbody>
    <tr><td>`clientId`</td><td>string</td><td>Yes</td><td>—</td><td>Client ID returned by `get_available_clients`.</td></tr>
    <tr><td>`briefId`</td><td>string (UUID)</td><td>Yes</td><td>—</td><td>Unique identifier of the brief.</td></tr>
    <tr><td>`email`</td><td>string</td><td>No</td><td>`null`</td><td>Email address of the recipient.</td></tr>
    <tr><td>`expirationDays`</td><td>integer</td><td>No</td><td>`30`</td><td>Number of days from now until the link expires.</td></tr>
  </tbody>
</table>

***

## 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](mailto:jane.doe@example.com) for 14 days."