MCP reference

Every capability is an MCP tool. Your agent discovers and calls them directly. The verified public runner is @poolstatis/mcp@0.7.0; pin that exact version in the MCP host rather than using @latest.

First connection proof#

Copied configuration is not connection proof. After the MCP host starts the runner, make these real calls against the selected project:

list_projects()
get_onboarding_status(project, { env: "prod" })
get_project_schema(project, { env: "prod" })

The first get_onboarding_status call records a protected agent observation and should make the agent_connected gate complete. It also returns the next evidence-backed blocker; it does not mark all setup complete just because a config was copied.

The product sends the event with its pk_ key through the SDK or Ingest API — MCP does not fabricate product events. After the owner reviews and activates the matching metric, trigger the product path again and verify the stored evidence:

sample_events(project, { event: "signup.completed", registered: true, limit: 20 })
query_trend(project, {
  metric: "signup_completed",
  date_from: "-7d",
  interval: "day",
  env: "prod"
})
get_onboarding_status(project, { env: "prod" })

Accept the first client path only when the status reports real evidence for agent_connected, first_event_observed, metrics_activated, and first_query_produced. A completely finished onboarding also requires data-quality acceptance and a saved evidence-backed insight or decision; follow the returned next_blocker.next_action rather than guessing.

Registry (design-time)#

register_metric(project, { key, name, purpose, category, tags?, type, source })
update_metric(project, key, patch)        // including activation { status: 'active' }
delete_metric(project, key)               // refused while a funnel references it
list_metrics(project, { status?, category? })
register_entity_type(project, { name, description, prop_schema? })
define_funnel(project, { key, name, goal, steps, window_seconds })
list_funnels(project)
delete_funnel(project, key)

Analysis (query-time)#

query_trend(project, { metric, date_from, date_to?, interval, breakdown?, env? })
query_funnel(project, { funnel | steps, date_from, date_to?, env? })
query_retention(project, { start_metric, return_metric?, interval, periods, date_from, env? })
query_lifecycle(project, { metric, interval, date_from, env? })
query_stickiness(project, { metric, interval, date_from, env? })
query_entities(project, { entity_type, filters?, limit, order_by? })
get_person(project, { distinct_id, env? })

Browser analytics#

propose_browser_analytics(project, { env? })
query_web_analytics(project, { metric, date_from, date_to?, dimensions?, env? })
get_web_overview(project, { metric, date_from, date_to?, env? })
list_web_sessions(project, { metric, date_from, date_to?, limit?, env? })
get_web_session(project, { session_id, metric, env? })
get_session_engagement(project, { session_id, metric, env? })
get_page_engagement(project, { page_view_id, metric, env? })

Timing reads are bounded aggregates over cumulative page.engagement snapshots, not replay. Missing terminal evidence remains incomplete and is not converted into a zero-duration bounce.

Operations#

sample_events(project, { event?, registered?, limit?, env? })
list_ingest_warnings(project, { env?, kind? })   // rejected / unregistered / clock_skew
create_insight(project, { title, body, query })

Historical data and auditable corrections#

preview_event_backfill(project, { env?, events })
import_historical_events(project, {
  env?, batch_id, reason, expected_payload_sha256, events
})
list_event_backfills(project, { env?, limit? })
preview_event_revision(project, { event_id, env?, patch })
revise_event(project, {
  event_id, env?, patch, expected_revision, expected_preview_sha256, reason
})
get_event_history(project, { event_id, env? })

A historical batch is previewed before commit, preserves supplied timestamps, and binds its permanent batch_id to the reviewed payload hash. Exact retries are idempotent; conflicting reuse fails. Native event corrections use optimistic revisions and an exact preview fingerprint, then preserve append-only before/after history. System and Browser Experience events are not editable. These tools accept Poolstatis's event contract; they do not promise an automatic PostHog migration.

Browser Experience#

• create_experience_surface declares an active, purpose-tagged surface.
• list_experience_surfaces and archive_experience_surface manage its lifecycle.
• register_experience_route registers a stable route key and canonical path pattern.
• list_visual_experience_versions returns version, route, device, and snapshot metadata — never image bytes.
• query_interaction_map aggregates labelled click cells for a safe route key.
• get_visual_experience_map reads one bounded route/version/device/period cohort.
• compare_visual_experience compares two explicit bounded cohorts without claiming cause.
• get_experience_session returns one known session timeline.

These tools expose labelled interactions, normalized coordinates, scroll milestones, safe route keys, and coarse error types. They do not expose DOM snapshots, input values, raw URLs, cursor recordings, gaze, stack traces, or error messages.

The raw interaction grid is bounded to 2–64 cells per axis; visual maps use 4–64. A session read is capped at 500 events. Visual outputs bound returned labels/sections and report truncation, sample sizes, data-quality caveats, and snapshot freshness. MCP returns semantic aggregates and evidence metadata, never image bytes.

Session Replay metadata#

list_session_replays and get_session_replay are included in the exact-pinned public @poolstatis/mcp@0.7.0 runner. They return bounded manifest metadata and an admin viewer path; they never return rrweb events, DOM bytes, cursor samples, or object-store keys through MCP. The authenticated REST/admin path reads and plays validated events inside the sandboxed player.

The public runner exposes 145 bounded tools, including these two replay metadata tools and all three funnel-investigation tools. See Session Replay for the recorder, privacy, retention, REST, player, and package contract.

Keys#

• pk_ — ingest, write-only, safe in client code (encodes project + env).
• sk_ — secret, scoped to one project, read + manage.
• pt_ — personal, org-wide, for MCP.