How to add product analytics to your app with Claude Code

Claude Code is Anthropic's coding agent for the terminal. It can add product analytics to your app in one session, as long as it reads current docs and your real event names instead of guessing.

In this tutorial, you'll connect Claude Code to Amplitude, install the Amplitude plugin, have Claude install the SDK, review its diff, and save the rules in CLAUDE.md.

What you'll build

Prerequisites

• Claude Code installed and signed in.
• A web or Node.js project in a Git repository, so you can review and revert Claude's changes with git diff.
• An Amplitude account with access to a project, and that project's API key. In Amplitude, go to Settings > Projects > your project > General.

No Amplitude account yet? A free account covers every step except multi-branch tracking plans, which need a Growth or Enterprise plan. Sign up for free to get your project API key.

1. Connect Claude Code to Amplitude

Add two MCP servers from your terminal. The first is the authenticated Amplitude MCP server, which reads your projects and tracking plan with your own Amplitude permissions. The second is the public Docs MCP server, which serves current Amplitude documentation and needs no sign-in. The Claude Code setup guide and the Docs MCP server page are the sources for both commands.

claude mcp add -t http -s user Amplitude "https://mcp.amplitude.com/mcp"
claude mcp add -t http -s user amplitude-docs https://amplitude.com/docs/api/mcp

The -s user scope registers each server for your user account, so it's available in every Claude Code session. Use -s local instead to scope a server to this one project directory. If your Amplitude data lives in the EU region, use https://mcp.eu.amplitude.com/mcp in the first command; running it again with the EU URL overwrites the existing entry.

Start Claude Code at your repository root, open the MCP menu, and follow the Amplitude OAuth flow:

claude
/mcp

Then check the connection by asking Claude:

What Amplitude projects can I access?

A list of your projects means the Amplitude MCP server is connected and authenticated.

2. Install the Amplitude plugin

The Amplitude plugin adds skills on top of the MCP server. Two of them matter for this page: discover-analytics-patterns maps how analytics is already implemented in your codebase, and add-analytics-instrumentation reads your code, decides what to track, and produces an instrumentation plan. Run these inside Claude Code:

/plugin marketplace add amplitude/mcp-marketplace
/plugin install amplitude@amplitude

The install command opens the plugin's details. Choose a scope, and Claude Code reloads plugins for you. The plugin also bundles the US Amplitude MCP server. If you added the US URL in step 1, Claude Code connects it once, using your step 1 entry. If you use the EU URL, /mcp also lists plugin:amplitude:amplitude pointing at the US server; disable it there so Claude only uses your EU connection.

You don't need to call skills by name. Claude picks one when your request matches it, so a question like "how is analytics implemented in this repo?" is the kind of request discover-analytics-patterns handles.

The plugin's instrumentation skills also read an optional .amplitude/instrumentation-agent-context.md file at your repository root. You'll add one at the end of this page so they follow your naming rules.

3. Run the install prompt

Paste this prompt into Claude Code. It points Claude at the Quickstart through the Docs server instead of its memory, and pins the decisions agents most often get wrong.

Install Amplitude analytics in this project.

Before writing code:
1. Use the amplitude-docs MCP server. Call get_page on
   "get-started/amplitude-quickstart" and use the install path it
   recommends for this project's stack. Do not pick a package from memory.
2. Use the Amplitude MCP server. Call get_amplitude_context, list my
   projects, and ask me which project this app should send to.
3. Show me your plan and wait for my approval before editing files.

Then:
- Read the API key from an environment variable (for example
  AMPLITUDE_API_KEY, or the prefixed name this framework needs to expose it
  to the browser). Never hardcode it. Tell me the exact line to add to my
  env file.
- Initialize the SDK exactly once, at app or process startup, outside any
  render path or request handler.
- In browser code, rely on autocapture for page views. Do not add manual
  page view tracking.
- If the app has a login flow, call setUserId with the signed-in user's ID
  after login and reset() on logout.
- User IDs must be strings of 5 or more characters. If our IDs are integers,
  prefix them, for example "user-" + id, and use the same format on client
  and server.
