How to add analytics to your app with Codex CLI

Codex CLI is OpenAI's coding agent for the terminal, and it can add analytics to your app for you, as long as it has the current docs and your real event names.

In this tutorial, you'll connect Codex to Amplitude, have it install the SDK, check its work, and save the rules so future sessions get it right.

What you'll build

Prerequisites

• Codex CLI installed and signed in.
• A web or Node.js project in a Git repository, so you can review and revert Codex's changes.
• 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 is enough for this tutorial; nothing here needs a paid plan. Sign up for free to get your project API key.

1. Connect Codex to Amplitude

Add two MCP servers. The first is the authenticated Amplitude MCP server, which reads your projects and tracking plan with your own permissions. The second is the public Docs MCP server, which serves current Amplitude documentation and needs no sign-in.

codex mcp add amplitude --url https://mcp.amplitude.com/mcp
codex mcp add amplitude-docs --url https://amplitude.com/docs/api/mcp

Follow the OAuth flow when Codex prompts you for the first server. If your Amplitude data lives in the EU region, use https://mcp.eu.amplitude.com/mcp for the first server instead; running the add command again with the EU URL overwrites the existing entry.

Check the connection by asking Codex:

What Amplitude projects can I access?

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

2. Run the install prompt

Start Codex at the repository root and paste this prompt. Replace the placeholder with the env var name your framework expects, or leave it and let Codex choose.

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.

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.
- 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.
- 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.
- 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.

Codex should come back with a short plan, a project question, and then a diff. Pick the project and let it apply the change.

3. Review what Codex changed

Read the diff before you run anything. These are the mistakes that show up most often, and each takes seconds to spot:

1. Package. For browser apps 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 init or initAll 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') alongside autocapture pageViews.
5. Server flushing. Any server-side track has a matching await flush().promise on shutdown or at the end of a serverless handler.
6. Session replay. If Codex installed @amplitude/unified with sessionReplay.sampleRate above 0, sessions are being recorded. Keep it or set it to 0 on purpose.

Ask Codex to fix anything that fails, in the same session:

Move the Amplitude init out of the component into a module that runs once
at startup, and read the key from the environment instead of the literal
string. Show me the diff.

4. Add an event that matches your taxonomy

This is where the Amplitude MCP server earns its setup. Ask Codex to check what already exists before it names anything.

I want to track when a user creates a project, with the template they
chose as a property.

1. Use the amplitude MCP server's get_amp_taxonomy tool to list the
   existing events and event properties in the project we picked.
2. If an event for this already exists, use its exact name and property
   names. If not, propose a name that matches the casing and style of the
   existing events, and wait for me to confirm it.
3. Add one track call where the project is actually created, not in an
   effect or a render.

If your tracking plan uses Title Case With Spaces, Codex should propose Project Created, not projectCreated or project_created. When it confirms the name, it adds a single call such as:

amplitude.track('Project Created', { template });

MCP write access: Codex can also add the new event to your tracking plan with manage_amp_events, if your role has the Use MCP (write) permission. Ask it to create the event on a tracking-plan branch rather than main, so a teammate can review it before it merges.

Verify it worked

Run the app the way you normally do, trigger a page load and the new event, 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, raise 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 chart should show your uploads.
3. User lookup. Go to Users > User Profiles and search your user ID or device ID. [Amplitude] Page Viewed and your custom event appear in the event stream within ten seconds to a minute.
4. Ask Codex. With the Amplitude MCP server connected, ask it to confirm the event arrived:

Using the amplitude MCP server, query the last hour of events in this
project and tell me whether "Project Created" arrived and which template
values it has.

Troubleshooting

Codex says it has no Amplitude tools

The servers didn't register, or Codex started before you added them. Restart Codex in the repository and ask again; if the tools are still missing, run the two codex mcp add commands again.

The OAuth page spins and never finishes

Close the tab after you approve access, and make sure you're signed in to only one Amplitude organization during the flow. Signing in to several can break authentication.

Codex 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 using the US endpoint. Compare the key in your env file with Settings > Projects > your project > General.

The MCP server returns a permission error on taxonomy writes

Your role lacks Use MCP (write), 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 AGENTS.md

Codex reads AGENTS.md from the repository root at the start of every session. Put the conventions from this page there, so the next time you ask Codex to track something it follows them without the long prompt.

## Analytics (Amplitude)

- Look up Amplitude SDK usage with the amplitude-docs MCP server before
  writing analytics code. Do not 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 [PATH TO INIT MODULE]. 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.
- 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, not in effects or render paths.
- Create new tracking-plan events on a branch, never directly on main.

Replace [PATH TO INIT MODULE] with the file Codex created in step 2. Keep the file short; Codex stops loading instruction files once their combined size reaches 32 KiB by default.

What this unlocks

• Session replay, if the unified package turned it on, lets you watch the session where Project Created fired, and Codex can pull that replay through the same MCP server.
• Heatmaps show where people clicked on the page before creating a project.
• Feature Experiment can test a new template picker with Project Created as the success metric, and Codex can create the flag with create_flags.
• Guides and surveys can prompt users who reached the create page but never fired Project Created.

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.