Merge Unified's Amplitude integration Merge Agent Handler's Amplitude MCP server

Connect your AI Agents to Amplitude in minutes

Merge lets you securely connect your agents to Amplitude and thousands of tools instantly

Start building for free

Read docs

Amplitude

Learn more about Merge Agent Handler

Available tools

get_active_users

Get active, new, returning, or exiting user counts over a date range. Dates must be in YYYYMMDD format. Supports daily, weekly, or monthly intervals and grouping by user properties.

get_average_session_length

Get average session length per day over a date range. Dates must be in YYYYMMDD format.

get_retention

Get user retention analysis for a starting and returning event over a date range. Pass event objects like {"eventtype": "signup"}. Use listevents to find valid event names. Dates in YYYYMMDD format.

get_funnel

Get funnel conversion analysis for a sequence of events over a date range. Pass a list of event objects like [{"eventtype": "view"}, {"eventtype": "purchase"}]. Use list_events to find valid event names. Dates in YYYYMMDD format.

get_realtime_active_users

Get realtime active user counts with 5-minute granularity over the last 2 days. No date parameters needed.

get_revenue_ltv

Get lifetime value and revenue metrics for new users over a date range. Metrics include revenue, ARPU, ARPPU, and paying new users. Dates in YYYYMMDD format.

get_user_composition

Get user distribution across values of a specific property (e.g. country, platform, os) over a date range. Dates in YYYYMMDD format.

list_annotations

List all chart annotations in the project. Returns annotation IDs, dates, labels, details, and category IDs.

get_annotation

Get a single annotation by ID. Use list_annotations to find valid IDs.

create_annotation

Create a chart annotation with a label and start timestamp (ISO 8601). Optionally assign a category name. Use listannotationcategories to find valid names.

update_annotation

Update an existing annotation's label, start/end timestamps, details, or category. Use list_annotations to find valid IDs.

delete_annotation

Delete an annotation by ID. Use list_annotations to find valid IDs.

list_annotation_categories

List all annotation categories. Returns category IDs, names, and colors.

create_annotation_category

Create a new annotation category with a name and optional color.

delete_annotation_category

Delete an annotation category by ID. Use listannotationcategories to find valid IDs.

get_chart_results

Get the results of a saved chart by its ID. Find chart IDs from the URL in Amplitude (e.g. the ID in https://app.amplitude.com/analytics/.../chart/abc123). Returns the same data shown in the Amplitude chart UI.

list_cohorts

List all behavioral cohorts in the project. Returns cohort IDs, names, owners, size, and metadata. Use this to find cohort IDs for other operations.

request_cohort_export

Request an async export of a cohort's user data. Returns a requestid to poll status with. Use listcohorts to find valid cohort IDs. Rate limited to 500 requests/month.

update_cohort_membership

Add or remove user IDs from a cohort. Each membership item needs 'ids' (list of user IDs) and 'operation' ('ADD' or 'REMOVE'). Use list_cohorts to find valid cohort IDs.

list_events

List all event types in the project with their weekly totals and percentage of DAU. Returns event names, totals, and metadata. Use this to discover available events before running segmentation or funnel queries.

get_event_segmentation

Get event segmentation data: counts, uniques, averages, or DAU percentage for a specific event over a date range. Supports grouping by event properties. Use list_events first to find valid event names. Dates must be in YYYYMMDD format (e.g. '20250401').

list_event_types

List all event types in the project taxonomy with their display names, descriptions, categories, and visibility settings.

get_event_type

Get details for a specific event type by name, including its properties, description, and category. Use listeventtypes to find valid event type names.

list_event_properties

List all properties for a specific event type. Returns property names, display names, types, and descriptions. Use listeventtypes first to find valid event type names.

list_user_properties

List all user properties in the project taxonomy. Returns property names, display names, types, and descriptions.

search_users

Search for users by user ID or device ID. Returns matching users with their Amplitude ID, last seen time, country, platform, and device info. Rate limited to 360 queries/hour.

get_user_activity

Get a user's recent events and summary data by their Amplitude ID (numeric). Use search_users first to find the Amplitude ID. Supports pagination via offset. Rate limited to 360 queries/hour.

get_user_profile

Get a user's profile including properties, cohort memberships, and recommendations from the Profile API. Provide either userid (external) or amplitudeid.

validate_credential

Validate Amplitude API key and secret key by making a lightweight API call. Returns success status and a message.

View all tools by creating a free account See more tools

How to set up Merge Agent Handler

In an mcp.json file, add the configuration below, and restart Cursor.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "url": "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
5      "headers": {
6        "Authorization": "Bearer yMt*****"
7      }
8    }
9  }
10}
11

Copy Code

Open your Claude Desktop configuration file and add the server configuration below. You'll also need to restart the application for the changes to take effect.

Make sure Claude is using the Node v20+.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "command": "npx",
5      "args": [
6        "-y",
7        "mcp-remote@latest",
8        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
9        "--header",
10        "Authorization: Bearer ${AUTH_TOKEN}"
11      ],
12      "env": {
13        "AUTH_TOKEN": "yMt*****"
14      }
15    }
16  }
17}

Copy Code

Open your Windsurf MCP configuration file and add the server configuration below.
Click on the refresh button in the top right of the Manage MCP server page or in the top right of the chat box in the box icon.

Learn more in the official documentation ↗

1{
2    "mcpServers": {
3      "agent-handler": {
4        "command": "npx",
5        "args": [
6          "-y",
7          "mcp-remote@latest",
8          "https://ah-api.merge.dev/api/v1/tool-packs/<tool-pack-id>/registered-users/<registered-user-id>/mcp",
9          "--header",
10          "Authorization: Bearer ${AUTH_TOKEN}"
11        ],
12        "env": {
13          "AUTH_TOKEN": "<ah-production-access-key>"
14        }
15      }
16    }
17  }

