Tools

The Subtotal Data MCP provides three tools for exploring and querying your purchase data.

ask

Ask a natural language question about your purchase data. The server translates it into SQL and returns the results — no SQL knowledge required. Parameters:

Name	Type	Required	Description
`question`	string	Yes	A natural language question about your purchase data

Example questions:

“Show me the top 5 retailers by purchase count this year”
“How many active connections do I have?”
“What are my highest-value purchases from the last 30 days?”
“Which brands appear most frequently in my items?”

Response format:

{
  "fields": ["name", "purchase_count"],
  "results": [
    ["Amazon", 1523],
    ["Target", 892],
    ["Walmart", 641]
  ],
  "result_count": 3
}

Constraints:

Questions must be plain English — embedded SQL will be rejected
Only SELECT queries are generated — your data is never modified
Results are limited to 100 rows and 5 MB
A 5-second execution timeout is enforced

If the question cannot be answered with the available data, or the generated query fails, the response will contain an error field:

{
  "error": "This question cannot be answered with the available data."
}

Other possible errors include request timeouts and response size limits.

ask uses an AI model to translate your question into SQL. For best results, be specific about the data you want, time ranges, and how results should be grouped or sorted. To inspect the data model itself (entities, fields, relationships), use get_data_model instead.

get_retailers

List the retailers available to your account as structured rows. By default returns only the retailers enabled for your team (each with a Subtotal Link URL); pass include="all" to list every active retailer in the catalog, annotated with whether it’s enabled for your team. Parameters:

Name	Type	Required	Description
`include`	string	No	`enabled` (default) — only the retailers enabled for your team, each with a `link_url`. `all` — every active retailer in the catalog, each annotated with an `enabled` flag and a `link_url` (present only when enabled). These are the only accepted values.

Response format:

{
  "retailers": [
    {
      "retailer_id": "walmart",
      "name": "Walmart",
      "images": {
        "logo": { "light": ".../light/logo.svg", "dark": ".../dark/logo.svg" },
        "icon": { "light": ".../light/icon.svg", "dark": ".../dark/icon.svg" }
      },
      "status": "active",
      "enabled": true,
      "link_url": "https://link.subtotal.com/a1b2c3d4"
    }
  ]
}

Fields:

Field	Description
`retailer_id`	Retailer slug — the exact value used to filter purchase data by retailer (e.g. in `ask`).
`name`	Retailer display name.
`images`	Logo and icon URLs, each with a `light` and `dark` theme.
`status`	Platform status: `active`, `limited`, or `inactive`.
`enabled`	Whether this retailer is enabled for your team.
`link_url`	URL to launch Subtotal Link for the retailer. Present only when the retailer is enabled; `null` otherwise.

This is the same retailer contract returned by the public GET /retailers API. With include="all", link_url is null for retailers not enabled for your team.

get_data_model

Returns the data model for your purchase data, including entities, fields, types, and relationships. Parameters: None Returns: A plain-text data model describing six entities: connection, purchase, item, retailer, product, and brand.

If you’re using ask, you typically don’t need to call get_data_model — the server already has the data model when answering questions.

Documentation

Platform

Integrations

Guides

ask

get_retailers

get_data_model

​ask

​get_retailers

​get_data_model

ask

get_retailers

get_data_model