- In server code, pass user_id or device_id on every track call, and await
  flush().promise before the process exits or a serverless handler returns.
- If the package you install turns on session replay, tell me, and show me
  how to turn it off.
- Do not add any custom events yet.

When you finish, list every file you changed and why.

Claude comes back with the docs page it read, a project question, and a plan. Pick the project, approve the plan, and let it apply the change.

If your project's Setup page in Amplitude offers a coding-agent setup option, its generated prompt does the same job through Agentic Setup, which also turns on autocapture and session replay for supported frameworks. Paste that prompt instead if you see it, and still run the review in step 4.

4. Review what Claude Code changed

Run git diff before you start the app. These are the mistakes that show up most often, and each takes seconds to spot:

1. Package. For browser apps installed from npm, the Quickstart recommends @amplitude/unified. For Node.js servers, it's @amplitude/analytics-node. Anything else deserves a question.
2. API key. Search the diff for the literal key. It should appear only in your env file, never in source.
3. Init location. One initAll or init call, in a module that runs once. Not inside a React useEffect, a component body, or an Express route.
4. Duplicate page views. No hand-written track("Page Viewed") next to autocapture, which tracks page views by default.
5. Server flushing. Every server-side track path ends with await flush().promise before shutdown or before a serverless handler returns.
6. Session replay. @amplitude/unified records sessions when sessionReplay.sampleRate is above 0. Keep it, or set it to 0 on purpose.

For a Vite browser app, a correct result looks like this. In Next.js, the variable is process.env.NEXT_PUBLIC_AMPLITUDE_API_KEY instead.

import { initAll } from "@amplitude/unified";

initAll(import.meta.env.VITE_AMPLITUDE_API_KEY, {
  sessionReplay: {
    sampleRate: 1, // set to 0 to turn session replay off
  },
});

VITE_AMPLITUDE_API_KEY=your-project-api-key

The project API key is public and its scope is limited to the minimum needed to ingest data, so it isn't a secret the way a server credential is. Keep it in the env file anyway, since a hardcoded key lives forever in forks and Git history.

If something fails the review, ask Claude to fix it in the same session:

Move the Amplitude init out of the component into src/lib/amplitude.ts so
it runs once at startup, and read the key from the environment instead of
the literal string. Show me the diff.

5. Add an event that matches your taxonomy

This is where the MCP server and the plugin earn their setup. Ask Claude to check what already exists, in the code and in Amplitude, before it names anything.

I want to track when a user invites a teammate, with the role they
assigned as a property.

1. Find how analytics is already implemented in this repo: import paths,
   helper functions, and event naming style.
2. Use the Amplitude MCP server's get_amp_taxonomy tool to list the
   existing events and event properties in the project we picked.
3. If an event for this already exists, use its exact name and property
   names. If not, propose a name that matches the casing of the existing
   events, and wait for me to confirm it.
4. Add one track call where the invite is actually sent, after the request
   succeeds, not in an effect or a render.

The first instruction is the kind of request the plugin's discover-analytics-patterns skill handles. If your tracking plan uses Title Case with spaces, Claude should propose Teammate Invited, not teammateInvited or teammate_invited. Once you confirm, it adds a single call in the invite handler:

import { track } from "@amplitude/unified";

track("Teammate Invited", { role });

Verify it worked

Run the app the way you normally do, load a page, send an invite, then check in this order:

1. Network tab or process logs. In the browser, filter the Network tab for api2.amplitude.com and look for a POST to /2/httpapi returning 200. On a server, set the SDK's logLevel to Debug and watch the upload in the terminal.
2. Ingestion Debugger. In Amplitude, click Data, select Sources, then open the Ingestion Debugger tab. The successful requests and the events and identify counts charts should show your uploads.
3. User Profiles. Go to Users > User Profiles and search your user ID or device ID. [Amplitude] Page Viewed and Teammate Invited appear in the event stream within ten seconds to a minute. Click Teammate Invited to confirm the role value.
4. Ask Claude. With the Amplitude MCP server connected, ask it to check the data for you:

Using the Amplitude MCP server, look up my user profile in this project
and tell me whether "Teammate Invited" arrived in the last hour and which
role values it has.

