This repository lets MCP-capable agents, coding agents, and developers answer questions about Convai session telemetry using only a Convai API key. The recommended path is the published local MCP server, @convai/analytics-mcp, which plugs into Claude Desktop, Cursor, Codex-compatible MCP clients, and other stdio MCP hosts so agents can call typed analytics tools instead of writing custom scripts.
Analyze Convai sessions, latency, reliability, usage, and provider telemetry via API key.
CONVAI_API_KEY, CONVAI_ANALYTICS_BASE_URL
ตรวจสอบล่าสุด
2026-11-09
ดาว
—
เครื่องมือ
—
อัปไทม์
—
For developers who want direct programmatic access, the repo also includes TypeScript, Python, and CLI clients that use the same public Analytics API.
Ask questions like:
How many interactions did my characters have in the last 7 days?
How many unique end users used each character this month?
Show aggregate P50/P95/P99 latency over time for production readiness sign-off.
Explain why this interaction was slow and generate a waterfall chart.
Which processor, provider, model, or character is driving latency or errors?
The SDK calls Convai's hosted analytics API at https://analytics-api.convai.com/v1/analytics. The API resolves your API key server-side, scopes every query to your account, enforces plan and quota limits, and returns agent-friendly JSON that can be summarized, charted, or used in scripts.
Status: v0.2. The full v1 endpoint surface is wired: summary, timeseries, breakdown, sessions.list, sessions.get, interactions.get, metrics/catalog, regression-detection, and query. Convenience facades (latency, providers, errors, usage) work end to end on top of those primitives.
What This Is
A local MCP server in packages/mcp that exposes the main analytics questions as typed agent tools.
A TypeScript SDK in packages/typescript.
A Python SDK in packages/python.
A CLI in cli.
Prompt recipes in recipes/prompts that tell an AI agent exactly which calls to make for common analytics questions.
Chart recipes in recipes/charts that generate Vega-Lite specs or Plotly timelines for latency, usage, reliability, and concurrency analysis.
What This Is Not
Not a client-side browser SDK. Your Convai API key is a bearer secret. Do not put it in browser JavaScript, mobile apps, public notebooks, screenshots, logs, or committed config files.
Not a direct data-store client. All reads go through Convai's hosted Analytics API with server-side account scoping, plan checks, and quota enforcement.
Not a write API. It only reads analytics data. It does not mutate characters, sessions, configs, or telemetry.
Not a replacement for the Convai dashboard. It is the programmable and agent-friendly surface for deeper analysis, automation, and chart generation.
Repository Layout
convai-analytics/
├── docs/ Concepts, auth, metrics reference, prompt/chart indexes
├── openapi/ Snapshot of the analytics API contract
├── packages/
│ ├── typescript/ @convai/analytics SDK
│ ├── mcp/ @convai/analytics-mcp local stdio server
│ └── python/ convai-analytics SDK
├── cli/ convai-analytics command line interface
├── recipes/
│ ├── prompts/ Natural-language prompt templates for AI agents
│ └── charts/ Runnable chart-generation scripts
└── examples/ Runnable end-to-end examples
Prerequisites
Node.js 18+ for the TypeScript SDK, CLI, examples, and chart recipes.
Python 3.10+ and uv for the Python SDK examples.
A Convai API key for the account whose analytics you want to query.
Get your key from the same Convai account you use for the rest of the Convai API, then export it in your shell:
export CONVAI_API_KEY="ck_live_your_key_here"
The SDK reads CONVAI_API_KEY automatically. You normally do not need to set a base URL; production is the default.
The server is also listed in the Official MCP Registry as io.github.Conv-AI/convai-analytics-mcp. If your MCP client supports registry discovery, use that registry entry; otherwise configure the npx command above. Once connected, ask normal analytics questions:
After adding or changing MCP config, restart Claude Desktop, Claude Code, Cursor, Codex, or your MCP host so it reloads the server command and CONVAI_API_KEY.
Show aggregate P50/P95/P99 latency for the last 30 days and generate a chart.
Which component is driving p95 latency, and which sessions should I inspect?
Show usage trends, unique end users, active-session concurrency, and provider/model latency charts.
git clone https://github.com/Conv-AI/convai-analytics.git
cd convai-analytics
export CONVAI_API_KEY="ck_live_your_key_here"
# Install TypeScript SDK + CLI dependencies.
make ts-install
# Optional but useful: verify the SDK and CLI compile.
make ts-build
make ts-test
Expected result: a short account summary with sessions, end users, interactions, errors, and latency percentiles for your own account.
Use With A Coding Agent
If your agent does not support MCP, open this repo in Codex, Claude Code, Cursor, or a similar coding agent. Give the agent this instruction:
Use this repository and my CONVAI_API_KEY environment variable to answer analytics questions.
First read README.md, docs/concepts.md, docs/metrics-reference.md, and recipes/prompts/README.md.
Prefer MCP when available; otherwise use the SDK or recipes. Do not ask for direct data-store access.
Keep the API key private and do not print it.
Then ask normal product questions:
How many interactions and unique end users did I have in the last 30 days?
Break it down by character and generate a usage trend chart.
Show aggregate P50/P95/P99 voice.user_to_bot_latency for the last 7 days.
Add a 3000 ms p95 threshold line and summarize the worst buckets.
List recent slow sessions, choose one with traceable interaction spans,
explain the bottleneck, and generate a waterfall chart.
The agent should use recipes/prompts for the call sequence and recipes/charts for chart generation.
MCP Server
The fastest path for MCP-capable agents is @convai/analytics-mcp. It is a published local stdio MCP server that wraps only the public TypeScript SDK. It reads CONVAI_API_KEY, optionally reads CONVAI_ANALYTICS_BASE_URL, and never accepts account overrides, service credentials, database URLs, or other internal access paths.
After saving this config, quit and reopen Claude Desktop so it starts the new MCP server. Claude Code, Cursor, Codex-compatible clients, and other stdio MCP hosts can use the same command/env shape; restart the client or start a new session after adding or changing MCP config. Once connected, ask questions like:
Show aggregate P50/P95/P99 latency for the last 30 days and generate a chart.
Which component is driving p95 latency, and which sessions should I inspect?
Show usage trends, unique end users, active-session concurrency, and provider/model latency charts.
The MCP server returns structured JSON for data tools and Vega-Lite JSON specs for chart tools. It does not write files; your MCP client can decide whether to render, save, or summarize the returned artifacts.
Local development:
make mcp-install
make mcp-lint
make mcp-test
make mcp-build
make mcp-smoke
This is a proxy derived from session start/end windows until first-class stream concurrency metrics are exposed.
10. Provider Comparison
Question:
Compare LLM or TTS provider latency and reliability.
Agent prompt:
Read recipes/prompts/provider-comparison.md and compare LLM and TTS providers for the last 7 days.
Return a table with provider/model, p95 latency, sample count, and any reliability caveats.
11. Regression Detection
Question:
Did latency regress compared with the previous window?
sessions, interactions, and unique users by character or experience
Chart Recipes
Most chart recipes print a Vega-Lite JSON spec to stdout. You can save that spec, render it in a notebook, hand it to an agent, or convert it to PNG with a Vega-Lite renderer.
Every request sends CONVAI-API-KEY to the hosted analytics API. The API key resolves server-side to one Convai account. The client cannot choose or override account scope.
The public API accepts common SDK-style aliases for compatibility, but documentation uses the canonical REST form so scripts, dashboards, and agents have one stable wire format.
Status breakdowns (group_by=status) require telemetry rows that include status metadata. If a status breakdown returns only an empty group or no rows, treat it as a no-data state rather than rendering demo values. Character usage breakdowns currently return stable character IDs; display-name enrichment is planned as a backward-compatible addition.
Development Commands
make ts-install # install TypeScript SDK + CLI deps
make ts-build # build TypeScript SDK + CLI
make ts-test # run TypeScript unit tests
make ts-lint # ESLint + TypeScript typecheck
make ts-typecheck-recipes # typecheck examples and chart recipes
make package-check # verify npm package archives exclude node_modules
make py-install # install Python SDK dev env
make py-test # run Python tests
make py-lint # ruff + mypy
make check-openapi # compare committed OpenAPI snapshot with live API
make gen-types # regenerate generated SDK types from OpenAPI snapshot
Live E2E test, if you have an API key with data:
CONVAI_ANALYTICS_E2E_RANGE=last_30d \
CONVAI_ANALYTICS_E2E_DELAY_MS=6500 \
make e2e-stg
Despite the target name, e2e-stg defaults to staging. To run against production:
CONVAI_ANALYTICS_BASE_URL=https://analytics-api.convai.com/v1/analytics \
CONVAI_ANALYTICS_E2E_RANGE=last_30d \
CONVAI_ANALYTICS_E2E_DELAY_MS=6500 \
make e2e-stg