GAME TELEMETRY FOR LIVE-SERVICE GAMES
Events, funnels, retention, in-game economy — instrument and query it all from the CLI or MCP, as structured JSON. The dashboard is for humans.
Scrolltga for your agents.The agent shipped the build and fired the events; it wants D7 retention back as JSON, not a chart to screen-scrape.
No card, no admin in the loop — your agent can bootstrap its own studio tenant.
# No account yet? Create a studio tenant and its first key $ npm install -g socialgraffa $ tga signup --slug acme --name "Acme Games" --username you --password ******** $ tga login --key tga_... # The numbers, not a dashboard $ tga stats <gameId> --from 7d --json
Works with: Claude Code · Cursor · Cline · Windsurf · Aider · Codex · any MCP client
But increasingly the thing that needs the numbers is an agent — it shipped the build, it fired the
events, and it wants to know whether players came back and the economy stayed balanced. It wants
structured JSON, not a chart to screen-scrape.
socialgraffa is the surface the agent drives itself. The tga CLI and MCP server
are the primary interface here — not a chat copilot bolted onto a dashboard.
Are players coming back, converting, and is the economy balanced? All read-only, all --json-able.
D1 / D7 / D30 return by cohort day and platform, in a single call — so an agent knows if the last change moved the needle.
Define a funnel once — tutorial_start → level_1 → purchase — then run it over any window with tga funnel run.
Currency source, sink and net flow — see where soft and hard currency is minted and burned before it breaks.
DAU, new players and sessions at a glance, live realtime, and the paths players take through your game.
Send events with a scoped per-game key. A dropped-as-bot event fails loudly instead of faking a 200.
tga agent-schema --json emits every command, flag, type and error code. If it's not in the schema, it doesn't exist.
Sign up keyless, or log in with an existing key. tga whoami tells you which tenant you're about to write to.
tga signup --slug acme --name "Acme Games"
tga login --key tga_...
Stats, retention, funnels and economy — all read-only, all --json. The machine surface is a first-class citizen.
tga stats <gameId> --from 7d
tga funnel run <funnelId> --from 30d
Mint a scoped ingest key, then send with a stable --id so agents never collapse into one player.
tga ingest-key create <gameId>
tga send <gameId> --name level_complete --id player_42
Point Claude Code, Cursor, Cline, Windsurf — any MCP client — at socialgraffa and your agent gets tools
covering stats, retention, funnels, economy, games, identity, server-side ingest and billing checkout. A tool
result and --json output are the same bytes.
# Local, for Claude Code / Cursor / Cline / Windsurf $ tga mcp-serve # Remote — zero install, Bearer your API key URL: https://mcp.socialgraffa.com/sse Auth: Authorization: Bearer tga_...
Unlimited agent keys on every plan — including Free. You pay for events, never for seats.
An agent authenticates with its tenant key and gets back a checkout URL: tga billing checkout --plan pro
Failures carry a stable code and a distinct exit code. Once published, codes are never reworded.
| Exit | Meaning | What to do |
|---|---|---|
| 2 | usage | fix the call, do not retry |
| 3 | auth | fix the credential |
| 4 | permission | do not retry, escalate |
| 5 | not found | check the id |
| 6 | validation | fix the payload |
| 7 | rate limited | back off and retry |
| 8 | network | retry is reasonable |
| 9 | server | retry once, then report |
Yes. tga signup is keyless — it works before you have a credential — and creates a studio tenant plus its first API key with no card and no admin in the loop. The one step an agent can't do is pay: a human opens the Stripe Checkout URL once to upgrade.
The dashboard is for humans. socialgraffa's primary interface is the tga CLI and the MCP server — the agent that shipped the build and fired the events queries retention, funnels and economy itself, as structured JSON, and branches on them. It's not a chat copilot bolted onto a dashboard.
--id?Anonymous identity is derived from IP and user-agent. Agents share both — one CLI version is one user-agent, and agents often share an egress IP — so without a stable --id every agent behind that IP collapses into a single player. It cannot be backfilled.
A discarded event still answers HTTP 200 — the ingest endpoint returns {"beep":"boop"} when it drops an event as a bot. The CLI treats that as a hard failure with a hint, so an agent never believes a dropped event succeeded.
Run tga agent-schema --json. It returns every command, argument, flag, type and the full list of error codes — generated from the same table that drives the parser, help text and MCP tools, so it cannot drift. If it's not in the schema, it doesn't exist.
One install, and it sends server-side events and queries retention, funnels and economy — all as structured JSON.
$ npm install -g socialgraffa $ tga stats <gameId> --from 7d --json
One more thing…
Agents run the instrumentation — but everything they capture lands in a complete, real-time dashboard. Live players, sessions, funnels, retention, economy and journeys, all in one place. No terminal required.