Copy Code

In Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows), run "MCP: Open User Configuration".

You can then add the configuration below and press "start" right under servers. Enter the auth token when prompted.

Learn more in the official documentation ↗

1{
2  "inputs": [
3    {
4      "type": "promptString",
5      "id": "agent-handler-auth",
6      "description": "Agent Handler AUTH_TOKEN", // "yMt*****" when prompt
7      "password": true
8    }
9  ],
10  "servers": {
11    "agent-handler": {
12      "type": "stdio",
13      "command": "npx",
14      "args": [
15        "-y",
16        "mcp-remote@latest",
17        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
18        "--header",
19        "Authorization: Bearer ${input:agent-handler-auth}"
20      ]
21    }
22  }
23}

Copy Code

FAQs on using Merge's Amplitude MCP server

What is an Amplitude MCP?

It's an MCP server that connects your agents to Amplitude via tools. Your agents can invoke these tools to query user analytics, analyze funnel and retention data, manage cohorts, track event segmentation, and more.

Amplitude offers an official MCP server, but you can also use one from a third-party platform, like Merge Agent Handler.

How can I use the Amplitude MCP server?

The use cases naturally depend on the agent you've built, but here are a few common ones:

On-demand funnel analysis: When a product manager asks about conversion for a specific user flow, an agent calls <code class="blog_inline-code">get_funnel</code> with the relevant event sequence and returns a step-by-step breakdown, identifying drop-off points without requiring anyone to open the Amplitude dashboard

Post-release retention check: After shipping a new feature, an agent calls <code class="blog_inline-code">get_retention</code> for users who triggered the feature event and surfaces whether that cohort retains better or worse than baseline, giving the team a signal on feature stickiness within hours of launch

Real-time anomaly alerting: An agent calls <code class="blog_inline-code">get_realtime_active_users</code> on a schedule, detects a significant drop from baseline, and posts a structured alert to the team's Slack channel with the current active user count and the expected range so engineers can investigate before it compounds

Deployment annotation: When a release is pushed to production, an agent calls <code class="blog_inline-code">create_annotation</code> to mark the date on Amplitude charts. That way, future analysis can correctly attribute metric changes to the specific deployment that caused them

What are popular tools for Amplitude's MCP server?

Here are some of the most commonly used tools:

<code class="blog_inline-code">get_funnel</code> retrieves conversion rates across a defined sequence of events for a specified time range and user segment. Use this when an agent needs to quantify where users are dropping off in a flow without requiring a manual dashboard query

<code class="blog_inline-code">get_retention</code> returns retention data for a cohort over a specified window, showing what percentage of users return after a triggering event. Good for agents that need to evaluate feature stickiness or compare cohort behavior after a product change

<code class="blog_inline-code">get_event_segmentation</code> breaks down event counts by user property, event property, or time interval. Call this when an agent needs to analyze how a specific action varies across user segments or platforms

<code class="blog_inline-code">get_realtime_active_users</code> returns the current count of active users in near real-time. Helpful when an agent is monitoring for traffic anomalies or validating that a deployment didn't cause an unexpected drop in engagement

<code class="blog_inline-code">search_users</code> finds users in Amplitude by property values or identifiers and returns their profile data. Use this when an agent needs to look up a specific user's attributes before cross-referencing activity from another system

<code class="blog_inline-code">create_annotation</code> adds a labeled marker to Amplitude charts at a specified date. Useful for agents that automatically document deployments, experiments, or external events so future analysis has the context to interpret metric shifts correctly

What makes Merge Agent Handler's Amplitude MCP server better than alternative Amplitude MCP servers?

A few things distinguish Merge Agent Handler's Amplitude MCP server from building your own or using a standalone alternative:

Enterprise-grade security and DLP: Merge Agent Handler includes built-in data loss prevention controls that let you block or redact sensitive fields before they reach an agent. For Amplitude, this means you can prevent user-level behavioral data, cohort membership details, and revenue metrics from being exposed even when the agent has broad read access to your analytics

Managed authentication and credentials: Merge stores and refreshes Amplitude credentials on your behalf. You never expose API keys to an agent directly or manage re-authentication when credentials rotate

Real-time observability and audit trail: Every tool call made against Amplitude is logged with timestamp, tool name, input parameters, and response metadata. You can audit exactly what analytics an agent queried or what annotations it created without adding any custom instrumentation

Tool Packs and controlled access: Tool Packs let you bundle specific Amplitude tools with tools from other connectors into a single MCP endpoint, scoped to a specific use case. An agent gets exactly the tools it needs, nothing more

How can I start using Merge Agent Handler's Amplitude MCP server?

You can take the following steps:

1. Create or log into your Merge Agent Handler account and navigate to Tool Packs (collections of connector tools scoped to a specific use case).

2. Create a new Tool Pack, then find and enable the Amplitude connector. Choose which tools to include: enable read tools like <code class="blog_inline-code">get_funnel</code> and <code class="blog_inline-code">get_retention</code> for analysis use cases, or add write tools like <code class="blog_inline-code">create_annotation</code> and <code class="blog_inline-code">update_cohort_membership</code> if your agent needs to annotate releases or manage cohort data.

3. Add a Registered User inside the Tool Pack. This is the identity context under which your agent operates. Merge generates a unique MCP URL scoped to this user once it's created.

4. From the Registered User detail page, authenticate Amplitude by completing the credential flow. Merge stores and manages the credentials going forward.

5. Copy the MCP URL from the Tool Pack detail page and generate an API key from Settings. You'll need both to connect your agent.

6. Add the MCP server to your agent or IDE using the MCP URL and API key. Your Amplitude tools are now accessible through that endpoint.