Connect AnalyticsCLI to AI coding agents

AnalyticsCLI gives coding agents a read-only path from production evidence to a reproducible product hypothesis. The agent can discover events, check freshness, query a narrow funnel or cohort, and cite the exact project, time window, data mode, and warnings behind its conclusion.

Install and authenticate

npm install --global @analyticscli/cli
analyticscli login
analyticscli projects select
analyticscli --version

Create the read-only token in the AnalyticsCLI dashboard. Do not give a coding agent a publishable ingest key, an admin token, database credentials, or raw SQL access.

Start with an agent brief

analyticscli --format json agent brief --last 14d

The versioned analyticscli.agent-brief response contains:

• freshness and Release/Debug scope;
• event activity plus non-aggregate unique-user keys with explicit non-person-level semantics and a half-window trend;
• top events, platforms, and product surfaces;
• detected acquisition, activation, engagement, monetization, reliability, feedback, agent-usage, and release-impact capabilities;
• instrumentation and identity-quality findings;
• reproducible follow-up commands;
• evidence endpoints and interpretation guardrails.

Use --focus web, --focus mobile, or --focus all when automatic surface detection is not enough. Add an explicit funnel or retention anchor only after schema discovery confirms those event names.

Connect through MCP

AnalyticsCLI ships a local stdio MCP server based on the stable MCP v1 SDK:

{
  "mcpServers": {
    "analyticscli": {
      "command": "analyticscli",
      "args": ["mcp", "--max-tool-calls", "100"]
    }
  }
}

The server exposes six tools:

• analytics_projects_list
• analytics_schema_events
• analytics_agent_brief
• analytics_funnel
• analytics_retention
• analytics_generic_query

Every tool is project-scoped, time-bounded, annotated read-only, and returns structured content. The server does not expose mutation tools, arbitrary property scans, or raw SQL. The process stops serving queries after its configured tool-call budget is exhausted.

A reliable agent workflow

1. Select the intended project.
2. Use Release mode unless the task is explicitly about test instrumentation.
3. Generate an agent brief and stop if data is empty or stale.
4. Discover the event schema before choosing event names.
5. Ask one product question with one bounded query.
6. Preserve query-plan and identity-quality warnings.
7. State what was observed separately from what is inferred.
8. Define the success metric and post-release comparison before changing code.

For example, an agent investigating signup should cite the observed time window and sample size, then run only the known signup sequence:

analyticscli funnel \
  --steps landing_page_view,signup_initiated,auth_signup_succeeded \
  --within user \
  --last 30d

If landing_page_view was collected in privacy-safe aggregate mode, it is a count, not a stable person. Use event_count for that event and start a person-level funnel only at the first consented event with a stable identity.

Release and Debug are different datasets

Release mode is the default. Debug mode is for verifying instrumentation and is selected explicitly:

analyticscli --include-debug schema events --last 24h

Do not merge both modes into one conclusion. A test event proving that an SDK call works is not evidence of production adoption or conversion.

Evidence standard for an agent recommendation

A strong recommendation records:

• project and product surface;
• Release or Debug mode;
• exact time window;
• metric and event definition;
• sample size;
• comparison baseline;
• data-quality warnings;
• observed result;
• hypothesis and confidence;
• smallest reversible change;
• post-release validation query.

That packet can be handed to the Growth Engineer to rank the finding against crash, revenue, feedback, deployment, SEO, and repository context.