Skip to documentation
Poolstatisdocs
Get started
Open SDK experience guideOpen MCP reference

Quickstart

Poolstatis has two verified setup paths: managed Cloud beta and the source-available self-host. Both lead to the same product proof: a created project, a durably accepted event, an active purpose-first metric, and a typed answer produced through MCP. The public MCP runner is available as the version-pinned @poolstatis/mcp@0.2.0 package; the SDK npm distribution path is not generally available yet.

Cloud beta path

  1. Start hosted signup and verify the email address used for the account.
  2. Complete onboarding to create the first workspace and project.
  3. Store the one-time project and personal tokens in trusted runtime environments.
  4. Send a real product event and confirm that Poolstatis accepted it.
  5. Connect an MCP client, activate a registered metric, and produce the first typed query answer.

Hosted human auth is separate from the pk_ project ingest key and pt_ personal MCP token. Never put either runtime token in browser code or a repository.

Self-host path

1. Connect the MCP server

First follow Self-host, save the scoped tokens printed by the bootstrap command, and use Node.js 22, 23, or 24. Then add the public stdio runner to Codex, Claude Code, Cursor, VS Code/Copilot, or another MCP host:

{
  "poolstatis": {
    "command": "pnpm",
    "args": ["--silent", "dlx", "@poolstatis/mcp@0.2.0"],
    "env": {
      "POOLSTATIS_URL": "http://localhost:3300",
      "POOLSTATIS_TOKEN": "pt_your_personal_token"
    }
  }
}

Your agent now has tools to register, query, and audit.

Keep the exact package version pinned; do not replace it with @latest. The pt_ token is org-wide and belongs in the MCP host's private environment, never in browser code or a repository. Use an sk_ token instead when the agent should read and manage only one project.

Optional agent skills

MCP is the runtime connection. Skills are separate, optional project instructions that teach an agent the recommended instrumentation, analysis, and maintenance workflows. They are not required for discovery because MCP already exposes the normative poolstatis://standard/instrumentation resource.

For Codex-compatible project scope, use the three reviewed GitHub paths:

The easiest Codex flow is to ask Codex to install those GitHub repository paths into ~/.codex/skills. The installed skills are available from the next turn. Claude Code uses the matching .claude/skills copies instead. Do not treat installing a skill as proof that the MCP server is connected; verify the MCP initialize/tool call separately.

2. Let your agent instrument

Ask your agent to "set up analytics for this product." It reads your code, proposes metrics, and registers each with a mandatory purpose:

register_metric({
  key: "signup_completed",
  purpose: "Track top-of-funnel growth week over week",
  type: "unique_actors",
  category: "acquisition",
  tags: ["onboarding"]
})

3. Send events

Until @poolstatis/sdk is published to npm, install it from the checkout with pnpm add /absolute/path/to/poolstatis/sdk. Then send events. distinct_id must be the stable user id:

import { createClient } from '@poolstatis/sdk';

export const ph = createClient({
  url: process.env.POOLSTATIS_URL!,
  ingestKey: process.env.POOLSTATIS_INGEST_KEY!,
});

ph.track('signup.completed', user.id, { plan });
ph.identify('account', account.id, { plan, seats });

4. Verify

Ask your agent to sample recent events, or check the admin panel's Data tab. Confirm that the event was accepted, activate the proposed metric, and run the first typed query so the onboarding proof is based on stored evidence rather than a setup-screen completion.

Your agent can now register measurements, query results, and inspect consented Browser Experience signals without depending on a dashboard.

Add browser traffic analytics

Use the shipped optional Browser module for consent-gated visitors, sessions, canonical page views, coarse device context, and bounded UTM landing attribution. See Browser analytics for install, initialization, consent modes, privacy limits, query definitions, migration, and no-data checks. Campaign properties are session landing context, not proof that a channel caused activation.