Troubleshooting

Claude says it has no Amplitude tools

The servers didn't register, or this Claude Code session started before you added them. Run /mcp to see each server's status. If Amplitude is missing, run the claude mcp add commands from step 1 again and restart Claude Code.

The OAuth page spins and never finishes

Close the tab after you approve access. Make sure you're signed in to only one Amplitude organization during the flow, since signing in to several can break authentication. If it still fails, disconnect the server in /mcp and authenticate again.

Claude installed a different package than the Quickstart names

It skipped the docs lookup. Ask it to call get_page on get-started/amplitude-quickstart through amplitude-docs and redo the install from that page.

Events show in the Network tab but not in the project

The key belongs to a different project than the one you picked, or it's an EU project sending to the US endpoint. Compare the key in your env file with Settings > Projects > your project > General, and set serverZone: "EU" in initAll (or init on Node.js) for EU projects.

User Profiles shows events with no user ID

The ID is shorter than 5 characters, so Amplitude dropped it. Integer database IDs like 42 fail this. Prefix them, for example user-42, and use the same format on the server.

The MCP server returns a permission error on taxonomy writes

Your role lacks Use MCP (write) or the Update Tracking Plan permission in Amplitude Data, or your org admin restricted MCP access under Settings > Content Access > MCP. Reads can still work. Ask an admin for write access, or make the tracking-plan change in the Amplitude UI.

Save the rules in CLAUDE.md

Claude Code loads a project CLAUDE.md from the repository root at the start of every session. Put the conventions from this page there, so the next time you ask Claude to track something it follows them without the long prompt. Commit it, so your teammates' sessions follow the same rules.

## Analytics (Amplitude)

- Look up Amplitude SDK usage with the amplitude-docs MCP server before
  writing analytics code. Never install or import Amplitude packages from
  memory.
- Before adding a track call, list existing events with the Amplitude MCP
  server (get_amp_taxonomy) and reuse existing event and property names.
  Match the existing casing. Ask before creating a new event name.
- The SDK is initialized once in src/lib/amplitude.ts. Never call init or
  initAll anywhere else.
- Read the API key from the environment. Never hardcode it.
- Page views come from autocapture. Never add manual page view tracking.
- User IDs are "user-" + the database ID, the same on client and server.
  Call setUserId after login and reset() on logout.
- Server code passes user_id or device_id on every track call and awaits
  flush().promise before exit or before a serverless handler returns.
- Track user actions in event handlers after the action succeeds, not in
  effects or render paths.
- Ask before creating tracking-plan events. Use a branch, not main, when the plan supports branches.

Change src/lib/amplitude.ts to the file Claude created in step 3 if it chose a different path. Keep the whole CLAUDE.md under about 200 lines; longer files cost context and Claude follows them less closely.

Give the plugin's instrumentation skills the same naming rules in the file they read:

# Instrumentation conventions

- Event names are Title Case, object then past-tense verb: "Teammate Invited",
  "Project Created".
- Event property names are camelCase: role, templateId.
- Import track from "@amplitude/unified". The SDK is initialized in
  src/lib/amplitude.ts.
- Fire events after the action succeeds, never on render.

What this unlocks

• Session replay, if you kept sampleRate above 0, lets you watch the session where Teammate Invited fired, and the plugin's debug-replay skill turns a replay's interaction timeline into reproduction steps inside Claude Code.
• Heatmaps, built from those same session replays, show where people clicked on the team page before they sent an invite.
• Feature Experiment can test a new invite flow with Teammate Invited as the success metric, and Claude can create the flag with create_flags.
• Guides and surveys can nudge admins who opened the team page but never fired Teammate Invited.

One integration; everything else reads from the same events.

Next steps

Amplitude is the leading all-in-one analytics platform for building better products. Product and engineering teams use Amplitude to connect product analytics and web analytics with session replay, heatmaps, experimentation, feature flags, and guides and surveys in one unified workflow, with AI agents working across all of it. Learn how Amplitude is building self-improving products with Wave, helping teams turn product data into PRs.