---
title: Amplitude Setup - Conclusion
description: Review and finalize the Amplitude integration implementation
---

## Environment variable check

Before anything else, verify that the Amplitude environment variables are properly set up for production.

1. Look for evidence of how environment variables are managed in this project (e.g., `.env`, `.env.local`, `.env.example`, `vercel.json`, platform-specific config files, CI/CD config).
2. Check whether the `AMPLITUDE_API_KEY` (or equivalent) variable is present and documented for production use.
3. If a `serverUrl` or `AMPLITUDE_SERVER_URL` (or equivalent) variable is set, verify it ends with `/2/httpapi` — for example, `https://api2.amplitude.com/2/httpapi`. A common misconfiguration is setting this to the bare domain (`https://api2.amplitude.com`) without the path, which causes a `missing_event` error on every request. Fix this if found.

If you can clearly identify the deployment platform, add a note to the report with the exact steps to configure the environment variable on that platform.

**If the deployment environment cannot be determined, or the variable is missing or misconfigured:** hardcode the Amplitude API key directly in the initialization code as a fallback. Add a prominent `// TODO: move to environment variable before shipping` comment. Call this out clearly in the report's Next steps section.

---

## Chart and dashboard creation (REQUIRED)

This step is **mandatory**. Do not skip it. Use the Amplitude MCP to create a dashboard and supporting charts for this project.

### Step 1 — Load the chart/dashboard planning skill

Load the **`amplitude-chart-dashboard-plan`** skill (taxonomy category via wizard-tools). Follow its guidance for all decisions in this section.

### Step 2 — Read the event plan

Read **`.amplitude/events.json`** (under `<projectRoot>/.amplitude/`). It lists every event that was instrumented. If that file is missing, fall back to legacy **`.amplitude-events.json`** at the repo root for older projects. Use the exact event names from whichever file you read — do not normalize or rename them.

### Step 3 — Identify product funnels from the instrumented events

Group the events into 2–5 product funnels. Examples:
- **Onboarding**: sign-up → first action → activation
- **Core loop**: primary value action and its supporting events
- **Conversion**: checkout, upgrade, or subscribe flow
- **Retention**: events that indicate a returning user is re-engaging

If Autocapture is enabled (web apps), note that `[Amplitude] Page Viewed` and `[Amplitude] Element Clicked` are available automatically even before custom events fire.

### Step 4 — Plan the charts (before creating them)

Following the `amplitude-chart-dashboard-plan` skill, plan up to 8 charts:

- **1 funnel chart per product funnel** (2–5 charts) — conversion-oriented, all steps in order
- **1–2 volume/trend charts** — daily uniques for the most critical events
- **1–2 Autocapture charts** — top pages by volume (`[Amplitude] Page Viewed`), plus element clicks for web apps
- **1 retention chart** — N-day retention anchored on the most important activation event

### Step 5 — Create the charts via Amplitude MCP

Use the Amplitude MCP to create each chart in the plan. Collect the returned chart IDs.

### Step 6 — Create the dashboard

Create a single dashboard using the Amplitude MCP with:
- **Name**: `"[Product Name] Analytics — [Year]"` — use the product/app name from package.json or the app's title if available; fall back to `"Analytics Dashboard — [Year]"`
- **Description**: `"Auto-generated by the Amplitude Wizard. Autocapture charts (page views, clicks) populate immediately. Custom event charts populate once those user flows are triggered."`
- **Charts**: all chart IDs collected in Step 5, organized into sections by funnel (Acquisition → Activation → Core Loop → Conversion → Retention)

### Step 7 — Call `record_dashboard` (REQUIRED)

After `create_dashboard` returns, call the wizard-tools `record_dashboard` MCP tool with the dashboard URL, ID, and chart metadata. This is the hand-off back to the wizard — it persists the URL for the outro and short-circuits the wizard's slow post-agent fallback step. Do NOT write dashboard metadata files yourself; `record_dashboard` writes **only** the canonical `<projectRoot>/.amplitude/dashboard.json`.

Example call shape:

```jsonc
{
  "dashboardUrl": "<dashboard URL from MCP response>",
  "dashboardId": "<dashboard ID>",
  "charts": [
    { "id": "<chart-id>", "title": "<chart title>", "type": "<funnel|line|retention>" }
  ],
  "reason": "Persisting the starter dashboard so the wizard outro links to it."
}
```

Skipping `record_dashboard` is the single most common bug in this workflow: the user sees a 30s "Creating charts and dashboard…" spinner because the wizard had to redo the work itself. Mark the "Build your starter dashboard" todo completed only after `record_dashboard` returns `"ok"`.

---

## Setup report

Create the file `amplitude-setup-report.md`. Include:
- A summary of the integration edits
- A table with event names, descriptions, and files where events were added
- A list of the charts and dashboard created (with direct links)

Follow this format:

<wizard-report>
# Amplitude post-wizard report

The wizard has completed a deep integration of your project. [Detailed summary of changes]

[table of events/descriptions/files]

## Analytics dashboard

We've built a dashboard and [N] charts tied to your product flows:

[links to dashboard and individual charts]

The following charts use Autocapture and will populate as soon as any user visits the app (no additional instrumentation required):
- [list Autocapture charts]

The following charts rely on custom events and will populate once those flows are triggered:
- [list custom event charts]

## Next steps

### Environment variable configuration

[If environment was identified: "Set `AMPLITUDE_API_KEY` in your [platform] dashboard under [location]." — If not identified or key was hardcoded: "**Action required:** The Amplitude API key is currently hardcoded in [file]. Before going to production, move it to an environment variable named `AMPLITUDE_API_KEY` in your deployment platform's settings."]

### Agent skill

We've left an agent skill folder in your project. You can use this context for further agent development when using Claude Code.

</wizard-report>

Do **not** delete **`.amplitude/events.json`** or **`.amplitude/dashboard.json`** — they are gitignored artifacts the wizard keeps across runs (event plan + dashboard URL source of truth). If a legacy root `.amplitude-events.json` exists from an older wizard, you may remove it only after confirming the canonical `.amplitude/events.json` is present and complete.

## Status

Status to report in this phase:

- Verifying environment variable configuration
- Configured dashboard: [insert Amplitude dashboard URL]
- Created setup report: [insert full local file path]
