MCP Server — Product Examples

This guide walks through end-to-end examples of using the MCP Server against product data. It assumes you've already connected a client and authenticated — see the MCP Server guide for setup, transport, and the full tool reference.

Every example here uses the same tools (df_count, df_search, df_start_download, df_download_status) and the same query syntax as the other data types; what changes are the fields, nested sub-fields, and views specific to product records. For the underlying reference, see the Product Data Schema and Constructing Product Queries.

The goal

Say we want Apple laptops, with their pricing and descriptions — first to size the set, then to pull a sample, and finally to export descriptions and reviews for analysis.

1. Size the result set with df_count

Every tool call names the dataset with a data_type parameter — here "data_type": "product". This is how the server knows to search product records rather than the other data types. The accepted values are property, people, product, and business.

Start with a count. It returns no records and costs no credits, so it's the cheapest way to confirm a query is scoped correctly before spending anything.

{
  "query": "brand:Apple AND categories:laptops",
  "data_type": "product"
}

A response tells you how many records match:

{
  "num_found": 742
}

2. Pull a targeted sample with df_search

Now retrieve a handful of records. df_search returns up to 50 per call and charges credits identically to REST /search.

{
  "query": "brand:Apple AND categories:(laptops OR desktops)",
  "data_type": "product",
  "num_records": 5,
  "view": ["name", "brand", "categories", "prices.amount", "prices.currency"]
}

The response has the same shape as a REST search — num_found, total_cost, and a records array:

{
  "num_found": 742,
  "total_cost": 5,
  "records": [
    {
      "name": "…",
      "brand": "Apple",
      "categories": ["laptops"],
      "prices": [
        {"amount": "000.00", "currency": "USD"}
      ]
    }
  ]
}

3. Work with nested sub-fields

Product data leans heavily on nested structures — prices, descriptions, and reviews are all nested objects. Reference their sub-fields with dot notation, both in queries and in views.

Query on a nested sub-field:

{
  "query": "brand:Apple AND descriptions.value:"Retina display"",
  "data_type": "product"
}

Request nested sub-fields in a view with dot notation in the name:

{
  "view": [
    {"name": "name"},
    {"name": "brand"},
    {"name": "descriptions.value"},
    {"name": "reviews.text"}
  ]
}

4. Use the compound {} syntax

To require multiple sub-fields to match within the same nested object — rather than anywhere across separate objects — use the compound {} syntax. For example, to match a product that has a single price record that is both under a threshold and in USD:

{
  "query": "brand:Apple AND prices:{amount:[* TO 1000] AND currency:USD}",
  "data_type": "product"
}

This differs from an unbraced AND, which would let the two conditions be satisfied by different price records on the same product. See Constructing Product Queries for a full explanation.

5. Export descriptions or reviews with df_start_download

A common product use case is pulling descriptions or reviews in bulk — for analysis or for training a model. Start an asynchronous download; the number of records it can return is governed by your Datafiniti subscription plan.

{
  "query": "categories:laptops",
  "data_type": "product",
  "format": "JSON",
  "view": ["name", "brand", "descriptions.value", "reviews.text", "reviews.rating"]
}

This returns a download identifier. Poll it with df_download_status:

{
  "download_id": "…"
}

Once the status comes back complete, the response includes links to the result files.

6. Run a product prompt

Prompts turn a product use-case guide into a ready-to-run query template. For example, search_by_gtin looks up a product by its GTIN, lookup_product_by_brand_model finds a product by brand and model number, and export_llm_training_data scopes a query to descriptions or reviews and — because the scope implies a large pull — routes the client to df_start_download rather than df_search.

For the full list of product prompts, see Product Data with AI.

Next steps

• Try the same flow for Property, People, or Business data.
• Full tool reference and setup: MCP Server.
• Product fields and prompts: Product Data with AI.