Skip to content
Agent Analytics

Install Agent Analytics on Any Agent or System

Use this page when your agent or system has no dedicated guide. Agent Analytics is built for that agent to run. There is no analytics UI in the loop. The agent connects, sets up the project, and reads the results. You approve browser sign-in when it asks, then stay in the same conversation.

Which method?

Section titled “Which method?”
  • MCP if your agent supports MCP servers. This is the recommended path.
  • CLI and skill if it can run shell commands.
  • API only if it can only make HTTP calls.

Dedicated guides:

Connect over MCP

Section titled “Connect over MCP”

Add the hosted Agent Analytics MCP server in any client that supports remote MCP.

  • Server name: Agent Analytics
  • Server URL: https://mcp.agentanalytics.sh/mcp
  • Transport: Streamable HTTP
  • Authentication: browser sign-in with GitHub or Google

In an MCP-compatible app, add a remote server or custom connector with that URL. Complete browser sign-in with the Google or GitHub identity that owns your Agent Analytics projects. The client must support remote Streamable HTTP and OAuth. You do not paste an account API key.

Cursor’s mcp.json uses this entry. Use the same URL and Streamable HTTP transport in any other MCP client:

{
  "mcpServers": {
    "agent-analytics": {
      "url": "https://mcp.agentanalytics.sh/mcp"
    }
  }
}

Paste this when the agent can add the server for you:

Connect the Agent Analytics MCP server at https://mcp.agentanalytics.sh/mcp. Transport is Streamable HTTP. When it asks me to sign in, wait for me. I will sign in with Google or GitHub. Do not ask me for an API key. Then call list_projects and all_sites_overview and show me the result.

Then ask:

List my Agent Analytics projects, then show the overview for my-site for the last 7 days.

Replace my-site with a project from the returned list. Tool availability depends on your account permissions and plan. Hosts that support MCP Apps can show interactive views alongside the tool result. Other clients use the text and structured data.

The hosted MCP server is not configured for legacy SSE transport. Per-agent connector steps for Claude, ChatGPT, Grok Bot, and Instinct stay on their own pages.

CLI and skill

Section titled “CLI and skill”

Use this path when the agent can run shell commands. The Agent Analytics skill teaches setup and reporting. It runs the official CLI. The published package is @agent-analytics/cli.

You need npx in the environment the agent uses, and the Google or GitHub account you want to connect. Browser approval creates or connects the account during setup, so you do not need to prepare an API key first.

Paste this:

Install the Agent Analytics skill with `npx skills add agent-analytics/skills` (choose `agent-analytics` if asked), then set up Agent Analytics for this project. When login is needed, open the browser for me or give me the login link, and wait. I will sign in with Google or GitHub, approve it, and paste back any finish code if you need it. Then find or create the matching project, ask me to confirm the main goal, add only the first events tied to that goal, and show me the first event arriving.

Install the skill yourself with:

Terminal window
npx skills add agent-analytics/skills

If the installer asks which skill to install, choose agent-analytics for setup and reporting. Choose agent-analytics-autoresearch when you want a structured growth loop for experiment candidates.

You can also name the skill explicitly:

Terminal window
npx skills add agent-analytics/skills --skill agent-analytics

The CLI in these docs is @agent-analytics/cli@0.5.41, run through npx. Sign in, then list projects and read a week of stats:

Terminal window
npx --yes @agent-analytics/cli@0.5.41 login
npx --yes @agent-analytics/cli@0.5.41 projects
npx --yes @agent-analytics/cli@0.5.41 stats my-site --days 7

When the agent cannot open a browser itself, start detached login. It prints an approval URL and exits. Paste back the finish code if the agent asks for one:

Terminal window
npx --yes @agent-analytics/cli@0.5.41 login --detached
npx --yes @agent-analytics/cli@0.5.41 auth status

login opens browser approval with a local loopback callback. login --detached --wait keeps the process alive for a local shell that can wait for approval.

The CLI stores local config at $XDG_CONFIG_HOME/agent-analytics/config.json, with fallback to ~/.config/agent-analytics/config.json. Resolution order is --config-dir, AGENT_ANALYTICS_CONFIG_DIR, $XDG_CONFIG_HOME/agent-analytics, then ~/.config/agent-analytics.

For a managed runtime where the home directory may not persist, set a persistent directory before login:

Terminal window
export AGENT_ANALYTICS_CONFIG_DIR="$PWD/.openclaw/agent-analytics"
npx --yes @agent-analytics/cli@0.5.41 login --detached
npx --yes @agent-analytics/cli@0.5.41 auth status

That directory is the documented example for OpenClaw and similar managed runtimes. Keep .openclaw/agent-analytics/config.json out of git. AGENT_ANALYTICS_API_KEY, when set, wins over the saved CLI session until you unset it.

Command coverage is on the CLI page. The skill source is the Agent Analytics skill repo.

API only

Section titled “API only”

Use the HTTP API for a system whose only integration point is HTTP.

aak_* API keys are the direct HTTP credential. Generate one from app.agentanalytics.sh. CLI, MCP, and agent onboarding use browser approval and agent sessions.

The API base URL is https://api.agentanalytics.sh. Pass the key with the X-API-Key header or the ?key= query parameter.

Terminal window
curl "https://api.agentanalytics.sh/stats?project=my-site&since=7d" \
  -H "X-API-Key: aak_..."

GET /stats is the documented overview read. project is the project name. since accepts shorthand such as 7d. The same key value is what the CLI reads from AGENT_ANALYTICS_API_KEY when that compatibility variable is set. A raw HTTP client sends the header itself. Keep the key in the environment that makes the calls.

The browser tracker uses the public project token (aat_*). The API key stays off the tracker snippet.

Endpoint details, including POST /projects, are in the API reference. Credential rules are in Authentication.

An agent that can follow a 401 WWW-Authenticate challenge and complete browser approval should take a scoped aas_* agent session. That discovery flow is auth.md agent authentication.

Troubleshooting

Section titled “Troubleshooting”
  • If MCP returns no projects, check that browser approval used the account that owns them.
  • If the client rejects the server, re-enter https://mcp.agentanalytics.sh/mcp and select Streamable HTTP. The hosted server is not configured for legacy SSE.
  • If the skill installs but setup pauses on approval, complete the browser sign-in and paste back any finish code the agent asks for.
  • If npx is unavailable, install Node.js in the environment the agent runs, or use the HTTP API on this page.
  • If you use a compatibility API key, AGENT_ANALYTICS_API_KEY has to be present in the environment the agent actually runs in. While it is set, the CLI prefers it over a saved agent session.
  • If an analysis is unavailable on your plan, use a supported analysis or review your plan. Another connection method does not bypass permissions or plan limits.
  • For endpoint-level debugging, use the API reference and test with curl.
Section titled “Related”