The alphabrand MCP server exposes three tools. Both require a signed-in user; the token belongs to the user, not to an organization, so the tools work across every organization the user belongs to.
list_workspaces
Lists the workspaces the signed-in user can query with the data agent, with the datasets each one gives access to. Call it first to find the workspaceId for ask_data_question. It takes no input.
Result, as structured content:
{
"workspaces": [
{
"id": "workspace-3eb09b96-4558-45",
"name": "Reverb",
"organization": "Reverb Drinks",
"dataAgentAvailable": true,
"unavailableReason": null,
"datasets": [
{ "id": "market", "name": "Market", "description": "Volume, value and share by market and segment" },
{ "id": "panel", "name": "Panel", "description": "Consumer panel purchases" }
]
},
{
"id": "workspace-7c1d2e3f-9a0b-41",
"name": "Archive",
"organization": "Reverb Drinks",
"dataAgentAvailable": false,
"unavailableReason": "NO_DATASET_ASSIGNED",
"datasets": []
}
]
}unavailableReason | Meaning |
|---|---|
ORG_FLAG_OFF | Market data is not enabled for the organization. Ask your alphabrand contact. |
NO_DATASET_ASSIGNED | The organization has market data but this workspace has no dataset assigned. |
Which workspaces appear follows the app: organization admins see every workspace of the organization, members only the ones they were added to.
describe_workspace
How to ask the data agent in one workspace. Returns a short contract on how to phrase questions, then, per dataset, its coverage and the house definitions the agent applies, in your company's own vocabulary. Call it once per workspace before the first ask_data_question, and use its terms in your questions instead of defining your own. Read-only.
Input:
{
"workspaceId": "workspace-3eb09b96-4558-45"
}| Field | Required | Meaning |
|---|---|---|
workspaceId | only when you have several data-enabled workspaces | Which workspace to describe. From list_workspaces. |
Result, as structured content:
{
"workspaceId": "workspace-3eb09b96-4558-45",
"name": "Reverb",
"organization": "Reverb Drinks",
"howToAsk": "The data agent applies the house definitions below, the client market scope and the current data period on its own ...",
"datasets": [
{
"id": "market",
"name": "Market",
"description": "Volume, value and share by market and segment",
"geographicScope": "UK, France, Germany, Spain, Italy",
"timeGranularity": "monthly",
"timePeriod": "January 2022 to September 2026",
"houseDefinitions": [
{ "term": "key markets", "meaning": "The five tracked countries, unless the question names others." },
{ "term": "innovation", "meaning": "A product launched in the last 36 months, measured on its first three years." },
{ "term": "share", "meaning": "Volume share of the segment, in 9L cases, over the last 12 months." }
]
}
]
}The text content carries the same material as a readable brief: the howToAsk paragraph, then one section per dataset with its coverage lines and a term: meaning list. A dataset with no vocabulary says "House definitions: none beyond the description". Definitions are terms and one or two sentences; they never include formulas, column names or SQL.
ask_data_question
Asks a business question in natural language over the datasets of a workspace. The agent applies your company's house definitions, market scope and current data period on its own, writes and runs the SQL, and answers with validated figures, tables and the assumptions it applied.
Input:
{
"question": "Gin volume trend in the UK over the last three years",
"workspaceId": "workspace-3eb09b96-4558-45",
"conversationId": "proj-a0149d83-98cf-4a",
"datasets": ["market"]
}| Field | Required | Meaning |
|---|---|---|
question | yes | The business question, in your company's business terms. Name the defined terms as describe_workspace writes them. Do not redefine a metric, restate the methodology or ask for raw rows to recompute a figure. |
workspaceId | only when you have several data-enabled workspaces and no conversationId | Which workspace to ask. From list_workspaces. |
conversationId | no | Continue an earlier investigation in the same context. For a report that needs many figures, ask one question per figure in the same conversation so scope and period stay consistent. Omit it to start a new one. |
datasets | no | Dataset ids to pin, from list_workspaces. Omit to let the agent choose. |
Result, as structured content:
{
"answer": "UK gin volume rose from 8.1M to 9.4M 9L cases between 2023 and 2025 ...",
"assumptions": [
"Source: Market",
"Period: 2023-2025 actuals",
"Metric: volume in million 9L cases"
],
"datasetsUsed": ["market"],
"conversationId": "proj-a0149d83-98cf-4a",
"workspaceId": "workspace-3eb09b96-4558-45",
"openInAlphaBrand": "https://app.alphabrand.ai/ws/workspace-3eb09b96-4558-45/project/proj-a0149d83-98cf-4a"
}The text content ends with the same two lines, for hosts that only read text:
Open in alphabrand: https://app.alphabrand.ai/ws/workspace-3eb09b96-4558-45/project/proj-a0149d83-98cf-4a
conversationId: proj-a0149d83-98cf-4aThe assumptions list is authoritative on scope, period and definitions: quote it next to the figure. Charts are not returned; open the project link to see them.
Errors
Errors come back as the tool's text content.
| Message | Cause |
|---|---|
Your alphabrand account was not found. | The token's user has no alphabrand account. |
Pass a workspaceId: call list_workspaces and pick one where the data agent is available. | Several data-enabled workspaces and no workspaceId. |
Workspace X was not found among your workspaces. Call list_workspaces. | Unknown or inaccessible workspaceId. |
The data agent is not available in workspace "X" (ORG_FLAG_OFF). | See unavailableReason above. |
You cannot start an investigation in workspace "X". | No right to create projects there, or the workspace has no brand. |
Conversation X was not found. | Unknown conversationId. |
The data agent could not answer this question. Please try again. | The run failed. The project created for it is deleted. |
Timing
A first answer takes about half a minute, a follow-up about a minute. Pass a progressToken in the request metadata to receive progress notifications while the agent works; they keep the connection alive on hosts with idle timeouts.