AI coding agents and MCP
Let Claude Code, Cursor, Codex or ChatGPT set up datacub for you. Paste one prompt; it reads your app, works out what your business does, installs datacub and tracks the few actions that matter.
Setup prompt
Copy the prompt for your platform and paste it into your coding agent. It installs the SDK, identifies signed in users, adds three to five events for the actions that show your product works, and checks that an automatic event and one of its events really reach datacub. It never tracks every button and never sends personal data. The same prompt, filled in with your project key, is in Settings, MCP and AI.
You are connecting datacub to this website or web app. In short: 1. add datacub's script to the page, 2. track the 3 to 5 actions that matter, for example signup_completed right after someone signs up, 3. check that a real visit and one of those actions reach datacub. The numbered steps below say exactly how.
datacub is privacy-first product analytics: it shows how people find the product, start using it (activation), keep using it (engagement), pay (conversion) and come back (retention). Do the whole setup yourself, from the code. Do not ask me to describe the business or to pick event names: work them out from the repository. Keep the change small and touch nothing unrelated.
Project
Public ingestion key: not filled in yet: ask me for it (it starts with pk_live_ or pk_test_; datacub shows it under Settings, Integrations)
These keys are public: they can only send events, so they are safe in client code. Never put any other datacub credential (read keys rk_, MCP tokens datacub_mcp_) in code, and never print secrets from .env files.
1. Inspect the repository
Read the README, the package manifests, the routes or screens, the data models and the main flows before changing anything.
2. Understand the business
Say in one or two sentences what the product does and for whom, from the code.
3. Find the core customer journey
Sign up, the first moment of value (activation), the action people repeat, and paying or subscribing, where each exists.
4. Discover the framework and architecture
Entry points, client versus server code, the router or navigation, how login works.
5. Install the official datacub SDK
Web (any site or framework). The SDK is not on npm: datacub serves it as a script. Never install an npm package named @datacub/web, @datacub/react-native or anything else under @datacub: datacub has published nothing on npm yet.
Paste this in the HTML <head>: index.html for Vite and plain sites. In JSX (the root layout in Next.js or TanStack Start) never paste raw script text between tags: put the snippet's code (what is between <script> and </script>) in <script dangerouslySetInnerHTML={{ __html: `...` }} /> inside <head>. It defines the global datacub at once and loads the SDK:
<script>
(function (w, d, src) {
var q = (w.datacub = w.datacub || [])
;['init', 'track', 'identify', 'reset'].forEach(function (n) {
q[n] = function () { q.push([n].concat([].slice.call(arguments))) }
})
var s = d.createElement('script'); s.async = true; s.src = src; d.head.appendChild(s)
})(window, document, 'https://ingest.datacub.example/v1/sdk/datacub-0.4.0.min.js')
datacub.init('pk_live_YOUR_PROJECT_KEY')
</script>
Then use the global datacub in client code only (event handlers, effects), never in code that runs on the server. For TypeScript, save https://ingest.datacub.example/v1/sdk/datacub-0.4.0.d.ts as datacub.d.ts in a folder the tsconfig include covers (src/ for Vite, the project root for Next.js): it types the global datacub.
Page views, route changes in single page apps, and clicks on buttons and links are captured automatically. Do not add page view or click tracking yourself. To give an important button a readable name in reports, add data-datacub-name="upgrade_plan" to it.
The site's domain must be in the project's allowed websites (datacub dashboard, Settings), or datacub refuses its events. On localhost only a test key (pk_test_) is accepted.
6. Automatic analytics
Page views, route changes in single page apps, and clicks on buttons and links are captured automatically once datacub.init runs. Do not add your own page view or click tracking.
7. Consent
Nothing to add: datacub tracks from the first page view or screen. Do not add a consent banner or datacub.consent calls for datacub.
8. Identify signed-in users
After login or signup succeeds, call datacub.identify(user.id) with the app's own stable internal user id. Never use an email address, phone number, national ID or name as the id. Optionally pass { email, name, phone } as the second argument when the user's account has them, at login or when they change, not on every page load: datacub.identify(user.id, { email: user.email, name: user.name }). On logout call datacub.reset(), or the next person on the device inherits the last user's activity.
9. Choose 3 to 5 business events
From the journey in step 3, pick the 3 to 5 actions that show the product is working for someone, for example signup_completed, project_created, checkout_completed, subscription_started, teammate_invited. Name them object_action in snake case. Decide yourself; do not wait for me.
10. Instrument them as custom events
Track successful outcomes where the code knows the action succeeded (after the API call resolves, in the success branch), not the button click: datacub.track('signup_completed', { method: 'email' }). Add a few flat, low-cardinality properties (plan, step, count, true or false). Put each call next to the code that does the action.
11. Stay clean
No passwords, OTPs, tokens, API keys, card data, IBANs, national or Iqama IDs, emails, phone numbers, names, addresses, free text a person typed, or IDs in event names or property values (the identify traits above are the only place for email, name and phone). No duplicate events: one call per outcome, check for existing analytics calls first, never inside code that re-runs on render. No unrelated refactors or formatting changes.
12. Verify for real
Run the app, open a page or screen (an automatic event), then do one of the business actions (a custom event). Each must reach datacub: the POST to https://ingest.datacub.example/v1/batch answers 200 with "accepted" of 1 or more. A 403 names the reason, for example origin_not_allowed (the site must be added to the project's allowed websites) or localhost_live_key (use the test key). Events are sent in small batches: wait 5 seconds before you leave or close the page. A headless or automated browser (Playwright, Puppeteer) counts as a bot: its events are stored but left out of reports, so check the POST answers, not the reports. The datacub setup page turns green by itself when the first automatic event and then the first custom event arrive in a normal browser. Only report what you actually saw.
Feature flags and A/B tests: skip this unless I ask for one. Then add <script src="https://ingest.datacub.example/v1/flags.js"></script> right after the datacub snippet, and use await datacub.flag('key') (true or false) or await datacub.experiment('key') ('A' the original, 'B' the new version). datacub.experiment records that the user saw the version, so call it where that version is actually shown. Use the key of a flag or experiment created in datacub (Feature flags or Experiments); never invent one. A flag is never a permission check: keep those on the server.
13. Report briefly
What you installed and where datacub.init lives, each event and where it fires, what you verified and what you could not, and anything I must do (allow a domain).For a React Native or Expo app:
You are connecting datacub to this mobile app. In short: 1. add datacub's SDK, 2. track the 3 to 5 actions that matter, for example signup_completed right after someone signs up, 3. check that a real session and one of those actions reach datacub. The numbered steps below say exactly how.
datacub is privacy-first product analytics: it shows how people find the product, start using it (activation), keep using it (engagement), pay (conversion) and come back (retention). Do the whole setup yourself, from the code. Do not ask me to describe the business or to pick event names: work them out from the repository. Keep the change small and touch nothing unrelated.
Project
Public ingestion key: not filled in yet: ask me for it (it starts with pk_live_ or pk_test_; datacub shows it under Settings, Integrations)
These keys are public: they can only send events, so they are safe in client code. Never put any other datacub credential (read keys rk_, MCP tokens datacub_mcp_) in code, and never print secrets from .env files.
1. Inspect the repository
Read the README, the package manifests, the routes or screens, the data models and the main flows before changing anything.
2. Understand the business
Say in one or two sentences what the product does and for whom, from the code.
3. Find the core customer journey
Sign up, the first moment of value (activation), the action people repeat, and paying or subscribing, where each exists.
4. Discover the framework and architecture
Entry points, client versus server code, the router or navigation, how login works.
5. Install the official datacub SDK
React Native or Expo: datacub's React Native SDK is not published yet, so nothing can connect this app today. Do not install anything and do not fake a connection. Still do steps 1 to 4 and 9, so the event plan is ready, then stop and tell me that datacub's mobile SDK is in early access and that I should contact the datacub team. Swift, Kotlin, Flutter and other native stacks are not supported yet: say so plainly. Never install an npm package named @datacub/web, @datacub/react-native or anything else under @datacub: datacub has published nothing on npm yet.
6. Automatic analytics
Screen views come from the navigation helper of the SDK; do not add your own.
7. Consent
Nothing to add: datacub tracks from the first page view or screen. Do not add a consent banner or datacub.consent calls for datacub.
8. Identify signed-in users
After login or signup succeeds, call datacub.identify(user.id) with the app's own stable internal user id. Never use an email address, phone number, national ID or name as the id. On logout call datacub.reset(), or the next person on the device inherits the last user's activity.
9. Choose 3 to 5 business events
From the journey in step 3, pick the 3 to 5 actions that show the product is working for someone, for example signup_completed, project_created, checkout_completed, subscription_started, teammate_invited. Name them object_action in snake case. Decide yourself; do not wait for me.
10. Instrument them as custom events
Track successful outcomes where the code knows the action succeeded (after the API call resolves, in the success branch), not the button click: datacub.track('signup_completed', { method: 'email' }). Add a few flat, low-cardinality properties (plan, step, count, true or false). Put each call next to the code that does the action.
11. Stay clean
No passwords, OTPs, tokens, API keys, card data, IBANs, national or Iqama IDs, emails, phone numbers, names, addresses, free text a person typed, or IDs in event names or property values. No duplicate events: one call per outcome, check for existing analytics calls first, never inside code that re-runs on render. No unrelated refactors or formatting changes.
12. Verify for real
Run the app, open a page or screen (an automatic event), then do one of the business actions (a custom event). Each must reach datacub: the POST to https://ingest.datacub.example/v1/batch answers 200 with "accepted" of 1 or more. A 403 names the reason, for example origin_not_allowed (the site must be added to the project's allowed websites) or localhost_live_key (use the test key). Events are sent in small batches: wait 5 seconds before you leave or close the page. A headless or automated browser (Playwright, Puppeteer) counts as a bot: its events are stored but left out of reports, so check the POST answers, not the reports. The datacub setup page turns green by itself when the first automatic event and then the first custom event arrive in a normal browser. Only report what you actually saw.
13. Report briefly
What you installed and where datacub.init lives, each event and where it fires, what you verified and what you could not, and anything I must do (allow a domain).MCP server
datacub runs a Model Context Protocol server, so Claude Code, Cursor, Codex and other MCP tools can read your analytics and check your integration. It sees what your team role sees in the dashboard, in totals only.
1. Create a token
Open Settings, MCP and AI in the dashboard, then Tokens:
- Access: read only (the default), or read and register events, which also lets the tool declare your events and their properties. Registering needs the analyst role or above.
- Projects: this project only, or every project of your team.
- Expires in: 7, 30 or 90 days, or 1 year.
The token starts with datacub_mcp_ and is shown once. Keep it like a password, never in client code. It belongs to you: it works with your current team role and stops when it expires, when you revoke it, or when you leave the team.
2. Connect your tool
The server is your datacub address followed by /mcp. The settings page shows these with your address and token filled in.
claude mcp add --transport http x https://YOUR_DATACUB_HOST/mcp \
--header "Authorization: Bearer datacub_mcp_YOUR_TOKEN"{
"mcpServers": {
"x": {
"url": "https://YOUR_DATACUB_HOST/mcp",
"headers": { "Authorization": "Bearer datacub_mcp_YOUR_TOKEN" }
}
}
}# ~/.codex/config.toml, then: export DATACUB_MCP_TOKEN=datacub_mcp_YOUR_TOKEN
[mcp_servers.x]
url = "https://YOUR_DATACUB_HOST/mcp"
bearer_token_env_var = "DATACUB_MCP_TOKEN"ChatGPT and other apps that sign in with OAuth
No token to paste: add datacub as a connector with the server address https://YOUR_DATACUB_HOST/mcp and OAuth sign-in. The app opens datacub, where you choose what it may do (read only unless you tick registering events, which needs the analyst role) and which projects, then you are sent back. It shows up in your token list as a connected app; revoking it there ends its access at once. Access tokens last an hour and renew themselves for up to 90 days.
Right after creating a token, Test connection checks it. Later, Last used in the token list shows whether your tool is reaching datacub.
What your tool can do
| Tool | What it does |
|---|---|
list_projects, get_project | your projects, their time zone, allowed websites and apps |
get_sdk_setup, get_docs | install steps for web or React Native, and short reference |
get_integration_status | the first and newest event, events in the last 24 hours, the SDK |
list_event_definitions, get_event_schema | events received, with counts, and the events your team declared |
register_event_definition | declare an event, what it means and its properties (write access) |
list_flags, create_flag | the project's feature flags and experiments; create one when you ask for it (write access) |
query_analytics | one question in the dashboard's query model |
funnel, retention, feature_adoption | the same numbers as the dashboard pages |
investigate_event, investigate_users | one event, or a group of users, in totals |
Lists return next_cursor for the next page. A tool that cannot answer returns {"error": "...", "message": "..."}; arguments that do not fit a tool's input schema are refused by the MCP layer itself, with the standard invalid params error. A token can make 120 requests a minute.
What it never does
- It never lists individual people, event rows or sessions. Profiles stay in the dashboard, where every view is recorded.
- It never gives an exact count. Every count is rounded to the nearest 10 (the answer says
"approx": true); 1 to 9 comes back as{"lt": 10}, fewer than 10, and 0 stays 0. A count of events made by fewer than 10 people comes back asnull. A rate needs 10 or more on both sides. Exact numbers are in your own dashboard. - It reads whole days in the project's time zone; a
timezoneargument does not move the window. - Values from your events are masked before they leave: an email becomes
<email>, a long number<number:10>. - It never runs SQL. Every question goes through the same query engine as the dashboard, limited to your team's projects.
Docs for AI tools
These docs are also published for language models:
- /llms.txt: an index of every page, with a link to its markdown
- /llms-full.txt: every page in one file
- any page as markdown: add
.mdto its address, for example /docs/quickstart.md - /openapi.json: the HTTP API, including the MCP endpoint