Capabilities

The tools Data MCP exposes, grouped by what they do — each with its parameters.

Data MCP exposes PolyAI’s conversation data as MCP tools. Your client discovers them automatically on connection — you don’t configure tools by hand. Each tool carries its own input schema, which the client reads directly from the server; the parameter tables below reproduce that schema so you can see what each tool takes without connecting first.

Data MCP exposes 5 tools. Tool names appear exactly as your client sees them in tools/list.

To see exactly what your client discovered, ask it to list its tools or query the endpoint’s tools/list method. Parameters map to a PolyAI REST endpoint — they’re sent as path segments, query parameters, or a request body — but your client handles that wiring from the schema; the tables below just list what you can set.

Search & read conversations

Find conversations by their metrics, search across transcript text, and pull back the full turn-by-turn record.

search-conversations

Search conversations by metric filters, with sorting and pagination.

Parameter	Type	Description
from / to	datetime	Bounds on conversation start time (from inclusive, to exclusive).
filters	array	Metric filters: {metric, op, value}. Operators: eq, gt, gte, lt, lte, in, ex, contains, not_contains, exists. conversation_id is also accepted as a filter (eq/in) to fetch one or many conversations’ metrics. An AI Score is CUSTOM_SCORE_<ID> and filters on its 1–5 score.
filter_operator	string	How filters combine: and (default) or or.
fields	array	Metric keys to include in each conversation’s metrics map (case-insensitive). A CUSTOM_SCORE_<ID> key also selects that score in custom_scores. Omit to return all metrics — prefer passing only the metrics you need, especially on large searches.
channel	array	Restrict to channels: VOICE-SIP, CHAT, WEBCHAT, SMS, RCS.
client_env	array	Restrict to environments: test, sandbox, pre-release, live, scenarios. pre-release is the Staging environment.
sort	object	{field, order} — field is started_at, duration, or conversation_id. Defaults to started_at descending.
limit / offset	integer	Pagination. limit 1–100 (default 20), offset 0–1000.
project_id	string	Optional project scope.

Each conversation in the response carries a flat metrics map and a custom_scores list. AI Scores appear in both: metrics holds each one’s 1–5 value under its CUSTOM_SCORE_<ID> key, and custom_scores holds the same value together with the breakdown.

Field	Description
metric	The score’s CUSTOM_SCORE_<ID> key, as in metrics.
display_name	The score’s name when the conversation was scored.
score	1 (worst) to 5 (best). Null unless state is processed.
state	processed, or why there’s no score: skipped_short_conversation, skipped_excluded, or failed.
sub_scores	One entry per criterion: criterion_id, display_name, score_type (THREE_POINT or YES_NO), weight (percent), answer (Poor −1, Fair 0, Good 1; No 0, Yes 1) and answer_label.

search-transcripts

Full-text search over transcript turns across conversations, returning matches with surrounding turns for context.

Parameter	Type	Description
q	string	Search phrase, 3–300 characters. Required.
from / to	datetime	Bounds on conversation start time.
context_turns	integer	Turns of context around each match, 0–3 (default 1).
limit / offset	integer	Pagination. limit 1–100 (default 20), offset 0–1000.
project_id	string	Project scope. Required when authenticating with a PAT.

get-conversation

Fetch every turn of a single conversation.

Parameter	Type	Description
conversation_id	string	The conversation to fetch. Required.
project_id	string	Optional project scope.

Metrics & analytics

Discover which metrics you can filter and aggregate on, then roll one up over time into buckets you can chart.

get-metrics

List the filterable metrics for an account, optionally scoped to a project — built-in metrics plus any custom metrics the project defines. With a project scope, it also lists the project’s AI Scores as CUSTOM_SCORE_<ID> metrics, each with the score’s name as its display_name. Use this first to discover what you can filter and aggregate on.

Parameter	Type	Description
project_id	string	Optional project scope.

aggregate-metrics

Aggregate a metric over a time window into buckets you can chart — with grouping, cohort filters, and post-aggregation thresholds.

This tool is experimental — its schema may change. Your client discovers the current name from tools/list.

Parameter	Type	Description
metric	string	Metric to aggregate (case-insensitive, e.g. poly_score). Required.
aggs	array	Aggregations to compute: sum, avg, min, max, p50, p95, p99, conversation_count, distinct_count. Required.
from / to	datetime	Window bounds (from inclusive, to exclusive).
interval	string	Time bucket: hourly, daily, weekly, monthly. Omit for a single unbucketed result.
timezone	string	IANA timezone (e.g. Europe/London) applied to hourly and daily bucketing; naive from/to are interpreted in it. Ignored for other intervals.
group_by	array	Group by project_id, channel, deployment_id, variant_id, client_env, or — for string metrics — value_string.
filters	array	Cohort filters on other metrics: {metric, op, value}. Operators: eq, gt, gte, lt, lte, in, ex, exists.
filter_operator	string	How filters combine: and (default) or or.
having	array	Post-aggregation thresholds: {field, op, value} where field is one of the aggs.
channel	array	Restrict to channels: VOICE-SIP, CHAT, WEBCHAT, SMS, RCS.
client_env	array	Restrict to environments: test, sandbox, pre-release, live, scenarios. pre-release is the Staging environment.
deployment_id / variant_id	array	Restrict to specific deployments or variants.
sort	object	Secondary sort on a group_by or aggs field, applied after the ascending bucket sort.
limit / offset	integer	Pagination. limit 1–100 (default 20), offset 0–1000.
project_id	string	Optional project scope.

Errors

Status	Meaning
400	Request validation error.
401	Missing or invalid X-API-KEY.
403	Authenticated, but missing the required permission.
404	Not found or empty result — also returned when a credential can’t access the account.
422	Unsupported filter.