Skip to content
Agent Analytics

CLI vs MCP vs API

Agent Analytics has three real access modes:

  • MCP for chat-native and editor-native tool use
  • CLI for shell-oriented agent workflows
  • API for raw HTTP control

The CLI is a convenience wrapper around the same public HTTP API. If an environment is strict about transient package execution or security scanners dislike npx, use the API docs directly and keep the same underlying workflows.

Which one is best depends on what your agent can already do.

When to use each

Section titled “When to use each”

MCP

Section titled “MCP”

Use MCP when your agent already runs inside a tool that supports connectors or MCP servers, such as Claude Desktop, Cowork, Cursor, or Claude Code plugin flows.

MCP is usually the best fit when:

  • you want the install to feel native inside chat
  • you want tool calls instead of shell commands
  • you do not want to hand-roll auth headers or request payloads
  • you want quick project or account summaries like analytics_overview, bot_traffic_overview, or all_sites_bot_traffic

Tradeoff:

  • MCP often adds more latency and token overhead than skill + CLI flows because the model has to manage more tool-call round trips and tool result payloads.

CLI

Section titled “CLI”

Use the CLI when your agent already has terminal access and is comfortable executing commands.

CLI is usually the best fit when:

  • your agent already lives in a shell-first environment
  • you want predictable command output
  • you prefer command composition over tool integration
  • you want lower overhead than MCP in editor-style agents like Cursor
  • you want simple local auth helpers like login and logout around the same API

API

Section titled “API”

Use the API when you want strict control over requests, retries, and response parsing.

API is usually the best fit when:

  • you are integrating from your own code
  • you need exact HTTP-level behavior
  • you are debugging auth or payload shape directly

CLI to API mapping

Section titled “CLI to API mapping”

Most CLI workflows map directly to an HTTP endpoint. The main exception is local auth convenience commands such as logout, which only modify local CLI state:

CLI CommandAPI Endpoint
npx @agent-analytics/cli stats my-siteGET /stats?project=my-site
npx @agent-analytics/cli all-sites --period 7dGET /account/all-sites?period=7d
npx @agent-analytics/cli bot-traffic my-site --period 7dGET /bot-traffic?project=my-site&period=7d
npx @agent-analytics/cli bot-traffic --all --period 7dGET /account/bot-traffic?period=7d
npx @agent-analytics/cli events my-siteGET /events?project=my-site
npx @agent-analytics/cli query --project my-site --metrics event_countPOST /query
npx @agent-analytics/cli funnel my-site --steps "page_view,signup,purchase"POST /funnel
npx @agent-analytics/cli retention my-site --period week --cohorts 8GET /retention?project=my-site&period=week&cohorts=8
npx @agent-analytics/cli experiments list my-siteGET /experiments?project=my-site
npx @agent-analytics/cli experiments create my-site --name signup_cta --variants control,new_cta --goal signupPOST /experiments
npx @agent-analytics/cli experiments get exp_abc123GET /experiments/{id}
npx @agent-analytics/cli projectsGET /projects
npx @agent-analytics/cli logoutNone. Local-only command that clears saved CLI auth and does not call the API.

logout clears the API key saved by the CLI on disk. It does not revoke the key on the server. If you exported AGENT_ANALYTICS_API_KEY in your shell, the CLI will still authenticate with that environment variable until you unset it.

Quick rule of thumb

Section titled “Quick rule of thumb”
  • Choose CLI first in shell-capable environments like Cursor when the agent can run commands directly.
  • Choose MCP when you specifically want native connector-style tool use or do not have a good shell path.
  • Choose API when you need full control or lower-level debugging.
Section titled “Related”