--- canonical_url: "https://docs.composio.dev/toolkits/amplitude_mcp" markdown_url: "https://docs.composio.dev/toolkits/amplitude_mcp.md" product: "platform" version: null last_updated: null --- # Amplitude MCP Amplitude MCP lets authorized agents analyze product data, manage charts, dashboards, cohorts, experiments, taxonomy, and related Amplitude workspace resources. - **Category:** model context protocol - **Auth:** DCR_OAUTH - **Composio-managed OAuth available?** No - **Tools:** 48 - **Triggers:** 0 - **Slug:** `AMPLITUDE_MCP` - **Version:** 20260918_00 ## Tools ### Create group types **Slug:** `AMPLITUDE_MCP_CREATE_GROUP_TYPES` Create one or more group types in a project, OR add already-ingested group types with status "unexpected" to the tracking plan. A group type is a category of group that users can belong to (for example "Company", "Account", "Team", "Workspace", "Organization"). The Amplitude Accounts add-on lets you analyse product usage at the group level rather than per individual user. NOTE: group TYPES are the categories themselves — use create_properties with propertyType "group" to add attributes (e.g. company name, plan tier) to an existing group type. When a user says "create a group type" without further qualification, or "add to plan" for an unexpected group type, use this tool. Specify whether each item is unexpected with `isUnexpected`. If `isUnexpected` is true, the group type must already exist in the project as observed-but-unexpected and will be added to the tracking plan. If false (default), a brand-new entry is created. INSTRUCTIONS: - Use get_context to get available project IDs first. - Use get_group_types to check which group types already exist before creating new ones. - If the user has not specified a project, prompt the user to decide. Don't decide for them. EXAMPLES: - Minimal: {"projectId": "123456", "groupTypes": [{"name": "Company"}]} - With description: {"projectId": "123456", "groupTypes": [{"name": "Team", "description": "Engineering teams within a company"}]} - Mixed batch (one fresh, one add-to-plan, on a feature branch): {"projectId": "123456", "branchName": "marketing-edits", "groupTypes": [{"name": "Account"}, {"name": "Workspace", "isUnexpected": true}]} # Response Each input item is reported individually in `groupTypes[]` with a `result` of `"created"`, `"addedToPlan"`, or `"failed"` (with a `reason`). Partial successes are preserved: a failure on one item never discards the results of others in the same batch. PERMISSIONS: - This tool requires the "Update Tracking Plan" permission and may fail with a 403. Don't pre-warn the user; if it fails, surface the error and note that an admin may need to grant access. # Workspace warnings Be sure you have information on the workspace settings and environments from get_workspace_context before using this tool. If the workspace has more than one environment, warn the user that the change will apply across multiple environments. If the main branch is protected (workspace setting approvalWF is "Required"), let the user know that changes cannot be made on the default branch and they will have to first create a new branch and make changes on that. NOTES: - A group type with the same name cannot already exist on the targeted branch — that item will be marked as failed. - Branch targeting: unless specified, the default branch is used. Pass either branchId or branchName, not both. - `description` is only allowed on brand-new group types (isUnexpected: false). Unexpected items added to the plan cannot include metadata at the same time — add them first, then use a follow-up tool call to set the description. USER-INTERFACING LANGUAGE: When relaying results to the user, do not surface internal mechanics. - Refer to the default branch as "main", not "default branch". - Say "unexpected group types" not "isUnexpected group types". - Say "added to the tracking plan" rather than using field names like "addedToPlan". - Say "branch approval setting" not "approvalWF". - Do not mention "mutations", "versionId", "stagingVersionId", "propertyPath", branch IDs, or GraphQL details to the user. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `branchId` | string | No | Optional branch ID to target a non-default branch. If omitted, the project's default branch is used. Mutually exclusive with branchName. | | `projectId` | string | Yes | Project ID to create the group types in. If the user has not specified a project, prompt the user to decide. Dont decide for them. | | `rationale` | string | No | Brief explanation of why you are calling this tool and what you expect to learn from the result. | | `branchName` | string | No | Optional branch name to target a non-default branch (e.g. "my-edits-branch"). If omitted, the project's default branch is used. Mutually exclusive with branchId. | | `groupTypes` | array | Yes | Array of group types to create or add to plan | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | array | Yes | Array of content blocks returned by the tool | ### Create properties **Slug:** `AMPLITUDE_MCP_CREATE_PROPERTIES` Create one or more properties in a project's tracking plan. Use propertyType to select which kind of properties to create. PROPERTY TYPES: | propertyType | What it creates | Key params | |---|---|---| | event | Event properties (global or event-scoped) | properties[].eventType (omit for global) | | user | User-level properties | properties[].type, regex, enumValues | | group | Group properties (e.g., company_name, plan_tier) for a group type | groupType, properties[] | INSTRUCTIONS: - If a user says "create a property" without specifying a type, ask them to clarify which type they mean: event, user, or group. - If a user says "create a property on an event," assume they mean an event property — propertyType "event" is the default for that phrasing. - Derived properties, profile properties, lookup properties, computed properties, and persisted properties are NOT supported via MCP tools. If the user asks to create one of these, let them know that this property type is not currently supported through MCP tools. - If the user has not specified a project, prompt them to decide. Don't decide for them. PERMISSIONS: - This tool requires the "Update Tracking Plan" permission and may fail with a 403. Don't pre-warn the user; if it fails, surface the error and note that an admin may need to grant access. # Workspace warnings Be sure you have information on the workspace settings and environments from get_workspace_context before using this tool. If the workspace has more than one environment, warn the user that the change will apply across multiple environments. If the main branch is protected (workspace setting approvalWF is "Required"), let the user know that changes cannot be made on the default branch and they will have to first create a new branch and make changes on that. NOTES BY PROPERTY TYPE: - group: Group properties describe attributes of a group type (e.g., company name, plan tier). Accepts a group type name (e.g., "org id", "Company") — the tool resolves it to the correct ID internally. If no branch is specified, defaults to the main branch. EXAMPLES: - Event property (global): { "propertyType": "event", "projectId": "123", "properties": [{ "name": "page_url", "type": "string" }] } - Event property (event-scoped): { "propertyType": "event", "projectId": "123", "properties": [{ "name": "button_name", "eventType": "Button Clicked", "type": "string" }] } - Event properties (mixed: one fresh, one add-to-plan, on a feature branch): { "propertyType": "event", "projectId": "123", "branchName": "marketing-edits", "properties": [{ "name": "page_url", "type": "string" }, { "name": "button_name", "eventType": "Button Clicked", "isUnexpected": true }] } - User property: { "propertyType": "user", "projectId": "123", "properties": [{ "name": "plan_type", "type": "string" }] } - Group properties: { "propertyType": "group", "projectId": "123", "groupType": "Company", "properties": [{ "name": "plan_tier", "type": "string" }] } USER-INTERFACING LANGUAGE: When relaying results to the user, do not surface internal mechanics. - Refer to the default branch as "main", not "default branch". - Say "event property", "user property", or "group property" not "propertyType". - Say "unexpected" or "unplanned" not "isUnexpected" when describing properties not yet in the plan. - Say "array type" not "isArrayType", "hidden" not "isHidden", "enum values" not "enumValues", and "classification" not "classifications". - Say "branch approval setting" not "approvalWF". - Do not mention "mutations", "versionId", "stagingVersionId", branch IDs, or GraphQL details to the user. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `branchId` | string | No | Optional branch ID to target a non-default branch. If omitted, the project's default branch is used. Mutually exclusive with branchName. | | `groupType` | string | No | Name of the group type the properties belong to (e.g., "org id", "Company"). The tool resolves this to the correct ID. Omit to create global group properties (not scoped to any group type). | | `projectId` | string | Yes | Project ID to create event properties in. If the user has not specified a project, prompt the user to decide. Dont decide for them. | | `branchName` | string | No | Optional branch name to target a non-default branch (e.g. "my-edits-branch"). If omitted, the project's default branch is used. Mutually exclusive with branchId. | | `properties` | array | Yes | Array of event properties to create | | `propertyType` | string ("event" | "user" | "group") | Yes | Discriminator: determines which set of parameters applies (event | user | group) | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | array | Yes | Array of content blocks returned by the tool | ### Delete event properties **Slug:** `AMPLITUDE_MCP_DELETE_EVENT_PROPERTIES` Delete one or more event properties in a project. Each requested property is routed by whether eventType is provided: - eventType provided → per-event delete (scoped to that one event): - live on this event → marked as deleted on this event (restorable). - planned on this event → the property-event link is removed on this event only (does NOT affect other events). - unexpected on this event → added to the plan as deleted on this event. - eventType omitted → plan-wide delete (across all events): - live → marked as deleted (restorable). - planned → removed entirely (NOT restorable; you'd have to recreate). Affects all events that used the property. - unexpected → added to the plan as deleted. A single call may mix both — each entry is routed independently. Amplitude-owned properties cannot be deleted. # Before deleting Before an event-property delete, pass includeDeleted: true when looking up which events are using the property so deleted attachments are also included. # Warning Marking an ingested event property as deleted stops ingestion until restored (immediately on main; after merge on other branches). A delete on a non-main tracking-plan branch does not drop live ingest until that branch is merged into main. Removing a planned property does not stop ingestion — it was never ingested. Always surface this to the user before they confirm. # Confirmation This is a destructive taxonomy mutation. Mark as deleted and remove both use the same confirmation gate — never skip it. The first call returns a confirmation_required response showing the bucketed actions, project, and branch; relay that and its warning field to the user. Only call again with confirmed: true after the user explicitly acknowledges. Do not pass confirmed: true on the first call. # Branch targeting Unless specified, the default branch is used. To apply changes to a non-default branch, pass either branchId or branchName. If the user references a branch by name (e.g. "my-edits-branch"), use branchName. Pass only one. # Permissions This tool requires the "Update Tracking Plan" permission and may fail with a 403. Don't pre-warn the user; if it fails, surface the error and note that an admin may need to grant access. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `branchId` | string | No | Optional branch ID to target a non-default branch. If omitted, the project's default branch is used. Mutually exclusive with branchName. | | `confirmed` | boolean | No | Set to true only after the user has explicitly acknowledged the actions and branch shown in the prior confirmation_required response. Required for mark as deleted and remove alike. Omit (or pass false) on the first call. | | `projectId` | string | Yes | Project ID to delete event properties from. If the user has not specified a project, prompt the user to decide. Dont decide for them. | | `rationale` | string | No | Brief explanation of why you are calling this tool and what you expect to learn from the result. | | `branchName` | string | No | Optional branch name to target a non-default branch (e.g. "my-edits-branch"). If omitted, the project's default branch is used. Mutually exclusive with branchId. | | `properties` | array | Yes | Array of event properties to delete | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | array | Yes | Array of content blocks returned by the tool | ### Delete user properties **Slug:** `AMPLITUDE_MCP_DELETE_USER_PROPERTIES` Delete one or more user properties in a project. Properties that are planned and ingested are marked as deleted (restorable). Properties that are planned but never ingested are removed. Properties ingested but not in the plan are added to the plan as deleted. When a name exists as both customer and Amplitude, only the customer property is targeted. # Warning Marking ingested properties as deleted (toMarkAsDeleted) stops ingestion until restored (immediately on main; after merge on other branches). A delete on a non-main tracking-plan branch does not drop live ingest until that branch is merged into main. Removing planned properties (toRemove) does not stop ingestion — they were never ingested and cannot be restored. Always surface both buckets and this warning to the user before they confirm. This tool only deletes customer-defined user properties. Amplitude-owned user properties cannot be deleted and are always skipped — tell the user if any were requested. # Confirmation This is a destructive taxonomy mutation. Mark as deleted and remove both use the same confirmation gate — never skip it. The first call returns a confirmation_required response listing the bucketed properties, project, and branch; relay that and its warning field to the user. Only call again with confirmed: true after they explicitly acknowledge. Do not pass confirmed: true on the first call. # Branch targeting Unless specified, the default branch is used. To apply changes to a non-default branch, pass either branchId or branchName. If the user references a branch by name (e.g. "my-edits-branch"), use branchName. Pass only one. # Permissions This tool requires the "Update Tracking Plan" permission and may fail with a 403. Don't pre-warn the user; if it fails, surface the error and note that an admin may need to grant access. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `branchId` | string | No | Optional branch ID to target a non-default branch. If omitted, the project's default branch is used. Mutually exclusive with branchName. | | `confirmed` | boolean | No | Set to true only after the user has explicitly acknowledged the properties and branch shown in the prior confirmation_required response. Required for mark as deleted and remove alike. Omit (or pass false) on the first call. | | `projectId` | string | Yes | Project ID to delete user properties from. If the user has not specified a project, prompt the user to decide. Dont decide for them. | | `rationale` | string | No | Brief explanation of why you are calling this tool and what you expect to learn from the result. | | `branchName` | string | No | Optional branch name to target a non-default branch (e.g. "my-edits-branch"). If omitted, the project's default branch is used. Mutually exclusive with branchId. | | `propertyNames` | array | Yes | Array of user property names to delete | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | array | Yes | Array of content blocks returned by the tool | ### Get agent results **Slug:** `AMPLITUDE_MCP_GET_AGENT_RESULTS` Retrieve results from AI agents that have analyzed your dashboards or session replays. This is NOT for searching dashboards, charts, or notebooks — use 'search' for that. This is specifically for retrieving the AI-generated insights and analyses that agents produced. This tool handles both searching for agent analyses and fetching full results in a single call. MODES: 1. **Search mode** (no session_id): Search agent analyses with filters. Returns preview summaries. 2. **Direct fetch mode** (session_id provided): Fetch full artifact data for a specific session. 3. **Auto-expand**: If search returns exactly 1 session, full artifacts are included automatically. SEARCH STRATEGY (important — follow this order): 1. If you have a specific session_id, use direct fetch mode. 2. For dashboard analyses, pass agent_params with dashboard_id (cheap exact-match). 3. For session replay insights, use agent_params with category and/or impact (cheap exact-match). 4. Use "query" ONLY for natural language / fuzzy search when exact filters aren't sufficient. WHEN TO USE: - "What are my dashboard agents?" → agent_type: dashboard_explorer - "Show my agent results" → agent_type: dashboard_explorer (or session_replay_explorer) - "What agents have I run?" → agent_type: dashboard_explorer - "What analyses exist for dashboard xyz?" → agent_type: dashboard_explorer, agent_params: { dashboard_id: "xyz" } - "Show me high-impact session replay insights" → agent_type: session_replay_explorer, agent_params: { impact: "High" } - "Friction hotspots in the checkout flow" → agent_type: session_replay_explorer, agent_params: { category: "Friction Hotspots" }, query: "checkout flow" - "What did the AI find about rage clicks?" → agent_type: session_replay_explorer, query: "rage clicks" - "Any dashboard insights about revenue?" → agent_type: dashboard_explorer, query: "revenue" - "Show me insights from last week" → agent_type: session_replay_explorer, created_after: "2026-03-16T00:00:00Z" - "What did I analyze recently?" → agent_type: dashboard_explorer DO NOT USE FOR: - Finding or listing dashboards, charts, or notebooks → use 'search' instead - Running new analyses or queries → use 'query_dataset' or 'query_charts' instead - Creating dashboards → use 'create_dashboard' instead RETURNS: - Search mode: List of analysis sessions with preview summaries, URLs, and pagination info - Direct fetch mode: Full artifact data for the session - Links to view each session in the Amplitude UI are included #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | Maximum number of results to return (default: 10). | | `query` | string | No | Free-text semantic search query (uses vector embeddings). Best for natural language discovery: "rage clicks on save button", "dashboard showing revenue drop", "friction in onboarding flow". This is EXPENSIVE (generates an embedding) — prefer exact filters when you have specific values. | | `offset` | integer | No | Pagination offset. Use with limit to page through results. Start at 0 (default). | | `rationale` | string | No | Brief explanation of why you are calling this tool and what you expect to learn from the result. | | `agent_type` | string ("dashboard_explorer" | "session_replay_explorer") | Yes | Type of agent analysis to search for. "dashboard_explorer" finds AI-generated dashboard analysis summaries. "session_replay_explorer" finds AI-generated UX insights from session replay analysis. | | `session_id` | string | No | Specific session ID to fetch full artifacts for. When provided, returns full artifact data and other filters are ignored. Get session IDs from a previous search. | | `agent_params` | object | No | Agent-type-specific filter parameters as a JSON object. For dashboard_explorer: { "dashboard_id": "xyz" }. For session_replay_explorer: { "category": "Friction Hotspots", "impact": "High" }. Valid categories: Journeys & Navigation, Forms & Input, Content, Conversion, Friction Hotspots, Retention. Valid impacts: Low, Medium, High. | | `created_after` | string | No | ISO 8601 date string. Only return sessions with analysis artifacts created after this date. Filters by artifact time, not session creation time. Example: "2025-03-01T00:00:00Z" for analyses run since March 2025. | | `created_before` | string | No | ISO 8601 date string. Only return sessions with analysis artifacts created before this date. Use with created_after for a date range. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | array | Yes | Array of content blocks returned by the tool | ### Get amplitude agent analytics info **Slug:** `AMPLITUDE_MCP_GET_AMPLITUDE_AGENT_ANALYTICS_INFO` Single read entry point for Amplitude Agent Analytics (AI/LLM session investigation). NOT FOR: Customer product feedback (use use_amplitude_ai_feedback) or browser Session Replay. Set `view` to choose the read route (each view has its own parameters in the tool schema): - `schema` — fields, rubrics, taxonomy, filter_options. Use only when an exact filter identifier is not already known; request only the needed filterOptionTypes. - `sessions` — filtered session lists and groupBy aggregations (replaces metrics/timeseries tools). - `conversation` — full transcript; sessionId is required. - `spans` — per-operation trace; sessionId or traceId is required (no org-wide scans). - `tool_reliability` — metrics enum is only tool_stats | tool_definitions. REMOVED (use sessions filters instead): - search_agent_analytics_conversations (ILIKE scans) - query_agent_analytics_metrics quality/cost/topics/timeseries enums EXAMPLES: - Agent names: { "view": "schema", "projectId": "12345", "include": ["filter_options"], "filterOptionTypes": ["agent_names"] } - Failed sessions: { "view": "sessions", "projectId": "12345", "hasTechnicalFailure": true, "agentNames": ["global-chat"] } - Transcript: { "view": "conversation", "projectId": "12345", "sessionId": "abc-123" } - Tool reliability: { "view": "tool_reliability", "projectId": "12345", "metrics": ["tool_stats","tool_definitions"], "agentNames": ["global-chat"] } #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `view` | string ("schema" | "sessions" | "conversation" | "spans" | "tool_reliability") | Yes | Discriminator: determines which set of parameters applies (schema | sessions | conversation | spans | tool_reliability) | | `limit` | integer | No | Max sessions per page (1-50, default 50). Use cursor for additional pages. | | `cursor` | string | No | Pagination cursor from previous response | | `status` | string | No | Filter by session status (e.g., "open", "closed") | | `endDate` | string | No | ISO 8601 end date (e.g., "2026-02-01"). Defaults to now. | | `groupBy` | array | No | Group by session-level field for aggregations. Options: agent_name, customer_org_id, user_id, project_id, parent_agent_name, source_system. | | `include` | array | No | Sections to return. Enum: fields | rubrics | taxonomy | filter_options. Pass a JSON array, not a string. | | `metrics` | array | No | Only tool_stats and/or tool_definitions (not quality, cost, or timeseries — use view=sessions for those). | | `orderBy` | string | No | DEPRECATED for enrichment sorts (quality_score, sentiment_score). Default ordering is session_start DESC. | | `traceId` | string | No | Trace whose spans to fetch. Required unless sessionId is set. | | `userIds` | array | No | Filter by user IDs (e.g., ["user@example.com"]) | | `toolName` | string | No | Filter by tool name | | `cohortIds` | array | No | Filter to sessions whose user belongs to ANY of these Amplitude cohort IDs. Requires projectId. | | `datasetId` | string | No | Filter to sessions in a specific gold dataset (by dataset ID). Use get_agent_analytics_schema to discover dataset IDs and names. | | `modelName` | string | No | Filter by model name | | `projectId` | string | Yes | Amplitude project id to scope filter_options to. Required. Call get_amplitude_context with no arguments first to list the projects you can access, then pass an id from that list — do NOT guess project ids. | | `rationale` | string | No | Brief explanation of why you are calling this tool and what you expect to learn from the result. | | `sessionId` | string | No | The session ID to get conversation turns for (required) | | `startDate` | string | No | ISO 8601 start date (e.g., "2026-01-01"). Defaults to 7 days ago. | | `toolNames` | array | No | Filter by tool names used in sessions. Use get_agent_analytics_schema to discover available names. | | `agentNames` | array | No | Filter by agent names (e.g., ["global-chat", "Chart Agent"]) | | `maxCostUsd` | number | No | Maximum total cost in USD | | `minCostUsd` | number | No | Minimum total cost in USD | | `sessionIds` | array | No | Filter by specific session IDs | | `closeReason` | string | No | DEPRECATED — will error. Use evalFilters instead. | | `datasetName` | string | No | Filter to sessions in a gold dataset by name (case-insensitive exact match, else first substring match). Resolves to a dataset ID. | | `emailDomain` | string | No | DEPRECATED — will error. | | `evalFilters` | array | No | Primary filter: modular evaluator results. Example for GAE2 data mismatch: [{"evaluatorId":"01KS3TGK1732EXA7EP0AAFVPN6","evaluatorType":"categorical","values":["RESP_DATA_RESPONSE_MISMATCH"]}] | | `evalSuiteId` | string | No | Restrict to sessions evaluated by any evaluator in this suite | | `searchQuery` | string | No | Search filter: partial user_id match or exact session_id match. Prefix with - to exclude. | | `userIntents` | array | No | Filter by OOTB User Intent L1 labels from [Agent] Session Record (e.g. ["Information Request", "Task Execution"]). NOT Topic Intelligence clusters — use clusterStableId for those. | | `clusterRunId` | string | No | Topic Intelligence clustering run id. Required when using clusterStableId or subStableClusterId. | | `customerName` | string | No | Filter by customer org name (fuzzy match, e.g., "eBay" matches "eBay Inc"). Resolves name to org IDs. | | `maxTurnCount` | integer | No | DEPRECATED — will error. | | `minTurnCount` | integer | No | DEPRECATED — will error. | | `componentType` | string ("llm" | "tool" | "embedding") | No | Filter by span component type | | `maxDurationMs` | integer | No | Maximum session duration in milliseconds | | `minDurationMs` | integer | No | Minimum session duration in milliseconds | | `primaryTopics` | array | No | DEPRECATED — will error. Use evalFilters instead. | | `customerOrgIds` | array | No | Filter by customer org IDs (string IDs, e.g., ["12345"]) | | `hasTaskFailure` | boolean | No | Filter sessions with task failures (compat shim → task_failure eval) | | `responseFormat` | string ("concise" | "detailed") | No | 'concise' returns session summaries. 'detailed' includes full enrichment data. Default: concise. | | `clusterStableId` | string | No | Filter to sessions in this Topic Intelligence L1 cluster. Requires clusterRunId from query_topic_clusters. | | `maxQualityScore` | number | No | DEPRECATED — will error. Use evalFilters instead. | | `minQualityScore` | number | No | DEPRECATED — will error. Use evalFilters instead. | | `overallOutcomes` | array | No | DEPRECATED — will error. Use evalFilters instead. | | `parentAgentName` | string | No | Filter by parent agent name (for sub-agent delegation sessions) | | `filterOptionTypes` | array | No | Filter option catalogs to fetch. Enum: agent_names | tool_names | evaluators | datasets. Request only the catalogs needed; omitted returns all. | | `includeCategories` | boolean | No | Include per-turn category annotations (e.g., topic, intent) | | `maxSentimentScore` | number | No | DEPRECATED — will error. Use evalFilters instead. | | `minSentimentScore` | number | No | DEPRECATED — will error. Use evalFilters instead. | | `includeAnnotations` | boolean | No | Attach per-session human "comments" (notes) and "labels" (tags) to each returned session. Fetched for up to 100 returned sessions. | | `subStableClusterId` | string | No | Filter to sessions in this Topic Intelligence L2 subtopic. Requires clusterRunId. | | `hasNegativeFeedback` | boolean | No | Filter sessions with negative feedback (compat shim → negative_feedback eval) | | `hasTechnicalFailure` | boolean | No | Filter sessions with/without technical failures (system-level crashes/exceptions) | | `toolDefinitionsHash` | string | No | Filter spans that used this tool-definitions hash | | `topicClassifications` | object | No | DEPRECATED — will error. Use evalFilters instead. | | `evaluatorResultFormat` | string ("none" | "summary" | "full") | No | Controls evaluator_results per session. 'none' skips them, 'summary' returns compact outcomes, and 'full' returns complete result JSON. Default: full for backward compatibility. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | array | Yes | Array of content blocks returned by the tool | ### Get amplitude charts **Slug:** `AMPLITUDE_MCP_GET_AMPLITUDE_CHARTS` Read saved Amplitude charts by ID, or look up the chart-type schema. One tool with five output modes selected by `include` (default `link`). OUTPUT MODES: - `link` (default) → 'get_chart_link': validates each id exists, then returns the chart's URL(s). Does not run the chart — cheap id lookup only. - `typed` → 'lower_chart': returns the chart as typed UI-shaped parameters (`kind` + events/where/group_by/…) — the same shape `query_amplitude_data`'s `chart` parameter accepts. Prefer this when creating a variant of an existing chart or preparing a modification: edit the typed object, then call `query_amplitude_data` with `chart` (+ `chartId` to fork/modify the saved chart). - `definition` → 'get_charts': returns the full raw Amplitude definition object(s). Use when `typed` cannot lower the chart (advanced features) or you need fields the typed model does not cover. - `data` → 'query_charts': runs the chart(s) and returns the result data. Use when you need the numbers. - `guide` → 'get_chart_definition_params': no ids needed. Pass `chartType` to get that type's parameter schema, valid enum values, and a working example definition — use BEFORE calling `query_amplitude_data` if you are unsure of the shape, or to look up valid enum values (e.g. funnel modes, segmentation metrics). Omit `chartType` to list all supported chart types. NOTE: This schema describes chart STRUCTURE only (params, enums, example) — it does NOT validate event or property names against your project's taxonomy. An unrecognized event/property key will NOT error; it silently returns a chart with empty data. Before building, confirm exact spelling via 'search', 'get_properties' (propertyType="event"), or get_amplitude_charts include='definition' on a similar existing chart — never guess a key name. PREREQUISITES (required): - For `link` / `typed` / `definition` / `data`: you MUST have at least one concrete `chartIds` or `chartEditIds` entry. Do not call speculatively. Resolve ids FIRST via `search` (by name), `get_from_url` (from a chart link), or `query_amplitude_data` (for ad-hoc analysis, which returns a chart edit id). - For `guide`: no ids required; `chartType` is optional (omit to list all supported types). INSTRUCTIONS: - Create a new chart: `search` (taxonomy) → build typed `chart` → `query_amplitude_data`. - Modify / fork a saved chart: `search` (find chart) → `get_amplitude_charts include='typed'` → edit the returned `chart` → `query_amplitude_data` with that `chart` and `chartId` set to the saved chart id. - Saved charts → `chartIds`. Chart edits (links ending in /chart/new/ or /chart//edit/) → `chartEditIds`. - `typed` and `definition` modes support `chartIds` only. For a chart edit's data use `data` mode. - `data` mode accepts up to 3 ids/edits combined. - The data params (`groupByLimit`, `excludeIncompleteDatapoints`, `timeSeriesLimit`) only apply when `include = 'data'`. `chartType` only applies when `include = 'guide'`. DO NOT USE FOR: - Ad-hoc analysis without a saved chart → use 'query_amplitude_data'. - Finding charts by name → use 'search'. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `vis` | string ("line" | "area" | "bar" | "pie" | "stackedbar") | No | data mode only: override the eventsSegmentation visualization type (line, area, bar, pie, stackedbar). Used by the chart widget vis switcher. | | `theme` | string ("light" | "dark") | No | data mode only: fetch only this theme of an eventsSegmentation Highcharts config. Used by the chart widget for active-theme-first rendering. | | `include` | string ("link" | "typed" | "definition" | "data" | "guide") | No | What to return: 'link' (default, URL only — free), 'typed' (UI-shaped chart params for query_amplitude_data), 'definition' (raw chart config), 'data' (run the chart), or 'guide' (chart-type parameter schema/enums/example — no ids needed, use chartType). | | `chartIds` | array | No | Saved chart IDs to read. | | `chartType` | string | No | guide mode only: the chart type to get parameter schema/enums/example for. Supported: eventsSegmentation, funnels, metricExplorer, retention, revenueLtv, sessions, stickiness. Omit to list all supported types instead. | | `rationale` | string | No | Brief explanation of why you are calling this tool and what you expect to learn from the result. | | `chartEditIds` | array | No | Chart edit IDs to read (data mode only). | | `groupByLimit` | integer | No | data mode only: max group-by values to return (1-1000, default 10). | | `timeSeriesLimit` | integer | No | data mode only: max group-by values that include per-interval rows (default 6; 0 = totals only). | | `includeAdditionalInfo` | array | No | data mode only: additional render-only information. Omit for compact analytics data; the chart app passes ["chartConfig"]. | | `excludeIncompleteDatapoints` | boolean | No | data mode only: exclude the current (incomplete) interval. Default false. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | array | Yes | Array of content blocks returned by the tool | ### Get amplitude context **Slug:** `AMPLITUDE_MCP_GET_AMPLITUDE_CONTEXT` Unified entry point for Amplitude context. Routes to one of two underlying tools based on whether a `projectId` is provided. ROUTES: - No `projectId` → 'get_context' route: returns the current user, organization (including org-level AI context), and the LIST of accessible projects as `{ appId, appName }`. Use this to discover which projects exist and their ids. - `projectId` provided → 'get_project_context' route: returns that single project's details — description, timezone, currency, session definition, source projects, and project-level AI context. WHEN TO USE: - Session start, "what projects do I have access to?", "show me my org details", "what is my role?" → call with no arguments. - "what timezone / currency / session settings does project X use?", "describe project X" → pass `projectId`. CONTEXT DOCUMENTS (uploaded files): - `org.aiContext` / project `aiContext` are short text fields only. Customers also upload context files (CSV data dictionaries, PDFs, process docs) in Settings → AI Controls; those are indexed for search and never returned in full — only titles (opt-in) or search snippets. - `listContextDocuments: true` adds `contextDocuments` — document titles and ids only, no file contents. Use it when `aiContext` references an uploaded file by name (e.g. "always check before answering"). - `searchContextDocuments` runs semantic search over the uploaded documents' contents and adds `contextDocumentSearch` with matching text snippets. Use specific terms from the user's question (event names, property names, column names). - Scope for both: without `projectId`, org-level documents only; with `projectId`, org-level plus that project's documents. EXAMPLES: - Session start: {} - Project settings: {"projectId": 12345} - aiContext says "check the event dictionary file" → {"projectId": 12345, "listContextDocuments": true} - Look up a term from uploaded docs: {"projectId": 12345, "searchContextDocuments": "envelope_event_type_id"} NOTES: - `projectId` is optional on purpose. Omit it to get the project list first, then call again with a real id from that list — do NOT guess project ids. - The two layers are meant to be loaded together: call once without `projectId` at session start for org context, then with a `projectId` to drill into a project. On conflict, project-level context overrides org-level. - Omit `listContextDocuments` and `searchContextDocuments` at session start — they add latency and are only useful once you know what to look for. DO NOT USE FOR: - Running analytics queries → use 'query_dataset'. - Finding charts/dashboards/cohorts → use 'search'. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `projectId` | integer | No | The project/app id to fetch detailed context for. Omit to get org context plus the list of projects you can access (the 'get_context' route); provide it to fetch one project's settings (the 'get_project_context' route). | | `rationale` | string | No | Brief explanation of why you are calling this tool and what you expect to learn from the result. | | `listContextDocuments` | boolean | No | When true, adds contextDocuments: titles and ids of the customer's uploaded context files (no file contents). Without projectId lists org-level documents; with projectId also includes that project's documents. Omit at session start. | | `searchContextDocuments` | string | No | Semantic search query over the contents of uploaded context documents. Adds contextDocumentSearch with matching text snippets. Without projectId searches org-level documents; with projectId also searches that project's documents. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | array | Yes | Array of content blocks returned by the tool | ### Get amp session replay info **Slug:** `AMPLITUDE_MCP_GET_AMP_SESSION_REPLAY_INFO` Unified entry point for session replay data: find replays and inspect what happened in them. Replaces get_session_replays, list_session_replays, get_session_replay_events, and get_session_replay_timeline. ACTIONS: - `search` (default): find replays by event / user-property / cohort filters, by Amplitude user (`userId`), by ID (`sessionReplayIds`), or sample recent sessions with no filters (random slice from the last 24 hours). - `list`: simple paginated time-range listing via the public Session Replay API (`start_time`/`end_time`/`page_size`/`page_token`). Use `search` instead when filtering by events or user properties. - `events`: processed rrweb interaction timeline for one replay (`sessionReplayId`) — page navigations, clicks, inputs, scrolls. - `timeline`: full analytics event timeline for one replay (`sessionReplayId`) — every event the user fired during and around the session. PREFER THIS over user-timeline tools when you have a replay ID. REQUIRED FOLLOW-UP — render_amp_session_replay: - After `search`/`list` return replay IDs, you MUST call `render_amp_session_replay` in the SAME turn whenever the user's request implies viewing the replays ("show me", "let me see", "pull up", "watch", "play", "open", or any phrasing where seeing the replays is the deliverable). A list of IDs alone is not the answer the user wants. - ONLY skip the render call for raw data extraction ("just count them", "export the IDs"). When in doubt, render. INSTRUCTIONS: - Provide `projectId` for every action. - Replay IDs use the "/" format — pass them verbatim between actions. - search: filters are ANDed; reference real event names (call get_events first if unsure). `userId` and `sessionReplayIds` are mutually exclusive with each other and with filters. - list: use the returned next_page_token to fetch subsequent pages; keep sort_order consistent across pages. The list response's start/end times describe the analytics session window, NOT the recorded replay length. - events vs timeline: `events` shows what the user DID in the recording (clicks/inputs/navigation from rrweb); `timeline` shows which analytics EVENTS fired (with properties). For "walk me through this session" prefer `timeline`. EXAMPLES: - Sample recent sessions: { "projectId": "12345" } - Users who hit checkout errors: { "action": "search", "projectId": "12345", "events": [{ "name": "Checkout", "withProperty": { "name": "error_type", "exists": true } }] } - Replays for a user yesterday: { "action": "search", "projectId": "12345", "userId": "98765", "since": "yesterday" } - Paginated listing: { "action": "list", "projectId": "12345", "page_size": 50, "sort_order": "desc" } - What the user did in a replay: { "action": "events", "projectId": "12345", "sessionReplayId": "device-abc/1773235450374" } - Events fired during a replay: { "action": "timeline", "projectId": "12345", "sessionReplayId": "device-abc/1773235450374", "includeEventProperties": true } NOTES: - search defaults: 10 results; 30-day window for filtered queries, 24 hours otherwise. If a filtered search is empty, widen the window or relax filters instead of retrying unchanged. - list defaults to the last 48 hours when no time range is provided. - Cohort filters take numeric IDs only — resolve names with get_cohorts first. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `on` | string | No | Single-day shorthand: "YYYY-MM-DD" or relative ("yesterday", "today"). Expands to a 24-hour window centered on that day. Mutually exclusive with `since`/`until`. | | `limit` | integer | No | Max sessions to return. Defaults to 10. | | `since` | string | No | Start of the search window. ISO 8601 ("2025-01-15T00:00:00Z"), Unix epoch ms or seconds, or a relative phrase ("yesterday", "7 days ago", "last week"). Defaults to 30 days ago for filtered queries; 24 hours ago for direct-ID lookups and the no-conditions sample. | | `until` | string | No | End of the search window. Same flavors as `since`. Defaults to now. | | `action` | string ("search" | "list" | "events" | "timeline") | No | Session replay operation: 'search' | 'list' | 'events' | 'timeline'. Defaults to search. | | `events` | array | No | Filter to sessions where the user performed these events. Each entry is ANDed within the same session by default (see `matchScope`). | | `userId` | string | No | Fetch sessions for one Amplitude user (the numeric `amplitude_id`). Mutually exclusive with `sessionReplayIds` and with filters. | | `cohorts` | array | No | Filter to users in these cohorts. Accepts numeric cohort IDs only — call get_cohorts to resolve a cohort name to its ID first. | | `version` | number | No | events: recording format version, 3 (default) or 2 (legacy). Allowed values: 2, 3. | | `end_time` | string | No | list: ISO 8601 upper bound. Defaults to now. | | `page_size` | number | No | list: results per page (1-200, default 50). | | `projectId` | string | Yes | The Amplitude project ID (appId) as a string (e.g. "12345", "678910"). To find the project ID, check the URL or project context. | | `randomize` | boolean | No | Shuffle results before returning. Use true for analysis sampling. Implied (with a 24-hour window) when no filters and no direct selectors are supplied. | | `rationale` | string | No | Brief explanation of why you are calling this tool and what you expect to learn from the result. | | `eventLimit` | number | No | timeline: max events to return (default 100, max 1000). | | `matchScope` | string ("session" | "user") | No | How to interpret multiple `events`. "session" (default) returns only replays where every event occurred in the same session — what users typically mean by "find sessions with X and Y". "user" returns all replays of users who satisfied the filters somewhere in the time window, even if a given replay doesn't contain every event. Has no effect when `events` is empty. | | `page_token` | string | No | list: opaque pagination cursor from a previous response. | | `sort_order` | string ("asc" | "desc") | No | list: "asc" (oldest first) or "desc" (newest first, default). | | `start_time` | string | No | list: ISO 8601 lower bound (e.g. "2024-01-01T00:00:00Z"). Defaults to 48 hours ago. | | `event_limit` | number | No | events: max interaction events to return (default 500). | | `amplitude_id` | string | No | list: filter replays to a specific Amplitude user ID. Mutually exclusive with sessionReplayIds. | | `userProperties` | array | No | Filter to sessions whose user matches these property conditions. Each entry is ANDed. | | `sessionReplayId` | string | No | events/timeline: replay ID in "/" format, as returned by search/list. | | `sessionReplayIds` | array | No | search: fetch specific replays by "device_id/session_id" (max 100; mutually exclusive with userId and filters). list: filter the listing to these replay IDs (mutually exclusive with amplitude_id and page_token). | | `includeEventProperties` | boolean | No | timeline: include full event properties (default false). | | `includeExperimentEvents` | boolean | No | timeline: include [Experiment] assignment events (default false). | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | array | Yes | Array of content blocks returned by the tool | ### Get amp taxonomy **Slug:** `AMPLITUDE_MCP_GET_AMP_TAXONOMY` Read a project's tracking plan: the events it defines, the properties on them, what a branch changes relative to main, and who changed what when. # WHEN TO USE — answer questions like: - "What events exist in project 12345?" → { action: "events", projectId: "12345" } - "List the custom events" → { action: "events", kind: "custom", projectId } - "Show custom and labeled events together" → { action: "events", kind: "all", projectId } - "Which properties are on the Purchase event?" → { action: "properties", propertyType: "event", eventType: "Purchase", projectId } - "Which events use button_name?" → { action: "properties", propertyType: "event", names: ["button_name"], projectId } - "What user properties are tracked?" → { action: "properties", propertyType: "user", projectId } - "What does branch feature/v2 change?" / "review this branch before merging" → { action: "branch_changes", branchName: "feature/v2", projectId } - "What changed in the tracking plan last week?" / "who deleted that event?" → { action: "activity", since: "2026-09-01T00:00:00Z", projectId } - Discovering valid event or property names before building a query_dataset filter or group_by This is a fast schema lookup. Do NOT run query_dataset to discover which events or properties exist. # DO NOT USE FOR: - Metrics, counts, trends, funnels, retention → use 'query_dataset' - Creating, updating or deleting taxonomy → use 'manage_amp_events' / 'manage_amp_properties' ACTIONS: | action | What it returns | Key params | |---|---|---| | events | Events in the tracking plan, with status and metadata. `kind` picks the surface: `event` (default, raw), `custom`, `labeled`, or `all` (custom + labeled together). | kind; raw: eventTypes, fields, includeDeleted, branchId/branchName; custom/labeled: customEventNames, customEventIds; both: limit, cursor | | properties | Properties by surface. propertyType selects which: event, user, group, derived, lookup, channel, persisted. | propertyType, eventType, name, sources, groupTypes, names, fields, includeDeleted, includeHidden, includeBlocked, includeTransformations, branchId/branchName | | branch_changes | What a branch adds, removes or updates vs main — events, properties, templates, group types. Use before approving or merging: review_branch reports only a count. `detail` adds per-field before/after; `detailFor` expands only the entities you name. | branchId/branchName, includeMainDrift, detail, detailFor | | activity | Change history: who changed which taxonomy entity and when, newest first. Use for activity logs, "what changed since X", and per-person attribution. `detail` adds stored before/after values. | since, until, entityTypes, changeActions, loginIds, detail, limit, cursor, branchId/branchName | INSTRUCTIONS: - Use get_amplitude_context first to get project IDs. If the user has not specified a project, prompt them to decide. - Raw events and custom/labeled events take different identifiers: `eventTypes` for raw, `customEventNames` / `customEventIds` for custom and labeled. Passing the wrong one is rejected rather than ignored. - Only raw-event reads are branch-aware and take `fields`; custom and labeled events are neither branch-scoped nor field-projected. - Where branch-aware, omit branchId/branchName for the default branch; otherwise pass exactly one selector. - Event and property semantics are unchanged from the tools this replaces — same statuses, same transformation folding, same field projection via fields. - activity reports current state nowhere: use it for "what changed", and events/properties for "what exists now". - activity is NOT a complete audit of everything that changed — say so rather than implying it is. Custom, labeled and autotrack event edits deliberately write no activity record; transformations live in a separate service with no activity log; derived and computed properties are not tracking-plan entities; and newly ingested unexpected events and properties never appear (read `firstSeen` from an events or properties read instead). Passing entityTypes or changeActions narrows further, dropping changes whose activity type has no mapping — sources, tags, group types, and edits made through the API — so an unfiltered query is the only complete view. - activity history belongs to the Data workspace, not the project, so every project sharing that workspace (its dev, staging and EU environments) returns the same rows. The response echoes workspaceId and branch — state that scope. - branch_changes requires exactly one branch selector, and always reports a `comparison` field. "3-way" compares against the point the branch was cut and also returns `mainDrift` and `conflicts`; "2-way" is used when no review is open, may include changes main made after the branch was cut, and cannot report drift or conflicts. Relay that caveat rather than presenting a 2-way result as the branch's own edits. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `kind` | string ("event" | "custom" | "labeled" | "all") | No | events: which event surface. "event" (default) = raw tracking-plan events. "custom" / "labeled" = the custom-or-labeled surface. "all" = custom and labeled together. Same vocabulary as manage_amp_events. | | `name` | string | No | properties + propertyType=user: exact user property name. | | `limit` | number | No | Page size. Prefer exact-name filters over exhaustive listing. action=activity caps at 200. | | `names` | array | No | properties + propertyType=event|derived|channel|persisted: exact names. For event, mutually exclusive with eventType; each row lists the events that use it. | | `since` | string | No | activity: inclusive start of the change window, ISO 8601 timestamp. | | `until` | string | No | activity: inclusive end of the change window, ISO 8601 timestamp. | | `action` | string ("events" | "properties" | "branch_changes" | "activity") | Yes | Which part of the tracking plan to read: "events", "properties", "branch_changes" or "activity". | | `cursor` | string | No | Pagination cursor. | | `detail` | boolean | No | branch_changes: include per-field before/after for updated entities, plus tag, source and property-group deltas. activity: include each change’s stored before/after values. Off by default on both. | | `fields` | array | No | Select response row fields. Valid values depend on the action and propertyType; omit for that surface’s defaults. For action=events the default is the slim set name, displayName, description, status — pass fields to widen it. | | `sources` | array | No | properties + propertyType=user: filter by property source. | | `branchId` | string | No | Optional branch id (mutually exclusive with branchName). | | `loginIds` | array | No | activity: only changes attributed to these Amplitude login IDs. | | `detailFor` | array | No | branch_changes: expand only these entities, by name or id, across every bucket. Use the ids or names from a previous summary. Implies detail, and is not capped — use this when the unfiltered expansion truncates. Unresolvable names come back in detailForUnmatched. | | `eventType` | string | No | properties + propertyType=event: scope to one event; omit to list project-wide. | | `projectId` | string | No | Numeric Amplitude project ID. Optional only when the user has exactly one accessible project. | | `rationale` | string | No | Brief explanation of why you are calling this tool and what you expect to learn from the result. | | `branchName` | string | No | Optional branch name (mutually exclusive with branchId). | | `eventTypes` | array | No | events + kind=event: exact event names to filter to (raw events only). | | `groupTypes` | array | No | properties + propertyType=group: filter to these group types. | | `entityTypes` | array | No | activity: restrict to these entity types. Omit for every recorded change — filtering drops changes whose activity type has no entity mapping (sources, tags, group types, API edits). | | `propertyType` | string ("event" | "user" | "group" | "derived" | "lookup" | "channel" | "persisted") | No | properties: which property surface to read. Defaults to "event". | | `changeActions` | array | No | activity: restrict to these change kinds. Omit for every recorded change; same mapping caveat as entityTypes. | | `includeHidden` | boolean | No | properties: include hidden rows. Defaults true. | | `customEventIds` | array | No | events + kind=custom|labeled|all: filter by custom/labeled event ids. | | `includeBlocked` | boolean | No | properties: include blocked rows. Defaults true. | | `includeDeleted` | boolean | No | Include deleted rows. Defaults false. Pass true before recommending or executing an event-property delete so deleted event–property links are also surfaced. | | `lookupTableName` | string | No | properties + propertyType=lookup: filter to one lookup table. | | `customEventNames` | array | No | events + kind=custom|labeled|all: filter by exact display names (include punctuation/brackets as shown in the UI). | | `includeMainDrift` | boolean | No | branch_changes: also list the entities main changed since the branch was cut, not just the count. Off by default — on a long-lived branch this can exceed the branch's own diff. | | `configurationFilter` | string ("all" | "configured" | "unconfigured") | No | properties + propertyType=lookup: configuration status. | | `derivedPropertyType` | string ("event" | "user") | No | properties + propertyType=derived: narrow to one level. | | `includeTransformations` | boolean | No | properties + propertyType=event|user: include transformations. Defaults true. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | array | Yes | Array of content blocks returned by the tool | ### Get amp user data **Slug:** `AMPLITUDE_MCP_GET_AMP_USER_DATA` Look up Amplitude users. One tool with modes selected by `include` (default `profile`). TWO KINDS OF "USER": - Product users (default): people in project analytics data — use amplitudeId / userId / email / deviceId. - Org teammates (`include='org'`): people with Amplitude login accounts in your org — emails for sharing charts/dashboards/notebooks. PRODUCT LOOKUPS — identify with exactly one of: - `amplitudeId` → exact lookup (fastest, no resolution step). - `userId` → your product's user id; resolved to an amplitudeId first. - `email` → resolved to an amplitudeId (most projects use the email as the user id; a fallback search covers the rest). - `deviceId` → resolved via device-id match (anonymous / pre-login users). - `amplitudeIds` → batch form (max 10); profile mode only. OUTPUT MODES (`include`): - `id` → 'resolve_user_id': resolve identifier to amplitudeId only. - `profile` (default) → 'get_user_profile': identity, properties, groups, usage stats. - `timeline` → 'get_user_timeline': recent event stream. - `both` → profile + timeline. - `org` → 'get_org_users': list org login emails/names for sharing. No product identifier or projectId needed. Pass returned `loginId` values to share tools. INSTRUCTIONS: - `projectId` is required for product modes (id/profile/timeline/both); omit it for `include='org'`. - If a product identifier matches multiple users, the response lists candidates (status 'ambiguous') — re-call with `amplitudeId`. - Experiment-prefixed properties/events are excluded by default; set `includeExperimentData` when debugging experiments. DO NOT USE FOR: - Enumerating product users who performed an event → use 'use_amplitude_cohorts' (action='find'). - Aggregate counts or trends → use 'query_dataset'. - Org role / group / RBAC admin reads → use 'get_org_users' with the matching admin action. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `email` | string | No | Email address to resolve to an amplitudeId. | | `userId` | string | No | Your product's user id; resolved to an amplitudeId first. | | `include` | string ("id" | "profile" | "timeline" | "both" | "org") | No | What to return: 'id', 'profile' (default), 'timeline', 'both', or 'org' (org teammate directory for sharing). | | `deviceId` | string | No | Device ID to resolve to an amplitudeId (anonymous users). | | `projectId` | string | No | Project ID (appId). Required for product modes; omit when include='org'. | | `rationale` | string | No | Brief explanation of why you are calling this tool and what you expect to learn from the result. | | `timestamp` | string | No | timeline/both: ISO 8601 timestamp to anchor the timeline — events before it are returned (default: now). | | `eventLimit` | integer | No | timeline/both: number of events to return (default 50, max 1000). | | `amplitudeId` | string | No | Amplitude ID for exact lookup (provide exactly one identifier). | | `amplitudeIds` | array | No | Batch of Amplitude IDs (max 10); profile mode only. | | `filterEvents` | array | No | timeline/both: only include events with these exact event types. | | `includeExperimentData` | boolean | No | Include [Experiment]-prefixed properties (profile) and assignment events (timeline). Default false. | | `includeEventProperties` | boolean | No | timeline/both: include full event properties (default false for concise output). | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | array | Yes | Array of content blocks returned by the tool | ### Get data warehouse destinations **Slug:** `AMPLITUDE_MCP_GET_DATA_WAREHOUSE_DESTINATIONS` List the Data Warehouse export destinations configured for a project. WHEN TO USE: - You want to see where a project exports its data (Snowflake, BigQuery, S3, etc.), their type, status, and last-export timing. - You need a destination's connection id to inspect its export jobs by passing that id to use_amplitude_data_connections (view: 'jobs', as dataSourceId) — or to get_data_warehouse_jobs if that standalone tool is available in this session. - This is the export-side counterpart of the ingestion-source listing (which lists the import sources feeding the project). INSTRUCTIONS: - Provide the projectId (appId) to list all configured export destinations. - Narrow the list with the optional `type` (matches `eventDestinationType` case-insensitively, whole value, so "SNOWFLAKE" does NOT match SNOWFLAKE_EXPORT_DATASHARE) and `enabled` filters instead of listing everything and scanning client-side. When either is set the response carries `filteredFrom`, the pre-filter count: an empty `destinations` with a non-zero `filteredFrom` means "none matched your filter", NOT "this project has no destinations". Report it that way. - Each destination's `id` is a ready-to-use `falcon:{id}` — pass it as the dataSourceId to use_amplitude_data_connections (view: 'jobs'), or as the connectionId to the standalone get_data_warehouse_jobs tool if that is the one available, to see that destination's export jobs. TIMING FIELDS (three different measurements — NOT three views of one job, and NOT reconcilable 1:1 with get_data_warehouse_jobs): - latestSuccessfulJobStartTime / latestFailedJobStartTime: START (enqueue) time of the most recent successful/failed automatic job, INCLUDING successful runs that exported 0 rows. Format 'YYYY-MM-DD HH:MM:SS' with fractional seconds and no timezone (effectively UTC). - latestExportCompletionTime: a data-export watermark — the COMPLETION time of the most recent successful run that actually exported data. Empty (0-row) successes and failures do NOT advance it, so it can legitimately lag latestSuccessfulJobStartTime by days or months when no new data has arrived. ISO-8601 with 'T' separator, no timezone designator (effectively UTC) — a different format from the two fields above. - RECONCILIATION CAVEAT: get_data_warehouse_jobs hides successful export jobs that exported 0 rows, so a destination can show latestSuccessfulJobStartTime = today while get_data_warehouse_jobs returns no recent SUCCESS job for the same connection. That is expected, not a contradiction. Do not treat these fields as ground truth against the jobs list, and do not conclude from them alone that a data-bearing export ran recently — use latestExportCompletionTime together with the jobs list to confirm actual data delivery. NOTES: - Destinations only (exports); import/ingestion sources are listed separately. - Two kinds of destination are returned. `falcon:{id}` supports job history; `gyrfalcon:{id}` (Snowflake CUSTOM_EVENTS / EVENT_TRANSFORMATIONS, Databricks) does NOT yet — asking for its jobs returns `supported: false`, which does NOT mean it never ran. Judge those on latestSuccessfulJobStartTime / latestFailedJobStartTime / `latestError` (present only on gyrfalcon rows with a recorded error; its absence elsewhere means the backend cannot report one, not that all is well). - If `note` is present, part of the list could not be fetched — say so rather than reporting it as complete. - Responses never include credential fields — only type, status, timing (see TIMING FIELDS), and count fields when Falcon has populated them (see COUNT FIELDS). - COUNT FIELDS: `latestRowsUnloadedCount` / `latestResolvedUserCount` come from Falcon and are often unset. Null is omitted from the response (not a failure). For export row counts, inspect job history via use_amplitude_data_connections (view: 'jobs') or get_data_warehouse_jobs if that standalone tool is available — do not chase missing destination-level counts. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `type` | string | No | Optional: keep only destinations whose eventDestinationType matches this value, case-insensitively (e.g. "SNOWFLAKE", "BIGQUERY", "AMAZON_S3"). Exact match on the whole value — "SNOWFLAKE" does NOT match SNOWFLAKE_EXPORT_DATASHARE. | | `enabled` | boolean | No | Optional: keep only destinations whose enabled flag equals this. Destinations reporting a null enabled flag are excluded by either value, since neither true nor false is known to hold. | | `projectId` | string | Yes | The project ID (appId) to list export destinations for. | | `rationale` | string | No | Brief explanation of why you are calling this tool and what you expect to learn from the result. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | array | Yes | Array of content blocks returned by the tool | ### Get from url **Slug:** `AMPLITUDE_MCP_GET_FROM_URL` Retrieve objects from Amplitude URLs WHEN TO USE: - CRITICAL: Only use this tool for full Amplitude app URLs on supported hosts (app.amplitude.com, app.eu.amplitude.com, apps.stag2.amplitude.com, local.amplitude.com) - You have an Amplitude URL and want to get the full object definition - User shares a link to a dashboard, chart, notebook, experiment, etc. INSTRUCTIONS: - Provide the full Amplitude URL (e.g., https://app.amplitude.com/analytics/myorg/chart/456 or https://app.eu.amplitude.com/analytics/myorg/chart/456) - The tool will parse the URL, validate the organization, and return the full object - Works with charts, dashboards, notebooks, experiments, flags, cohorts, metrics, and opportunities - /chart/new/{id} URLs may refer to a chart draft or a temporary chart edit (from query tools); both are resolved automatically - Agent session URLs (/agents/session/{id}) are not resolvable here — use get_agent_results with the session_id instead #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `url` | string | Yes | Full Amplitude URL to retrieve the object from | | `rationale` | string | No | Brief explanation of why you are calling this tool and what you expect to learn from the result. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | array | Yes | Array of content blocks returned by the tool | ### Get group types **Slug:** `AMPLITUDE_MCP_GET_GROUP_TYPES` List available group types for a project. Group types are the categories of groups (e.g., "Company", "Team", "Account") — NOT the properties/attributes of those groups. WHEN TO USE: - Use this tool to discover what group types exist (e.g., "Company", "Team"). - Use get_properties with propertyType "group" instead if the user is generally asking for group properties (e.g., company_name, plan_tier). NOTES: - Returns group types from the latest staging version of the default branch. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `projectId` | string | Yes | Project ID (appId) to list group types for. Prompt the user if not specified. | | `rationale` | string | No | Brief explanation of why you are calling this tool and what you expect to learn from the result. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | array | Yes | Array of content blocks returned by the tool | ### Get session replay duration **Slug:** `AMPLITUDE_MCP_GET_SESSION_REPLAY_DURATION` APP SUPPORT ONLY. Do not call this tool from the LLM or agent. The session replay app calls this tool to hydrate replay duration metadata without downloading the full replay. Prefer list_session_replays, get_session_replays, get_session_replay_events, or render_amp_session_replay for user-facing tasks. APP INSTRUCTIONS: - Provide projectId and sessionReplayId in "/" format (as returned by list_session_replays / get_session_replays). - Returns durationMs: last event timestamp minus first event timestamp. - Returns null durationMs for empty or single-frame recordings. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `projectId` | string | Yes | The Amplitude project ID (appId) as a string (e.g. "12345", "678910") the replay belongs to | | `rationale` | string | No | Brief explanation of why you are calling this tool and what you expect to learn from the result. | | `sessionReplayId` | string | Yes | Session replay ID in "/" format. Returned from list_session_replays / get_session_replays. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `error` | string | No | | | `success` | boolean | Yes | | | `durationMs` | number | No | | ### Get session replay stream **Slug:** `AMPLITUDE_MCP_GET_SESSION_REPLAY_STREAM` APP SUPPORT ONLY. Do not call this tool from the LLM or agent. The session replay app calls this tool to stream rrweb events for inline playback. The response is base64-encoded gzipped NDJSON and is not useful for text reasoning. If you need to understand what happened in a replay, use get_session_replay_events instead. APP INSTRUCTIONS: - First call: pass projectId + sessionReplayId. Response includes durationMs, events (file 0), and nextCursor. - Continue with nextCursor until it is null. - For duration-only hydration, pass metadataOnly: true. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `cursor` | string | No | Opaque cursor returned by the previous call as `nextCursor`. Omit on the first call. | | `projectId` | string | Yes | The Amplitude project ID (appId) as a string (e.g. "12345", "678910") the replay belongs to | | `rationale` | string | No | Brief explanation of why you are calling this tool and what you expect to learn from the result. | | `metadataOnly` | boolean | No | If true, return only durationMs (no event chunks). Used by the sessions panel to hydrate per-row durations cheaply. | | `sessionReplayId` | string | Yes | Session replay ID in "/" format. Returned from list_session_replays / get_session_replays. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `error` | string | No | | | `events` | string | No | | | `success` | boolean | Yes | | | `durationMs` | number | No | | | `nextCursor` | string | No | | | `eventOffset` | number | No | | | `totalEvents` | number | No | | ### Get session replay timeline **Slug:** `AMPLITUDE_MCP_GET_SESSION_REPLAY_TIMELINE` APP SUPPORT ONLY. Do not call this tool from the LLM or agent. The session replay app calls this tool to hydrate the events panel and user identities. Use get_amp_session_replay_info (action timeline) for user-facing tasks. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `projectId` | string | Yes | The Amplitude project ID (appId) as a string (e.g. "12345", "678910") | | `rationale` | string | No | Brief explanation of why you are calling this tool and what you expect to learn from the result. | | `eventLimit` | number | No | Max number of events to return (default 100, max 1000) | | `sessionReplayId` | string | Yes | Session replay ID in the format "/", e.g. "0c650142-4a68-4f82-ad6a-4f154fee5265/1773235450374" | | `includeEventProperties` | boolean | No | Whether to include full event properties (default false for concise output) | | `includeExperimentEvents` | boolean | No | Whether to include [Experiment] assignment events (default false) | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | array | Yes | Array of content blocks returned by the tool | ### Get tracking plan sources **Slug:** `AMPLITUDE_MCP_GET_TRACKING_PLAN_SOURCES` List the sources configured on a project's tracking plan (e.g. iOS, Android, Web, Server). WHEN TO USE: - You need source IDs before adding sources to an event in the tracking plan. - The user asks what sources are configured on their tracking plan. INSTRUCTIONS: - Pass projectId. - Returns each source's id and name. Use the id when modifying event sources. NOTES: - The Sources UI merges tracking-plan labels with pipeline connections, but this tool returns only the tracking-plan catalog (id + name) for assigning sources to events. Use get_data_ingestion_sources for ingestion status, volumes, and warehouse/import connections. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `projectId` | string | Yes | Project ID to list tracking plan sources for. If the user has not specified a project, prompt the user to decide. Don't decide for them. | | `rationale` | string | No | Brief explanation of why you are calling this tool and what you expect to learn from the result. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | array | Yes | Array of content blocks returned by the tool | ### Get transformations **Slug:** `AMPLITUDE_MCP_GET_TRANSFORMATIONS` Retrieve data transformations from a project. Transformations are data cleaning operations that merge events, merge properties, or map property values. WHEN TO USE: - Use this tool to see what transformations are configured for a project. - Use this tool to understand how events or properties are being merged or remapped. - Use this tool to audit data cleaning rules applied to a project. WHAT IT RETURNS: - A list of transformations with their type, name, description, and configuration details. - Transform types include: merge (merge events), merge_events_derived_prop (merge events with derived property), merge_event_properties, merge_user_properties, map_event_property_values, map_user_property_values. INSTRUCTIONS: - Get the project ID from the context tool. - Optionally filter by transform type to narrow results. - Use pagination to retrieve large lists of transformations. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | number | No | Maximum number of transformations to return (1-500). Use this in conjunction with cursor to paginate through results. | | `cursor` | string | No | Pagination cursor for retrieving the next page of results. Use this in conjunction with limit to paginate through results. | | `projectId` | string | Yes | Project ID to get transformations from. If the user has not specified a project, prompt the user to decide. Dont decide for them. | | `rationale` | string | No | Brief explanation of why you are calling this tool and what you expect to learn from the result. | | `transformType` | string ("merge" | "merge_events_derived_prop" | "merge_event_properties" | "merge_user_properties" | "map_event_property_values" | "map_user_property_values") | No | Optional filter by transformation type. Values: merge, merge_events_derived_prop, merge_event_properties, merge_user_properties, map_event_property_values, map_user_property_values. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | array | Yes | Array of content blocks returned by the tool | ### Manage amp context **Slug:** `AMPLITUDE_MCP_MANAGE_AMP_CONTEXT` Manage AI context. Actions: `set_org_context` and `set_project_context` replace customer AI context. Use `get_amplitude_context` to read your current org, projects, and context. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `action` | string ("set_org_context" | "set_project_context") | Yes | Discriminator: determines which set of parameters applies (set_org_context | set_project_context) | | `context` | string | Yes | New org AI context. | | `projectId` | number | No | Project ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | array | Yes | Array of content blocks returned by the tool | ### Manage amp entities **Slug:** `AMPLITUDE_MCP_MANAGE_AMP_ENTITIES` Create a shared (team) space, rename a space or change its members, or move charts, dashboards, notebooks, or cohorts into a shared space. Opens a confirmation card the user approves. Selected by `route`. ROUTES: - `create_space`: create a new shared space. Opens a compact form prefilled with the proposed name and members (`spaceName`, `members`). - `manage_space`: update an existing shared space's name, description, or members. Requires `spaceId`. - `move_to_space`: move charts, dashboards, notebooks, or cohorts into an existing shared space. Renders a destination picker over the entities you pass. - `search_members`, `validate_confirmation`, and `commit`: reserved for the confirmation card. Do not call them yourself. SPACE MANAGEMENT: - This is the only tool for creating, updating, or moving content into shared spaces. - If the needed destination does not exist, use `create_space` first. Do not create a destination inside `move_to_space`. INSTRUCTIONS: - For `move_to_space`, prefer `objects` and pass each entity's id plus the display name already established in the conversation or source tool output. This is especially important for unnamed chart edits: preserve the useful name you gave the chart instead of showing "Untitled chart". Do not use one title for multiple objects. - Resolve entity ids with `search_amp_entities`, or pass chart edit ids straight from `query_amplitude_data`. `objectIds` and `objectId` remain compatibility fallbacks when no display name is available. - `objectType` is optional for charts (saved vs unsaved is detected from the id) and required for dashboards, notebooks, and cohorts. - Set `title` to a short line explaining why the app opened, in the user's own words. - Nothing is written when a launch route returns. The user confirms in the app, which applies the change and reports back. DO NOT USE FOR: - Archiving flags or cohorts: no archive route exists yet. - Sharing individual charts or dashboards, or org invites: use `share_amp_entities`. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `query` | string | No | | | `route` | string ("create_space" | "manage_space" | "move_to_space" | "search_members" | "validate_confirmation" | "commit") | Yes | Discriminator: determines which set of parameters applies (create_space | manage_space | move_to_space | search_members | validate_confirmation | commit) | | `title` | string | No | Short heading explaining why the app opened, in the user's words. | | `members` | array | No | Org teammate login emails to preselect. The user can change them before confirming. | | `objects` | array | No | Preferred move input. Pair every entity id with its established display name so the confirmation stays recognizable. | | `spaceId` | string | No | Existing shared space to update. | | `newSpace` | object | No | Space details submitted by the create_space app route. | | `objectId` | string | No | Singular alias for objectIds. | | `objectIds` | array | No | Entity ids to act on. Saved entity ids, or chart edit ids from query_amplitude_data. | | `spaceName` | string | No | Suggested space name to prefill in the app. | | `objectType` | string ("CHART" | "DASHBOARD" | "NOTEBOOK" | "COHORT") | No | CHART, DASHBOARD, NOTEBOOK, or COHORT (uppercase). Optional for charts; required for the others. | | `selectedIds` | array | No | Entity ids the user left selected. | | `spaceUpdate` | object | No | Update the token-bound shared space. | | `targetSpaceId` | string | No | Existing space to move the selection into. | | `spaceDescription` | string | No | Suggested space description to prefill in the app. | | `confirmationToken` | string | No | | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | array | Yes | Array of content blocks returned by the tool | ### Manage amp events **Slug:** `AMPLITUDE_MCP_MANAGE_AMP_EVENTS` Write to a project's tracking-plan events — raw ingested events, custom events, and labeled (autotrack) events — in one tool selected by `action` + `kind`. Reading events lives in `get_amp_taxonomy`. KINDS: - `event` (default): raw ingested / planned event types in the tracking plan (Purchase, Page Viewed, …). Identified by `eventTypes`. - `custom`: virtual events composed of one or more raw source events with optional filters (`isAutotrack=false`). Identified by `customEventNames` / `customEventIds`. - `labeled`: autotrack / labeled events (`isAutotrack=true`). Same identifiers as custom. Update and delete — MCP cannot create labeled events. ACTION + KIND MATRIX (key params per combo): - create + event → `events: [{ name, isUnexpected, … }]` (isUnexpected: true adds an already-ingested unexpected event to the plan; false creates a brand-new planned event) - create + custom → `name` + `definition` (raw source events) - update + event → maps keyed by exact raw event `name` (`descriptions`, `newNames`, `categories`, `sources`, `tags`, `visibility`, `owners`, …) - update + custom|labeled → maps keyed by id / display name / ce: (`descriptions`, `newNames`, `categories`, `isOfficial`, `eventDefinitions`) - delete + event → `eventTypes`; mark as deleted (ingested) / removed (planned); two-step with `confirmed` - delete + custom|labeled → `customEventNames` / `customEventIds`; permanently removed (same as UI); two-step with `confirmed` - restore + event only → `eventTypes` (custom/labeled cannot be restored) COMMON MISTAKES (seen in production — avoid these): - Using `eventTypes` with kind custom/labeled, or `customEventNames` with kind event. Raw events → `eventTypes`; custom/labeled → `customEventNames`/`customEventIds`. - Sending `kind: "all"`. It is no longer a valid kind here — it only ever meant "custom and labeled together" on a read. Use `get_amp_taxonomy` (`action: events`) to read both, or pick `custom` or `labeled` for a write. - Omitting `action`. It is required now; it used to default to `get`, which no longer exists on this tool. - Putting `ce:` values in a custom event `definition` — source events must be raw event types; custom events cannot nest, and labeled events as sources are not supported yet. - create + event failing with "name already exists": the event was likely already ingested (unexpected) — retry with `isUnexpected: true` to add it to the plan instead. - Setting `description`/`category`/`isOfficial` on an event with `isUnexpected: true` — add to plan first, then update. - update + event on events not yet in the tracking plan — only planned/live events can be updated; add unexpected events to the plan first. - Creating a custom event whose definition duplicates an existing one — the API rejects duplicates and returns the existing event; reuse it instead. HOW TO FIND THE EVENTS YOU ARE ABOUT TO CHANGE: 1. Discover names with `search` (`entityTypes: ["EVENT"]` or `["CUSTOM_EVENT"]`). That is the primary path. 2. Hydrate them with `get_amp_taxonomy` (`action: events`) before writing — it returns status, category, activity, visibility, and ingestion timestamps, and confirms the exact name to key update maps by. DELETE / RESTORE: - For kind:event, delete is a two-step confirmation gate for every target — mark as deleted and remove alike. Never skip confirmation. - Marking as deleted stops ingestion immediately on main; on any other tracking-plan branch, ingest is unchanged until merge. Removing a planned event does not stop ingestion (the event was never ingested). - Restore: on main, ingestion resumes immediately; on any other branch, the restore is staged until merge. Only events that were marked as deleted can be restored; removed planned events must be recreated. - Custom/labeled delete is permanent and does not use this branch-ingest rule. TYPICAL FLOWS: - Add raw events on a branch: manage_amp_taxonomy create_branch (if main protected) → create with kind event + branchName → update metadata as needed. - Build a custom event: get_amp_taxonomy for the raw source events → create with kind custom + definition (source events). - Delete raw events (not custom/labeled): delete with kind event (confirmation_required first), then confirmed: true after the user acknowledges the buckets and branch. Ingested events are marked as deleted (restorable); planned events are removed (not restorable). - Permanently remove a custom/labeled event: delete with kind custom|labeled + customEventNames/Ids (confirmation_required first), then confirmed: true. Cannot be restored. - Restore a deleted raw (not custom/labeled) event: get_amp_taxonomy with `action: events` + `includeDeleted: true` to find it, then restore with its exact `eventTypes`. PROJECT ID: - Pass numeric `projectId`. Get it from `get_amplitude_context` if needed. - If omitted and the user has exactly one accessible project, that project is used automatically. DO NOT USE FOR: - Reading events → `get_amp_taxonomy` (`action: events`) - Fuzzy discovery → `search` - Properties → `manage_amp_properties` (writes) / `get_amp_taxonomy` (reads) - Branch governance → `manage_amp_taxonomy` (or legacy branch tools) #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `kind` | string ("event" | "custom" | "labeled") | No | event = raw tracking-plan events (default). custom / labeled = custom-or-labeled surface. | | `name` | string | No | create kind=custom: display name for the new custom event. | | `tags` | string | No | update kind=event: tags to add. | | `action` | string ("create" | "update" | "delete" | "restore") | Yes | Event write operation. Required — reads live in get_amp_taxonomy. | | `events` | array | No | create kind=event: array of { name, isUnexpected?, description?, category?, isOfficial? }. `name` is the exact ingested event name (same as get_events `name`). | | `owners` | object | No | update kind=event: name -> owner login ID (typically the user email). Same identifier as get_amp_taxonomy `owner`; values are trimmed and lowercased. Assigns the tracking-plan owner; does not clear an existing owner. Not supported for custom/labeled events or properties. | | `sources` | object | No | update kind=event: source IDs to add (use get_tracking_plan_sources). | | `branchId` | string | No | create/update/delete/restore kind=event: optional branch id (mutually exclusive with branchName). | | `category` | string | No | create kind=custom: optional category. | | `newNames` | object | No | update: rename map. | | `confirmed` | boolean | No | delete kind=event|custom|labeled: set true only after the user acknowledges the prior confirmation_required response. Required for every delete — not only ingested events marked as deleted. | | `projectId` | string | No | Numeric Amplitude project ID (e.g. "123456"). Optional only when the user has exactly one accessible project. | | `rationale` | string | No | Brief explanation of why you are calling this tool and what you expect to learn from the result. | | `branchName` | string | No | create/update/delete/restore kind=event: optional branch name (mutually exclusive with branchId). | | `categories` | string | No | update: category map. | | `definition` | array | No | create kind=custom: source events [{ event_type, filters? }, …]. At least one required. | | `eventTypes` | array | No | delete / restore kind=event: exact ingested event names to act on. | | `isOfficial` | string | No | create kind=custom: boolean official flag. update: map of exact raw event name or custom id_or_name → boolean. | | `removeTags` | string | No | update kind=event: tags to remove. | | `visibility` | object | No | update kind=event: name -> { hiddenFromDropdowns?, hiddenFromPersonaResults?, hiddenFromPathfinderAndJourneys?, hiddenFromEventStreams? }. Omitted flags remain unchanged. get_amp_taxonomy returns read-shaped `hiddenFrom` surface lists; use these flags to change visibility. | | `description` | string | No | create kind=custom: optional description. | | `descriptions` | object | No | update: descriptions map (raw event name or custom id_or_name). | | `removeSources` | object | No | update kind=event: source IDs to remove. | | `customEventIds` | array | No | update / delete kind=custom|labeled: custom/labeled event ids. | | `isActiveAction` | object | No | update kind=event: name -> boolean active/inactive state. Same field name as `isActiveAction` on get_amp_taxonomy output. | | `customEventNames` | array | No | update / delete kind=custom|labeled: exact display names (include punctuation/brackets as shown in UI). | | `eventDefinitions` | object | No | update kind=custom|labeled: id_or_name → SourceEvent[] definition replacements. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | array | Yes | Array of content blocks returned by the tool | ### Manage amp taxonomy **Slug:** `AMPLITUDE_MCP_MANAGE_AMP_TAXONOMY` Read Data workspace governance settings and manage tracking-plan branches for a project. One tool selected by `action` (default `get`). TYPICAL FLOW (most common production path): 1. `get` first — learn `mainProtected`, naming conventions, approval workflow, and environments before changing the plan. 2. If `mainProtected` is true (or the user wants an isolated change), `create_branch` — do not mutate main. Optionally `get` again / check `branches` first so you do not recreate an existing name. 3. Apply tracking-plan edits with the taxonomy mutation tools (`create_events`, `create_properties`, `update_event`, …) and pass `branchName` / `branchId` to target that branch — those tools are separate from this one. 4. Finish with `merge_branch` (two-step `confirmed`) when the user wants changes on main, or `delete_branch` (two-step `confirmed`) to abandon. Many sessions stop after step 3 with work left on the feature branch — that is normal. 5. Less common: `refresh_branch` (pull main into the feature branch; two-step), `review_branch` (approve/unapprove when approvals are required), `update_branch` (description only). ACTIONS: - `get` (default): workspace settings + environments + branches in one response. Includes `mainProtected` (true when approvalWF is "Required" — changes must go on a feature branch, not main) and `workflowHint`. - `create_branch`: create a branch off main. Requires `name`. - `update_branch`: update a branch description (not name). Requires `branchName` or `branchId` + `description`. - `delete_branch`: delete a non-main branch. Two-step: call once, then again with `confirmed: true` after the user acknowledges. - `merge_branch`: merge a feature branch into main. Two-step with `confirmed`. If approvals are required and missing, reports status instead of merging. - `refresh_branch`: pull latest main into a feature branch. Two-step with `confirmed`; conflicts overwrite the feature-branch version. - `review_branch`: approve or unapprove a branch for merge. Pass `reviewDecision` ("approve" | "unapprove"). Prefer after the branch has pending changes — empty branches cannot be approved. PROJECT ID: - Pass numeric `projectId` (e.g. "123456"). Get it from `get_amplitude_context` if you do not already have one. - If omitted and the user has exactly one accessible project, that project is used automatically. - Do not invent project ids. Do not use project names. DO NOT USE FOR: - General org/user/project discovery → `get_amplitude_context` - Creating or updating events/properties → the taxonomy mutation tools (`create_events`, `create_properties`, …) with `branchName` when on a feature branch - Listing events/properties → `get_events` / `get_properties` #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | No | create_branch: unique name for the new branch. | | `action` | string ("get" | "create_branch" | "update_branch" | "delete_branch" | "merge_branch" | "refresh_branch" | "review_branch") | No | Workspace/branch operation. Defaults to get. | | `branchId` | string | No | Branch ID for update/delete/merge/refresh/review. Use either branchId or branchName. | | `confirmed` | boolean | No | delete_branch / merge_branch / refresh_branch: set true only after the user explicitly confirms. | | `projectId` | string | No | Numeric Amplitude project ID (e.g. "123456"). Get it from get_amplitude_context. Optional only when the user has exactly one accessible project. | | `rationale` | string | No | Brief explanation of why you are calling this tool and what you expect to learn from the result. | | `branchName` | string | No | Branch name for update/delete/merge/refresh/review. Use either branchId or branchName. | | `description` | string | No | create_branch: optional branch description. update_branch: new description (required for that action). | | `reviewDecision` | string ("approve" | "unapprove") | No | review_branch: whether to approve or withdraw approval. Defaults to approve. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | array | Yes | Array of content blocks returned by the tool | ### Query amplitude data **Slug:** `AMPLITUDE_MCP_QUERY_AMPLITUDE_DATA` Run analytics queries to answer data questions about users, events, funnels, and retention — and to create or modify charts via the typed `chart` parameter. PREFERRED: pass the typed `chart` parameter (segmentation | funnel | retention | sessions | data_table). It is a small, UI-shaped model (events, where, group_by, measured_as, segments, date_range) that is deterministically compiled server-side into a validated chart definition — compile errors come back with a fix-oriented hint, so you never need to hand-build raw definition JSON. FALLBACK: pass a raw `definition` only for chart types the typed model does not cover (composition, revenueLtv) or advanced params the typed model has no field for. Raw definitions are validated inline; on failure the response includes chartTypeSchema with the parameter schema, valid enums, a working example, and coercion rules. Provide exactly one of `chart` or `definition`. # WHEN TO USE - Answer questions like: - "How many active users did we have last week?" - "Show me a funnel from sign up to purchase" - "What is the retention rate for new users?" - "Create a chart…" / "Modify chart X to…" - Any question asking for metrics, counts, trends, funnels, or retention analysis # DO NOT USE FOR: - Finding existing charts/dashboards → use 'search' or 'get_amplitude_charts' instead - Project settings (timezone, currency) → use 'get_amplitude_context' with projectId instead # STRATEGIES 1. Discover event/property names with 'search' (or search_amp_data_taxonomy) — never guess them. 2. Create: build the typed `chart` (events + date_range required; add where/group_by/segments as asked) → call this tool. 3. Modify / fork a saved chart: `search` to find the chart id → `get_amplitude_charts include='typed'` → edit the returned `chart` → call this tool with that `chart` AND `chartId` set to the saved chart id (links the edit to the parent; parent params fill gaps the typed model omits — including `date_range`, which may be left out to keep the parent's window). 4. Call query_amplitude_data — compile and validation errors are actionable; fix the named field and retry. 5. To show the result visually, call 'render_amplitude_chart' with the returned chartEditId. # GENERAL GUIDELINES - Don't guess event or property names — discover them first, and use the exact name and scope returned. - ALWAYS set a descriptive "name" (becomes the chart title) and an explicit date_range (except when modifying with chartId and the parent's window should be kept). - Relative date_range windows support an Offset suffix for day-over-day / historical comparisons: "Last 0 Days Offset 1" (yesterday), "Last 0 Days Offset 7" (same day last week), "Last 7 Days Offset 7" (the prior week). - On errors, follow the hint in the message; the compiler names the offending field. Chart types supported by raw `definition`: eventsSegmentation, funnels, metricExplorer, retention, revenueLtv, sessions, stickiness RESPONSE FORMAT: Returns {isCsvResponse: bool, csvResponse or jsonResponse, definition}. Only ONE response type present. When jsonResponse is present, "seriesNames" (string[]) gives the human-readable name of each timeSeries entry in order — use it instead of the numeric seriesLabels for ungrouped segments. Check the isCsvResponse flag to determine which response format to parse CRITICAL — NON-ADDITIVE METRICS (uniques, pct_dau): - These metrics cannot be summed across intervals. The chart UI plots per-interval values, not a running total. - Additive metrics (totals, sums) CAN be summed across intervals. How to read the JSON response, by metric type: 1. COUNT metrics ("uniques"): - Use "overallSeries" — it is the TRUE deduped unique count across the full date range. - Do NOT sum "timeSeries" values — that overstates the count due to user overlap across intervals. 2. RATIO metrics ("pct_dau" only): - Use "timeSeriesAverage" (mean of per-interval values) — this matches what the chart UI displays. For "current" reporting, also consider the most recent N intervals from "timeSeries". - Do NOT use "overallSeries" for pct_dau over multi-interval ranges. For pct_dau, "overallSeries" is a long-range aggregate (deduped numerator over the full range / deduped denominator over the full range). Over many intervals the denominator dedupes a much larger pool than the numerator, which compresses the ratio — typically reporting roughly half of the per-interval values the chart shows. This is mathematically valid as a long-range aggregate but is NOT what users see in the chart. - Do NOT sum "timeSeries" values — ratios cannot be summed. CSV Response Structure (when isCsvResponse is true): - Header rows: The top rows contain metadata including chart name, description, events, formulas, and other chart configuration details - Data header row: A single row containing column labels for the data points below (typically includes dates or time periods) - Data rows: Each row contains: * Label columns: First few columns contain row labels identifying the data series * Value columns: Numerical data organized under the corresponding date/time columns from the data header row - Parse by: Skip metadata rows, identify the data header row, then extract labels from first columns and values from remaining columns - Cells in the CSV response are delimited by commas and may be prepended with a character Example below measures uniques of custom event "Valuable Tweaking" over 3 days (2025-08-23, 2025-08-24, 2025-08-25) for all users. The data points are 614, 1769, and 4132 for the 3 days respectively. IMPORTANT: The overall unique users is 5642 (NOT 614+1769+4132=6515), because users overlap across days. data: " Example chart name" " Formula"," UNIQUES(A)" " A:"," [Custom] 'Valuable Tweaking'" " Segment"," 2025-08-23"," 2025-08-24"," 2025-08-25" " All Non-Amplitude Users","614","1769","4132" definition: { "app": "APP_ID", "params": { "countGroup": "User", "end": 1756166399, "events": [ { "event_type": "ce:'Valuable Tweaking'", "filters": [], "group_by": [] } ], "groupBy": [], "interval": 1, "metric": "uniques", "segments": [], "start": 1755907200, }, "type": "eventsSegmentation", } JSON Response Structure (when isCsvResponse is false): - Parse using the following structure: - timeSeries: Array of arrays, each containing data points for a given time period with a "value" property - overallSeries: Array of arrays, each containing the overall data point across the entire range under the "value" property. IMPORTANT — interpretation depends on the metric: * For "uniques" (count): this is the TRUE deduped unique count over the full date range. Use this. * For "pct_dau" (ratio): this is a long-range aggregate ratio (deduped numerator over range / deduped denominator over range). It does NOT match the per-interval values the chart UI plots and is typically much smaller. Do NOT report it as the headline number — use "timeSeriesAverage" instead. - timeSeriesAverage: Present only for "pct_dau". Array of arrays, one per series, each containing a single {value} that is the mean of "timeSeries" values for that series. Use this as the headline ratio when the chart spans multiple intervals — it matches what users see in the chart UI. - seriesMetadata: Array of objects containing metadata for each series - xValuesForTimeSeries: Array of strings representing the x-axis values (dates) for the time series - Use the dataset definition to be able to parse referenced events, properties, and segments. Example below is a JSON response is for the same query as the CSV example above. { "timeSeries": [[{"value": 614}, {"value": 1769}, {"value": 4132}]], "overallSeries": [[{"value": 5642}]], "seriesMetadata": [{"segmentIndex": 0, "formulaIndex": 0, "formula": "UNIQUES(A)"}], "xValuesForTimeSeries": ["2025-08-23T00:00:00", "2025-08-24T00:00:00", "2025-08-25T00:00:00"] } Note: 614+1769+4132=6515, but overallSeries shows 5642. This is because unique users overlap across days. For "uniques", always use overallSeries for the total. Example below is a "pct_dau" query over 3 weeks (a ratio metric): { "timeSeries": [[{"value": 0.1402}, {"value": 0.1421}, {"value": 0.1444}]], "overallSeries": [[{"value": 0.0712}]], "timeSeriesAverage": [[{"value": 0.1422}]], "seriesMetadata": [{"segmentIndex": 0, "formulaIndex": 0, "formula": "PCT_DAU(A)"}], "xValuesForTimeSeries": ["2026-04-06T00:00:00", "2026-04-13T00:00:00", "2026-04-20T00:00:00"] } Note: the chart UI shows ~14% per week. timeSeriesAverage (14.22%) matches that. overallSeries (7.12%) is the deduped 3-week aggregate ratio and would HALVE the reported value if used as the headline — never report it as "the number" for "pct_dau". Always use timeSeriesAverage for "pct_dau". Event Segmentation with Insights (anomaly detection / confidence intervals): - When params.insights.isOn is true, Event Segmentation charts queried via query_charts or query_dataset return BOTH chartConfig (Highcharts) AND jsonResponse with joinable band data. - jsonResponse.seriesIntervals maps stringified seriesMetadata keys to { low, high, yhat } arrays (parallel to xValuesForTimeSeries). Use seriesMetadata + xValuesForTimeSeries to join bands to series. - Metric Explorer charts with Insights return seriesIntervals inside each data[] entry instead. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `chart` | string | No | PREFERRED. Typed, UI-shaped chart parameters, discriminated on `kind` (segmentation | funnel | retention | sessions | data_table). Compiled server-side into a validated definition — no raw definition JSON needed. Provide exactly one of `chart` or `definition`. | | `chartId` | string | No | Optional parent chart ID for modify/fork. When provided, the parent chart's params (segments, filters, countGroup, groupBy, etc.) are used as defaults — only params you explicitly provide will override. Typical modify flow: get_amplitude_charts include='typed' → edit `chart` → query_amplitude_data({ chart, chartId }). | | `projectId` | string | Yes | Project ID to query data from | | `rationale` | string | No | Brief explanation of why you are calling this tool and what you expect to learn from the result. | | `definition` | object | No | FALLBACK — prefer the typed `chart` parameter. Raw chart definition for types/params the typed model does not cover (e.g. composition, revenueLtv). Validated inline — on failure the response includes chartTypeSchema (params, enums, example, coercion rules) so you can fix and retry. Use canonical chart types only: - "eventsSegmentation" - "funnels" - "retention" - "sessions" - "revenueLtv" - "dataTableV2" Do not use aliases like: - "segmentation" - "event_segmentation" - "events" - "funnel" TIME RANGE — three accepted shapes, mutually exclusive with each other: - "range" preset (e.g. "Last 30 Days", "Last 12 Weeks", "This Month", "Yesterday") - "start" + "end" for a bounded custom range - "start" alone for an open-ended "since " range (renders as Amplitude's "Since" view) - Timestamps may be Unix seconds, ISO 8601 strings, or relative strings like "now-7d" / "now" - Do not combine "range" with "start"/"end". Do not provide "end" without "start" - Do not use invalid placeholders like "Custom", "Daily", or "All Time" VISUALIZATION TYPE (top-level "vis", optional): - Set "vis" when the user explicitly asks for a specific chart shape (e.g. "as a bar chart", "show as a pie", "stacked bar by country"). Otherwise omit and the system picks a sensible default. - Valid values for eventsSegmentation: "line" (default trend), "area", "bar" (vertical), "column" (horizontal), "stackedbar", "pie", "kpi" (single number). - Valid values for funnels: "line", "bar". - Valid values for sessions: "line", "bar", "totalSessions", "average". - "vis" goes at the TOP LEVEL of the definition, NOT inside "params". COMMON GUARDRAILS: - "dataTableV2" requires "params.table" - "sessions" requires "params.sessions" - "customerJourney" has a maximum of 5 steps when using PATH_TREE or SINGLE_PATH visualization - event lists should use canonical event objects with "event_type", "filters", and "group_by" - include a descriptive top-level "name" whenever possible MINIMAL EXAMPLES: - eventsSegmentation (default line): {"type":"eventsSegmentation","app":"123","name":"Active Users Last 30 Days","params":{"range":"Last 30 Days","events":[{"event_type":"_active","filters":[],"group_by":[]}],"metric":"uniques","countGroup":"User","groupBy":[],"interval":1,"segments":[{"conditions":[]}]}} - eventsSegmentation as bar chart (user said "show as a bar chart"): {"type":"eventsSegmentation","app":"123","name":"Purchases by Country","vis":"bar","params":{"range":"Last 30 Days","events":[{"event_type":"Purchase","filters":[],"group_by":[{"type":"event","value":"country"}]}],"metric":"totals","countGroup":"User","groupBy":[],"interval":1,"segments":[{"conditions":[]}]}} - funnels: {"type":"funnels","app":"123","name":"Signup Funnel","params":{"range":"Last 30 Days","events":[{"event_type":"View Signup","filters":[],"group_by":[]},{"event_type":"Complete Signup","filters":[],"group_by":[]}],"countGroup":"User","segments":[{"conditions":[]}]}} - revenueLtv (cumulative revenue from users NEW in the selected date range — empty results usually mean no new users were acquired in the period, not broken revenue instrumentation): {"type":"revenueLtv","app":"123","name":"Revenue LTV - Total Revenue","vis":"line","params":{"range":"Last 90 Days","metric":"2","event":{"event_type":"_any_revenue_event","filters":[],"group_by":[]},"revenueProperty":"$revenue","groupBy":[],"countGroup":"User","interval":1,"segments":[{"conditions":[]}]}} | | `groupByLimit` | number | No | Maximum number of group by values to return (1-1000, defaults to 10) | | `timeSeriesLimit` | integer | No | Maximum number of group-by values that include per-interval time-series rows in the CSV response. All group-by values always include their aggregate "Total" row. Groups beyond this limit only return their Total row, which dramatically reduces response size for charts with many group-by values over long date ranges. Set to 0 for totals-only. Defaults to 3. | | `includeAdditionalInfo` | array | No | Additional render-only information to include. Omit for compact analytics data. | | `excludeIncompleteDatapoints` | boolean | No | Optional flag to exclude incomplete data points from results. When true, the current time interval will be excluded from the results to avoid incomplete data points. Defaults to false. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | array | Yes | Array of content blocks returned by the tool | ### Rename chart **Slug:** `AMPLITUDE_MCP_RENAME_CHART` Rename a chart that has already been saved WHEN TO USE: - A chart was saved (e.g. via save_chart_edits) and the user wants a different name on that same chart IMPORTANT: - Updates the existing chart in place and records a version-history entry; it does not create a copy - Requires edit access to the chart and write access to its project - To save a new chart from an ad-hoc edit, use save_chart_edits instead #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | Yes | New name for the chart | | `chartId` | string | Yes | ID of the saved chart to rename (e.g. from /chart/abc123) | | `rationale` | string | No | Brief explanation of why you are calling this tool and what you expect to learn from the result. | | `description` | string | No | New description. Omit to leave the existing one untouched | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | array | Yes | Array of content blocks returned by the tool | ### Render amplitude chart **Slug:** `AMPLITUDE_MCP_RENDER_AMPLITUDE_CHART` Render an interactive Amplitude chart UI for a saved chart or a chart edit by ID. This is the way to SHOW a chart to the user — it spins up the chart widget; the widget fetches the chart's data itself and draws it. ## SUPPORTED CHART TYPES eventsSegmentation, funnels, retention, metricExplorer. - dataTableV2 CANNOT be rendered in the chart widget. Present query results directly instead. ## WHEN TO USE - The user wants to SEE a chart and you already have a `chartId` (saved chart) or `chartEditId` (ad-hoc chart edit). - Right after `query_dataset` returns a `chartEditId` for a non-empty result — pass that `chartEditId` here to render it. - Right after `search` / `get_from_url` resolves a saved `chartId` the user asked to see. ## WHEN NOT TO USE — DO NOT CALL WITHOUT AN ID - You do NOT have a `chartId` or `chartEditId` yet. Resolve one FIRST: - `query_dataset` (returns a `chartEditId` for an ad-hoc definition) - `search` with `entityTypes: ["CHART"]` (finds a saved `chartId`) - `get_from_url` (parses an id out of an Amplitude chart URL) - The query you ran returned empty / all-zero data — tell the user, do NOT render an empty chart. ## INSTRUCTIONS - Provide exactly one of `chartId` (saved chart) or `chartEditId` (chart edit). If you have both, prefer `chartEditId`. - When rendering a chart edit from `query_dataset`, pass its returned `title` so the widget displays the requested chart title. - This tool does NOT return chart data to you — it only renders the widget. To reason about the numbers, call `get_amplitude_charts` (include='data') / `query_dataset` for the data. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `title` | string | No | Chart title to display. Pass the title returned by query_dataset when rendering a chart edit. | | `chartId` | string | No | Saved chart ID to render (e.g. from search or get_from_url). | | `rationale` | string | No | Brief explanation of why you are calling this tool and what you expect to learn from the result. | | `chartEditId` | string | No | Chart edit ID to render. Returned by query_dataset, or parsed from links ending in /chart/new/ or /chart//edit/. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `appId` | string | No | | | `error` | string | No | | | `title` | string | No | | | `chartId` | string | No | | | `success` | boolean | Yes | | | `chartEditId` | string | No | | | `canSaveChart` | boolean | No | | | `shouldRenderUI` | boolean | Yes | | ### Render amp session replay **Slug:** `AMPLITUDE_MCP_RENDER_AMP_SESSION_REPLAY` Render an interactive session replay player UI for one or more session replays. This is the ONLY way to actually show a session replay to the user — text descriptions are not a substitute. WHEN TO USE (call this tool whenever the user wants to SEE a replay): - Any user request with a viewing verb: "show me", "render", "play", "watch", "let me see", "pull up", "open", "display", "view", "I want to see", "can I see" + "session replay(s)" / "session(s)" / "recording(s)" / "the replay" / "those sessions". - Any time the user asks to look at, observe, or visually inspect session activity, even without an explicit verb (e.g. "the session for jane@acme.com", "that recording", "those replays from yesterday"). - Immediately after a session replay search returns replay IDs in response to such a request — chain directly into render_amp_session_replay with the returned IDs. Do NOT stop at listing IDs in text when the user asked to see the replays. - If the user asks to see replays but you don't have IDs yet, FIRST find them with the session replay search tool available to you (`get_amp_session_replay_info`, else `get_session_replays` / `list_session_replays`), THEN call this tool with the results — in the same turn. - Call ONCE with a list of IDs to render multiple replays the user can switch between — do NOT call this tool separately per replay. WHEN NOT TO USE: - The user is asking for a count, summary, or analysis of replay events without wanting to watch them ("how many replays…", "what did the user do in…", "summarize…"). Use the timeline / events tools instead. INSTRUCTIONS: - Provide projectId and one or more sessionReplayIds. - sessionReplayId format is "/" (e.g. "0c650142-4a68-4f82-ad6a-4f154fee5265/1773235450374") — use the ids returned from the search/list tools verbatim. - This tool is an MCP App: it ships the player manifest through structuredContent/_meta, so hosts treat it as a UI render rather than a data read. - Maximum 20 IDs per call. The UI hydrates the rrweb player on demand for each replay. - Set `title` to a short, human-readable summary of WHY you're rendering these replays based on the user's request (3–8 words). This is shown as the heading above the player. Examples: "Recent web sessions for nvidia.com", "Sessions where users hit checkout errors", "Top 3 longest sessions yesterday". Do NOT echo IDs or device info — that lives in the player itself. If the user gave no specific framing, omit `title`. EXAMPLES: - Single replay: { "projectId": "678910", "sessionReplayIds": ["0c650142-4a68-4f82-ad6a-4f154fee5265/1773235450374"], "title": "Most recent session for jane@acme.com" } - Multiple replays: { "projectId": "678910", "sessionReplayIds": ["abc/111", "def/222"], "title": "Sessions where users abandoned checkout" } - No framing context: { "projectId": "678910", "sessionReplayIds": ["abc/111"] } NOTES: - The UI plays the replay inline (rrweb-based) with a tree-style event list — the model does NOT need to summarize that data in text. - This tool is UI-only. Do not rely on its response for reasoning about the replays. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `title` | string | No | Short, human-readable heading for the player UI describing WHY these replays are being shown (3–8 words). Examples: "Recent web sessions for nvidia.com", "Sessions where users hit checkout errors". Omit if there is no specific framing. | | `projectId` | string | Yes | The Amplitude project ID (appId) as a string (e.g. "12345", "678910") the replays belong to | | `rationale` | string | No | Brief explanation of why you are calling this tool and what you expect to learn from the result. | | `sessionReplayIds` | array | Yes | List of session replay IDs in the format "/". Returned from the session replay search tools. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `error` | string | No | | | `title` | string | No | | | `success` | boolean | Yes | | | `sessions` | array | No | | | `projectId` | string | No | | | `projectName` | string | No | | | `shouldRenderUI` | boolean | Yes | | ### Restore event properties **Slug:** `AMPLITUDE_MCP_RESTORE_EVENT_PROPERTIES` Restore event properties that were previously marked as deleted in a project. Each requested property is routed by whether eventType is provided: - eventType provided → per-event restore: restore the property on that specific event only. - eventType omitted → plan-wide restore: restore the property across the tracking plan. A single call may mix both — each entry is routed independently. Amplitude-owned properties cannot be restored (they cannot be deleted in the first place). # Note On the main branch, ingestion for a restored event property resumes immediately. On any other branch, the restore is staged on that branch and only takes effect on ingestion once the branch is merged into main. Always warn the user about this. # Branch targeting Unless specified, the default branch is used. To apply changes to a non-default branch, pass either branchId or branchName. If the user references a branch by name (e.g. "my-edits-branch"), use branchName. Pass only one. # Permissions This tool requires the "Update Tracking Plan" permission and may fail with a 403. Don't pre-warn the user; if it fails, surface the error and note that an admin may need to grant access. # Caveats Properties that were removed (planned but never ingested at the time of deletion) cannot be restored — they have to be recreated via create_properties. Only properties that were marked as deleted can be restored. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `branchId` | string | No | Optional branch ID to target a non-default branch. If omitted, the project's default branch is used. Mutually exclusive with branchName. | | `projectId` | string | Yes | Project ID to restore event properties in. If the user has not specified a project, prompt the user to decide. Dont decide for them. | | `rationale` | string | No | Brief explanation of why you are calling this tool and what you expect to learn from the result. | | `branchName` | string | No | Optional branch name to target a non-default branch (e.g. "my-edits-branch"). If omitted, the project's default branch is used. Mutually exclusive with branchId. | | `properties` | array | Yes | Array of event properties to restore | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | array | Yes | Array of content blocks returned by the tool | ### Restore user properties **Slug:** `AMPLITUDE_MCP_RESTORE_USER_PROPERTIES` Restore user properties that were previously marked as deleted in a project. # Note On the main branch, ingestion for a restored user property resumes immediately — incoming data with this property will be accepted again as soon as the restore succeeds. On any other branch, the restore is staged on that branch and only takes effect on ingestion once the branch is merged into main. Always warn the user about this. This tool only restores customer-defined user properties. Amplitude-owned user properties cannot be restored and are always skipped — tell the user if any were requested. When a name exists as both customer and Amplitude, only the customer property is targeted. # Branch targeting Unless specified, the default branch is used. To apply changes to a non-default branch, pass either branchId or branchName. If the user references a branch by name (e.g. "my-edits-branch"), use branchName. Pass only one. # Permissions This tool requires the "Update Tracking Plan" permission and may fail with a 403. Don't pre-warn the user; if it fails, surface the error and note that an admin may need to grant access. # Caveats Properties that were removed (planned but never ingested at the time of deletion) cannot be restored — they have to be recreated via create_properties. Only properties that were marked as deleted can be restored. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `branchId` | string | No | Optional branch ID to target a non-default branch. If omitted, the project's default branch is used. Mutually exclusive with branchName. | | `projectId` | string | Yes | Project ID to restore user properties in. If the user has not specified a project, prompt the user to decide. Dont decide for them. | | `rationale` | string | No | Brief explanation of why you are calling this tool and what you expect to learn from the result. | | `branchName` | string | No | Optional branch name to target a non-default branch (e.g. "my-edits-branch"). If omitted, the project's default branch is used. Mutually exclusive with branchId. | | `propertyNames` | array | Yes | Array of user property names to restore | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | array | Yes | Array of content blocks returned by the tool | ### Save chart edits **Slug:** `AMPLITUDE_MCP_SAVE_CHART_EDITS` Promote chart edits to saved charts — Save as (new chartId) or Save in place (same chartId). WHEN TO USE: - You have a chartEditId from query_amplitude_data and need a permanent chartId - The user asked to update an existing chart and keep the same chartId / links MODES (per item in charts[]): - **Save as** (default): omit chartId → creates a new unpublished chart in personal space - **Save in place**: chartId + expectedLastModified → overwrites that chart (same chartId; updates all dashboards/notebooks referencing it) → ONLY when the user explicitly asked to update the existing chart — never infer from context → Requires a two-step confirm flow (probe, then confirm) — see workflow below WORKFLOW — save as new: 1. query_amplitude_data → chartEditId 2. save_chart_edits({ charts: [{ editId, name }] }) 3. Use returned chartId in dashboards/notebooks WORKFLOW — update existing chart (two-step — always confirm with the user): 1. get_amplitude_charts({ chartIds, include: "definition" }) → lastModified 2. query_amplitude_data({ chart, chartId }) → chartEditId 3. **Probe** (no confirm flags): save_chart_edits({ charts: [{ editId, name, chartId, expectedLastModified }] }) → returns overwriteImpact (chart name, URL, dashboards, published status) → present this to the user and ask whether to update in place or save as new 4. **Confirm** (only if user explicitly wants in-place): re-call with confirmOverwrite: true → if requiresSharedChartConfirmation, also add confirmSharedImpact: true after user reviews sharedChartImpact IMPORTANT: - Never set confirmOverwrite on the first in-place call — the probe response exists so you can double-check with the user - Default to save-as-new unless the user clearly wants the same chartId updated - Having chartId from a URL or prior query does NOT mean in-place save is allowed - Save-as-new charts default to unpublished in your personal space until a human publishes - To collaborate on save-as-new, pass destination {"kind":"space","spaceId":"..."} using a space id from the user or a shared-space URL. You must have permission to add to that space. To create a space or move already-saved charts, use manage_amp_entities - The response echoes where charts landed in savedTo (kind, spaceName, published, notified). Report that to the user rather than assuming the requested destination was used - In-place save requires edit access, matching edit provenance, and a fresh expectedLastModified (409 conflict if stale) - Prefer save in place when the user explicitly asks to update a chart others reference; use save as for new analyses #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `charts` | array | Yes | Chart edits to promote. Omit chartId on each item to save as new. For in-place update: probe with chartId + expectedLastModified (no confirm flags), show impact to the user, then re-call with confirmOverwrite. | | `rationale` | string | No | Brief explanation of why you are calling this tool and what you expect to learn from the result. | | `destination` | string | No | Where to save. Omit for the personal space (previous behavior). | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | array | Yes | Array of content blocks returned by the tool | ### Search amp data taxonomy **Slug:** `AMPLITUDE_MCP_SEARCH_AMP_DATA_TAXONOMY` Semantic search over a project's data taxonomy: discover events, properties, and property values by describing what you're looking for in natural language. Batches many searches into ONE call. INSTRUCTIONS: - Use get_amplitude_context FIRST to get the projectId. - Batch your entire discovery plan into a single call (one search per concept, up to 16) instead of calling this tool repeatedly. - Populate each search based on its kind: - "events": set 'description' to one event concept (e.g. "user completes a purchase"). - "properties": set 'descriptions' to 1-2 concise phrasings of the property (e.g. ["subscription plan", "pricing tier"]). - "property_values": set 'propertyName' to the EXACT property name (find it with a "properties" search first); set 'eventType' when it is an event property. - Per-search 'limit' is 1-50 hits (default 10). Raise it only for broad concepts where the default may miss the right entity; larger limits cost context. USING THE RESULTS: - Results come back in the same order as the input searches. A failed search returns an 'error' entry without failing the others. - Hits are semantically ranked; the top hit is not guaranteed to be correct. Use the returned names EXACTLY as spelled — never guess variants. - An 'ambiguity' block on a result means several hits scored similar confidence — surface those candidates and ask which the user means rather than silently picking one, whenever the choice is load-bearing for the answer. - Reason from whatever extra signal a hit carries instead of taking rank 1 on faith: 'query_volume' (how often the org actually queries it) is the strongest tiebreaker between similar names, 'last_seen' exposes stale or deprecated entities, and a property's 'scope' (event vs. user vs. group) decides where a filter belongs. - Report taxonomy quality problems back to the user — near-duplicate events for one concept, several casing variants of the same value, hits with no recent volume, or an 'ambiguity' block you had to guess past. Say which one you picked and why. These are fixable data issues, and staying silent means every later answer quietly inherits the same ambiguity. - 'detail' controls response verbosity — pick the cheapest level that answers the question: - "compact" (default): names, descriptions, ranking hints only — cheapest, right for most lookups. - "stats": adds usage/recency metrics per hit. 'volume' (+ *_30d/*_180d) = ingested event counts; 'query_volume' = how often the org uses it in charts/queries (the strongest tiebreaker between similar hits); 'first_seen'/'last_seen' = recency (an old last_seen means stale/deprecated — avoid building new analyses on it). - "full": nothing stripped (tags, category, importance scores, all stats) — most tokens, only when you need governance metadata. - Need just one or two stat fields? Stay on "compact" and name them in 'extraFields' (e.g. ["query_volume"]) — cheaper than "stats" or "full". - Use 'maxResponseChars' to hard-cap the payload when context is tight; results are truncated per search so every search stays represented. EXAMPLES: - Ground a funnel: {"projectId": "123456", "searches": [{"kind": "events", "description": "user signs up"}, {"kind": "events", "description": "user completes checkout"}]} - Find a property then its values: {"projectId": "123456", "searches": [{"kind": "properties", "descriptions": ["subscription plan"]}]} then {"projectId": "123456", "searches": [{"kind": "property_values", "propertyName": "plan_type", "eventType": "Subscription Started"}]} - Rank by usage: {"projectId": "123456", "searches": [{"kind": "events", "description": "purchase"}], "detail": "stats"} - Compact but keep one stat: {"projectId": "123456", "searches": [{"kind": "events", "description": "purchase"}], "extraFields": ["query_volume"]} - Tight context budget: {"projectId": "123456", "searches": [{"kind": "events", "description": "purchase"}], "maxResponseChars": 4000} NOTES: - Hits are already ranked by a hybrid of semantic and keyword search — a single ranking, not two lists to reconcile. - 'source' says which backend served the batch. 'langley' is the normal path. 'unisearch_fallback' means that backend was unreachable, so results are keyword-only and lower quality; the response carries a 'degradedReason', the fallback cannot serve 'property_values' searches, and it ignores 'detail' and 'extraFields' (always compact hits). Treat a fallback answer as provisional and say so when it materially affects your conclusion. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `detail` | string ("compact" | "stats" | "full") | No | Response verbosity. 'compact' (default): names, descriptions, and ranking hints only — right for most lookups. 'stats': adds usage/recency metrics per hit ('volume', 'query_volume', 'first_seen', 'last_seen' + *_30d/*_180d windows) — use when ranking similar candidates or checking freshness. 'full': nothing stripped (also tags, category, importance scores) — most tokens; only for governance metadata. | | `searches` | array | Yes | 1-16 searches, run in parallel in one call. Batch the whole discovery plan (all event concepts, properties, and value lookups) instead of calling this tool repeatedly. | | `projectId` | string | Yes | Amplitude project ID to search within (required). | | `rationale` | string | No | Brief explanation of why you are calling this tool and what you expect to learn from the result. | | `extraFields` | array | No | Keep only these normally-stripped hit fields while staying compact — cheaper than detail='stats'/'full' when you need one or two extras (e.g. ["query_volume"]). Ignored when detail='full'. | | `maxResponseChars` | integer | No | Hard cap on total response size in characters (0 = uncapped; server default ~90000). When the cap binds, hits are dropped per search so every search stays represented. Set it when your context budget is tight. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | array | Yes | Array of content blocks returned by the tool | ### Search amp entities **Slug:** `AMPLITUDE_MCP_SEARCH_AMP_ENTITIES` Search for dashboards, charts, notebooks, experiments, docs, and other content in Amplitude. INSTRUCTIONS: - Use this as your primary tool to discover and explore available analytics content before diving into specific analyses. - If you are not sure what to search for, use the default search query. - Do not specify appIds/projectIds in the input unless the user explicitly asks to search within a specific app/project. - To search Amplitude's official product documentation (SDK setup guides, API reference, help articles), include 'AMPLITUDE_DOCS' in entityTypes. This searches the public docs corpus — NOT your org's content — and returns doc pages with browsable URLs. Pair it with a natural-language query (e.g. "how to track revenue in the browser SDK"). DO NOT USE FOR: - AI agent results, agent analyses, or agent runs → use 'get_agent_results' instead - Getting full dashboard definitions with chart details → use 'get_dashboard' with the IDs from search results - Running queries or analysis → use 'query_dataset' or 'query_charts' ADDITIONAL INFORMATION: - Results are personalized to the user you are making the request on behalf of. - Results do not include the full object definition. You will need to use other tools to get the full object definition when needed. - Best practice is to query for a single entity type, unless the user's request is open ended. - The response includes an isOfficial flag in contentMeta to identify content that has been marked as official by the organization. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `appIds` | array | No | Array of app/project IDs to search within. If not provided, search will be for all apps the user has access to. | | `owners` | array | No | Filter by owners (array of login IDs) | | `queries` | array | No | Array of search query strings. If not provided or empty, search will return results based on relevance to the user. Multiple queries are executed in parallel and results are deduplicated using Reciprocal Rank Fusion (RRF). | | `rationale` | string | No | Brief explanation of why you are calling this tool and what you expect to learn from the result. | | `sortOrder` | string ("relevance" | "lastModified" | "viewCount" | "name") | No | Sort order for results | | `isOfficial` | boolean | No | Filter by official content only | | `entityTypes` | array | No | Types of entities to search for. Will be converted to camelCase internally for entityRef field access. 'AMPLITUDE_DOCS' is special: it searches Amplitude's public product documentation (via the docs search endpoint) instead of your org's content, and can be combined with org entity types in a single call. | | `search_goal` | string | No | What you are looking for and what you plan to do with the results. Example: "Find the main retention dashboard to answer a question about churn." | | `excludeOwners` | array | No | Filter out content by specific owners (array of login IDs) | | `limitPerQuery` | number | No | Maximum number of results to return per query. Results from multiple queries are deduplicated before being returned. We recommend starting with the default of 50, even if you are using multiple queries. | | `sortDirection` | string ("ASC" | "DESC") | No | Sort direction for results | | `semanticSearch` | boolean | No | Whether to use semantic search in addition to keyword search | | `includeArchived` | boolean | No | Whether to include archived entities | | `includeGenerated` | boolean | No | Whether to include AI-generated entites | | `lastViewedBefore` | number | No | Filter to entities last viewed before this epoch timestamp (in seconds). Useful for finding stale or unused content. | | `lastModifiedAfter` | number | No | Filter to entities modified after this epoch timestamp (in seconds). Useful for finding recently active content, e.g. charts modified in the last 7 days. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `results` | array | Yes | Array of search results | | `totalHits` | number | Yes | Total number of matching results | ### Share amp entities **Slug:** `AMPLITUDE_MCP_SHARE_AMP_ENTITIES` Manage sharing and org invites for Amplitude entities. One outcome-based tool selected by `action`. ACTIONS: - `get`: list owners/viewers for a CHART / DASHBOARD / NOTEBOOK / COHORT (`objectId` + `objectType`). - `share`: add users as viewers (`userIds` or singular `userId`). Existing editors are not downgraded. - `update_role`: set one user's role to CAN_EDIT / CAN_VIEW / NOT_ADDED (`userId` + `shareRole`). - `invite`: invite people to the org by email (optional chart access at invite time). Requires org role Manager or higher. INSTRUCTIONS: - Resolve object IDs with `search_amp_entities` first. Object types are uppercase enums (not "space"). - Resolve recipients with `get_amp_user_data` include=`org`. Pass returned `loginId` emails as recipients. If the user did not name a teammate, ask for an email instead of guessing. - Prefer `update_role` with CAN_EDIT to promote a viewer to editor; `share` only adds viewers. - Callers need edit access on the object to share or change roles. DO NOT USE FOR: - Creating a shared space, renaming it, changing space members, or moving content into a space: use `manage_amp_entities`. - Comments on objects: use `use_amp_comments`. - Product analytics end-user lookup: use `get_amp_user_data` with include id/profile/timeline. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `action` | string ("get" | "share" | "update_role" | "invite") | Yes | Discriminator: determines which set of parameters applies (get | share | update_role | invite) | | `emails` | array | No | Email addresses to invite. | | `userId` | string | No | Singular login ID alias for userIds. | | `message` | string | No | Optional notification message. | | `orgRole` | string ("VIEWER" | "MEMBER" | "MANAGER" | "ORG_ADMIN") | No | Org role to grant. Defaults to VIEWER. | | `userIds` | array | No | Login IDs (emails) to add as viewers. Resolve with get_amp_user_data include='org'. | | `objectId` | string | No | Entity ID. Resolve the entity with search_amp_entities, then pass its id as objectId with objectType CHART, DASHBOARD, NOTEBOOK, or COHORT. | | `shareRole` | string ("CAN_EDIT" | "CAN_VIEW" | "NOT_ADDED") | No | CAN_EDIT (editor), CAN_VIEW (viewer), or NOT_ADDED (remove). | | `nextAppUrl` | string | No | Optional absolute URL the invite email should send users to. | | `objectType` | string ("CHART" | "DASHBOARD" | "NOTEBOOK" | "COHORT") | No | CHART, DASHBOARD, NOTEBOOK, or COHORT (uppercase). | | `permGroupIds` | array | No | Optional permission group IDs to add invited users to. | | `projectRoles` | object | No | Optional legacy project role map keyed by project/app ID. Values are VIEWER, MEMBER, MANAGER, or ORG_ADMIN. | | `isSetupRequest` | boolean | No | Whether this invite is from a first-time setup flow. | | `projectRoleUuid` | string | No | Optional RBAC role UUID to assign across assignedProjectIds. | | `defaultProjectId` | string | No | Optional default project/app ID for the invited users. | | `assignedProjectIds` | array | No | Optional project/app IDs to assign when using projectRoleUuid. | | `initialObjectPermissions` | array | No | Optional chart permissions granted when the invite is accepted. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | array | Yes | Array of content blocks returned by the tool | ### Track ui render response **Slug:** `AMPLITUDE_MCP_TRACK_UI_RENDER_RESPONSE` Internal telemetry tool used by MCP UI components to report render latency and errors. NOT FOR DIRECT MODEL USE. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `chartId` | string | No | Chart ID or edit ID associated with the render | | `chartType` | string | No | Chart definition type (e.g., eventsSegmentation, funnel, retention) | | `rationale` | string | No | Brief explanation of why you are calling this tool and what you expect to learn from the result. | | `projectName` | string | No | Amplitude project name | | `uiComponent` | string | Yes | UI component identifier (e.g., amplitude-chart) | | `renderStatus` | string | Yes | Render status: "success" or error message | | `renderLatency` | number | Yes | UI render latency in milliseconds | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | array | Yes | Array of content blocks returned by the tool | ### Update properties **Slug:** `AMPLITUDE_MCP_UPDATE_PROPERTIES` Update property description, isOfficial, category, and/or name in a project's tracking plan. Use propertyType to select which kind of properties to update. This tool CANNOT be used to update property visibility or type. It can also NOT be used to set event properties to required. PROPERTY TYPES: | propertyType | What it updates | Key params | |---|---|---| | event | Event property metadata (global or event-scoped) | metadataScope, eventType (when scope is "event") | | user | User property metadata | descriptions, isOfficial, categories, newNames | INSTRUCTIONS: - Use get_properties first to verify property names and status before updating. - Call this tool only after the user has explicitly confirmed the properties to change and the exact new values. - Do not auto-apply speculative or inferred changes. - If the user has not specified a project, prompt them to decide. Don't decide for them. - This tool requires the "Update Tracking Plan" permission. If it fails with 403, note that an admin may need to grant access. - Make sure you have used the get_workspace_context tool to get information on workspace settings and environments for specified projectId. If there is more than one environment in the workspace, warn the user that the change will apply across multiple environments. If the workspace has main branch protected (indicated by approvalWF being "Required"), let the user know that changes cannot be made on the default branch and they will have to first create a new branch and make changes on that. - This tool only updates properties that are already in the tracking plan (status: planned, live, blocked). Unexpected properties (auto-detected from ingested data, isPlanned: false) are skipped. To edit an unexpected property's metadata, first add it to the plan with create_properties by setting properties[].isUnexpected: true on that item, then call update_properties. WHEN UPDATING EVENT PROPERTIES: - Do not try to update the properties globally if it failed on the event-scoped update, or vice-versa. Always confirm with the user whether the event property should be updated on a global or event-scoped basis. WHEN UPDATING USER PROPERTIES: - Remove the gp: prefix, if present, from user property names when requesting updates with this tool. EXAMPLES: - Event properties (global): { "propertyType": "event", "projectId": "123", "metadataScope": "global", "descriptions": { "revenue": "USD amount" } } - Event properties (event-scoped): { "propertyType": "event", "projectId": "123", "metadataScope": "event", "eventType": "Purchase", "descriptions": { "line_items": "JSON array" } } - User properties: { "propertyType": "user", "projectId": "123", "descriptions": { "plan_tier": "Customer subscription tier" } } #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `branchId` | string | No | Optional branch ID to target a non-default branch. If omitted, the project's default branch is used. Mutually exclusive with branchName. | | `newNames` | object | No | Map of current property names to new names (property_name -> new_name). Global-only: pass with metadataScope "global". Only valid for planned properties. | | `eventType` | string | No | Required when metadataScope is "event": the event type name whose properties to update. Ignored when metadataScope is "global". | | `projectId` | string | Yes | Project ID. If the user has not specified a project, prompt the user to decide. Dont decide for them. | | `branchName` | string | No | Optional branch name to target a non-default branch (e.g. "my-edits-branch"). If omitted, the project's default branch is used. Mutually exclusive with branchId. | | `categories` | object | No | Map of property names to category names (property_name -> category). Pass an empty string to clear the category. | | `isOfficial` | object | No | Map of property names to official status (property_name -> isOfficial). Global-only: pass with metadataScope "global". | | `descriptions` | object | No | Map of property names to their descriptions (property_name -> description) | | `propertyType` | string ("event" | "user") | Yes | Discriminator: determines which set of parameters applies (event | user) | | `metadataScope` | string ("global" | "event") | No | Whether updates apply to global (plan-wide) event properties or to properties local to a single event type. Use "event" only when the user wants changes scoped to one event; use "global" for shared definitions. When "event", eventType is required. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | array | Yes | Array of content blocks returned by the tool | ### Use amp ai visibility **Slug:** `AMPLITUDE_MCP_USE_AMP_AI_VISIBILITY` Use Amplitude AI Visibility. Set `action`: - `list_brands`: list tracked brands and get orgBrandId. Start here when the brand is unknown. - `read`: read a brand using orgBrandId plus `view`: scores, scores_over_time, reports, topics, prompts, prompt_responses, competitors, aliases, models, pages, sentiment, or sources. - `update_page_view_config`: set a project's page-view event, referrer property, and page-URL property. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `view` | string ("scores" | "scores_over_time" | "reports" | "topics" | "prompts" | "prompt_responses" | "competitors" | "aliases" | "models" | "pages" | "sentiment" | "sources") | No | Discriminator: determines which set of parameters applies (scores | scores_over_time | reports | topics | prompts | prompt_responses | competitors | aliases | models | pages | sentiment | sources) | | `limit` | number | No | Maximum rows to return (default: 100, max: 100) | | `action` | string ("read" | "list_brands" | "update_page_view_config") | Yes | Discriminator: determines which set of parameters applies (read | list_brands | update_page_view_config) | | `cursor` | string | No | Pagination cursor returned by the previous call | | `metric` | string ("visibility" | "citationRate") | No | Metric to trend over time | | `sortBy` | string ("responseCount" | "visibility" | "avgRank" | "relevancy" | "citationCount" | "promptCount" | "topicName" | "prompt" | "brandName" | "url" | "brandMentionPercent" | "domain") | No | Optional sort field | | `brandId` | number | No | Optional brand ID. Takes precedence over brandName. | | `endDate` | string | No | Optional end date in yyyy-mm-dd | | `groupBy` | string ("score" | "topic" | "competitor" | "citationDomain") | No | Optional grouping for the timeline | | `topicId` | number | No | Optional topic ID | | `promptId` | number | No | Optional prompt ID | | `reportId` | number | No | Optional report ID. Omit it to use the latest report. | | `brandName` | string | No | Optional brand name when brandId is not provided | | `pageLimit` | integer | No | Maximum nested pages to return per source (default: 20, max: 100) | | `projectId` | string | No | Project ID whose AI Visibility page view config should update. | | `promptIds` | array | No | Optional prompt IDs | | `rationale` | string | No | Why this call is needed. | | `sentiment` | string ("positive" | "neutral" | "negative" | "both") | No | Optional sentiment filter | | `startDate` | string | No | Optional start date in yyyy-mm-dd | | `orgBrandId` | number | No | Org brand ID to score within | | `limitSeries` | integer | No | Optional max number of series to return (default: 20) | | `limitThemes` | integer | No | Maximum sentiment themes to return (default: 100, max: 100) | | `modelFamilies` | array | No | Optional model family filters | | `sourceKeyword` | string | No | Optional keyword match against a citation domain, URL, or title | | `excludeBrandId` | number | No | Optional brand ID to exclude | | `sentimentTheme` | string | No | Optional sentiment theme filter | | `mentionsBrandId` | number | No | Optional brand ID that cited sources must mention | | `pageUrlProperty` | string | No | Event property name on the page view event that contains the page URL. | | `maxResponseChars` | integer | No | Maximum response characters to return (default: 1000, max: 5000) | | `referrerProperty` | string | No | Event property name on the page view event that contains the referrer. | | `mentionsBrandName` | string | No | Optional brand name that cited sources must mention when mentionsBrandId is not provided | | `pageViewedEventType` | string | No | Event type/name that represents a website page view. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | array | Yes | Array of content blocks returned by the tool | ### Use amp comments **Slug:** `AMPLITUDE_MCP_USE_AMP_COMMENTS` Read and add plain-text comments on Amplitude charts, dashboards, and notebooks. One outcome-based tool selected by `action`. ACTIONS: - `get`: read comments for `source` + `id`. Dashboards/notebooks also roll up comments from charts inside them. - `add`: leave a plain-text comment (`content`). Prefixed with the AI client name automatically. INSTRUCTIONS: - `source`, `id`, and `projectId` are required on every call. Resolve the object with `search_amp_entities`, then pass its id as `id` with source CHART, DASHBOARD, or NOTEBOOK. `projectId` comes from `get_amplitude_context`. - Call get before add to avoid duplicates. - Comments are plain text only (no mentions/reactions). DO NOT USE FOR: - Opportunity / Wave comments: use opportunity tools. - Sharing access: use `share_amp_entities`. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `id` | string | Yes | Chart, dashboard, or notebook ID from search_amp_entities. | | `action` | string ("get" | "add") | Yes | Discriminator: determines which set of parameters applies (get | add) | | `source` | string ("CHART" | "DASHBOARD" | "NOTEBOOK") | Yes | Object type: CHART, DASHBOARD, NOTEBOOK. | | `content` | string | No | Plain-text comment body. | | `projectId` | string | Yes | Amplitude project ID from get_amplitude_context. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | array | Yes | Array of content blocks returned by the tool | ### Use amp dashboards **Slug:** `AMPLITUDE_MCP_USE_AMP_DASHBOARDS` Read and manage Amplitude dashboards. One outcome-based tool selected by `action`. ACTIONS: - `get`: read up to three dashboards by `dashboardIds`. Resolve IDs with `search_amp_entities` (entityTypes: DASHBOARD). - `create`: create a dashboard. Row items accept saved chart IDs and temporary chart edit IDs interchangeably in `chartId`; edit IDs are saved as permanent charts automatically before the dashboard is created. Optionally pass `chartEdits` to control the saved name and description of each edit. If the events the user asked about are not instrumented, explain the gap and confirm before building a proxy dashboard from substitute events. Never pass placeholder or invented chart IDs. - `edit`: update dashboard metadata or layout. Read the dashboard first and pass its `lastModified` as `expectedLastModified`. Rows in `set_rows` / `update_row` / `insert_row` accept saved chart IDs and temporary chart edit IDs interchangeably, same as `create` — use this to add a freshly queried chart to an existing dashboard. - `replace_properties`: discover or replace chart properties across a dashboard. - `subscribe` / `edit_subscription`: create or edit a recurring email, Slack, or Teams dashboard delivery. SUBSCRIPTIONS: - Use top-level `notificationType`, `sendWeek`, `sendDay`, and `sendHourUtc`; do not send nested JSON strings. - For email, `email` defaults to the current user; never ask the user for their own email address. For Slack or Teams, provide `recipientType` and `recipientId`; Teams also needs `recipientTeamId`. - If the user has not given a delivery channel or cadence, ask instead of assuming defaults. DO NOT USE FOR: - Finding dashboards by name: use `search`. - Creating a shared space, changing space members, or moving an existing dashboard into a space: use `manage_amp_entities`. - Creating or querying chart data: use the chart tools. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `edit` | string | No | One layout operation from the dashboard returned by get. | | `name` | string | No | Dashboard name. | | `rows` | array | No | Dashboard layout rows. Item chartId accepts a saved chart ID or a temporary chart edit ID; edit IDs are saved automatically. | | `email` | string | No | Email recipient. Defaults to the current user's email when omitted. | | `action` | string ("get" | "create" | "edit" | "replace_properties" | "subscribe" | "edit_subscription") | Yes | Discriminator: determines which set of parameters applies (get | create | edit | replace_properties | subscribe | edit_subscription) | | `dryRun` | boolean | No | Preview changes without saving. | | `sendDay` | string ("every" | "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday") | No | Delivery weekday. | | `metadata` | object | No | Dashboard metadata updates. | | `sendWeek` | string ("every" | "first" | "second" | "third" | "last") | No | Delivery cadence week. | | `attachCsv` | boolean | No | Attach CSV to email deliveries. | | `chartEdits` | array | No | Optional names and descriptions for chart edits referenced in rows. Without an entry, an edit referenced in rows is saved using the name from its definition. | | `chartMetas` | object | No | Optional display configuration keyed by saved chart ID. | | `dashboardId` | string | No | Dashboard ID. Resolve dashboard IDs with search_amp_entities (entityTypes: ['DASHBOARD']). | | `description` | string | No | Dashboard description. | | `destination` | string | No | Where to save. Omit for the personal space (previous behavior). | | `recipientId` | string | No | Slack or Teams recipient ID. | | `sendHourUtc` | integer | No | UTC delivery hour. | | `dashboardIds` | array | No | Dashboard IDs to read (array of 1 to 3 strings, e.g. ['abc1234']). Resolve with search_amp_entities (entityTypes: ['DASHBOARD']). | | `replacements` | array | No | Array of replacement definitions from discovery mode. | | `recipientType` | string ("channel" | "user") | No | Slack or Teams recipient type. | | `subscriptionId` | string | No | Subscription ID. | | `recipientTeamId` | string | No | Teams team ID. | | `notificationType` | string ("email" | "slack" | "teams") | No | Delivery channel. | | `expectedLastModified` | integer | No | lastModified returned by get. Read the dashboard first. | | `confirmSharedChartImpact` | boolean | No | Confirm updates to charts used elsewhere. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | array | Yes | Array of content blocks returned by the tool | ### Use amp experiments **Slug:** `AMPLITUDE_MCP_USE_AMP_EXPERIMENTS` Unified entry point for experiments: read, analyze, create, and set metrics. Replaces get_experiments, query_experiment, create_experiment, and update_experiment. ACTIONS: - `get` (default): fetch experiments by `ids`. - `analyze`: run experiment analysis for `id` (same as query_experiment). Omit metricIds unless the user asks for specific/secondary metrics. - `create`: create an experiment across projects (same fields as create_experiment). - `update`: replace experiment metrics (`experimentId` + `metrics`). For name/variants/testers/deployments/links on an experiment, use `use_amp_flags` action `update` — experiments are flags. INSTRUCTIONS: - Resolve experiment IDs with `search` (entityTypes: ["EXPERIMENT"]) before get/analyze/update. - Resolve deployment IDs with `use_amp_flags` action `list_deployments` before passing `deploymentIds`. - Resolve metric IDs with `use_amplitude_metrics` before passing `metrics` or `projectMetrics`. - On `create`, strongly prefer setting `proxyExposureEvent` to the event where users hit the tested surface. Without it, pre-launch planning falls back to Any Active Event and can wildly overstate the required duration. - ALWAYS reference queried experiments by their Amplitude link in analyses. - Metrics for `update` fully replace the existing set; create metrics first via `use_amplitude_metrics`. DO NOT USE FOR: - Feature flags → `use_amp_flags`. - Metric definitions → `use_amplitude_metrics`. - Chart / dataset queries → chart query tools. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `id` | string | No | analyze: experiment ID to query. | | `ids` | array | No | get: experiment IDs to retrieve. | | `key` | string | No | create: unique experiment key. | | `name` | string | No | create: human-readable experiment name. | | `links` | array | No | Links to associate with the experiment (e.g., design docs, tickets, PRs). Each link requires a url and title. | | `action` | string ("get" | "analyze" | "create" | "update") | No | Experiment operation: 'get' | 'analyze' | 'create' | 'update'. Defaults to get. | | `filters` | array | No | analyze: optional metric filters. | | `groupBy` | array | No | analyze: optional group-by, e.g. [{"type":"user","value":"device type","group_type":"User"}]. | | `metrics` | array | No | update: full replacement metric set. Empty array clears metrics. | | `variants` | array | No | create: variants (defaults to control + treatment if omitted). | | `metricIds` | array | No | analyze: ONLY if the user explicitly requests specific or all metrics. Omit for primary/recommended metric only. | | `rationale` | string | No | Brief explanation of why you are calling this tool and what you expect to learn from the result. | | `projectIds` | array | No | create: project IDs (prompt the user if unspecified). | | `description` | string | No | Experiment description explaining what is being tested | | `bucketingKey` | string ("user_id" | "device_id" | "amplitude_id") | No | Property used to bucket users into variants. One of "user_id", "device_id", "amplitude_id". Omit unless the user asks — Amplitude then picks the right default ("amplitude_id" for remote, "device_id" for local). Group-level bucketing (group_id/group_name) requires bucketingGroupType and is not supported via MCP yet. | | `experimentId` | string | No | update: experiment ID whose metrics to replace. | | `deploymentIds` | array | No | create: deployment (API key) IDs to associate. List available IDs with use_amp_flags action list_deployments. Single-project creates only. | | `evaluationMode` | string ("local" | "remote") | No | Defaults to "remote". Set to "local" if specified by the user | | `projectMetrics` | array | No | Metrics to attach to the experiment for analysis | | `proxyExposureEvent` | object | No | Proxy exposure event used for pre-launch planning (duration estimator, control mean, sample size). Set it to the event where users first encounter the tested surface (e.g. the screen-viewed event for the screen being changed). Strongly recommended for funnel/conversion metrics: without it, planning falls back to Any Active Event and denominates the baseline against all active users. Does not change the running experiment's exposure event. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | array | Yes | Array of content blocks returned by the tool | ### Use amp flags **Slug:** `AMPLITUDE_MCP_USE_AMP_FLAGS` Unified entry point for feature flags and deployments. Replaces get_flags, create_flags, update_flag, and get_deployments. ACTIONS: - `get` (default): fetch flags by `flagIds` (numeric IDs or flag keys). - `create`: create one or more flags (`flags` array — same shape as create_flags). Supports evaluationMode, bucketingKey, percentage, rolloutWeights, targetSegments, testers, deploymentIds. - `update`: update a flag or experiment (`flagId` + only the fields to change). Supports flagConfig (name/description/enabled), evaluationMode, bucketingKey, percentage, rolloutWeights, targetSegments, variants, testers, deployments, links. Experiments are flags — use this for shell/rollout changes on experiments too. - `list_deployments`: list deployments (API keys) for the current project. Deployments are shared by flags and experiments — this is the only place to list them. INSTRUCTIONS: - Resolve IDs with `search` (entityTypes: ["FLAG"] or ["EXPERIMENT"]) before get/update. - Use `list_deployments` before create/update when associating deployment IDs. - Only include update sections you intend to change. - evaluationMode is "local" or "remote"; bucketingKey is "user_id", "device_id", or "amplitude_id". - For update rollout: `percentage` / `rolloutWeights` apply to "All Other Users"; omit `targetSegments` to keep existing conditional segments, pass `[]` to clear them, or pass a full array to replace them. - To GA a flag: `{"action":"update","flagId":"...","percentage":100,"rolloutWeights":{"on":1}}` (optionally `"targetSegments":[]` to drop prior segments). DO NOT USE FOR: - Experiment analysis → `use_amp_experiments` action `analyze`. - Attaching experiment metrics → `use_amp_experiments` action `update`. - Creating experiments → `use_amp_experiments` action `create`. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `flags` | array | No | create: flags to create (same shape as create_flags). | | `links` | object | No | Link operations | | `action` | string ("get" | "create" | "update" | "list_deployments") | No | Flag operation: 'get' | 'create' | 'update' | 'list_deployments'. Defaults to get. | | `flagId` | string | No | update: ID of the flag or experiment to update. | | `flagIds` | array | No | get: flag IDs or keys to retrieve. | | `testers` | object | No | Tester operations | | `variants` | object | No | Variant operations | | `rationale` | string | No | Brief explanation of why you are calling this tool and what you expect to learn from the result. | | `flagConfig` | object | No | Flag configuration updates | | `percentage` | number | No | Default rollout percentage for "All Other Users" (0-100). Set to 100 to enable for everyone. | | `deployments` | object | No | Deployment operations | | `bucketingKey` | string | No | Property used to bucket users into variants. One of "user_id", "device_id", "amplitude_id". Group-level bucketing (group_id/group_name) requires bucketingGroupType and is not supported via MCP yet. | | `evaluationMode` | string | No | Evaluation mode: "local" or "remote". | | `rolloutWeights` | object | No | Default variant weight distribution for "All Other Users" (e.g., {"on": 1} for 100% to "on" variant). | | `targetSegments` | array | No | Target segments for conditional rollout. Replaces existing conditional segments when provided; omit to keep them; pass [] to clear them. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | array | Yes | Array of content blocks returned by the tool | ### Use amp guides surveys **Slug:** `AMPLITUDE_MCP_USE_AMP_GUIDES_SURVEYS` List Guides and Surveys or get one by ID. Use `action: "list"` for filtered discovery and rollout summaries; use `action: "get"` for full content, targeting, variants, steps, and rollout details. Both require `projectId`; get also requires `nudgeId`. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | Maximum number of items to return per page. Defaults to 50, capped at 200. | | `types` | array | No | Types to include. Defaults to both Guides and Surveys. | | `action` | string ("list" | "get") | Yes | Discriminator: determines which set of parameters applies (list | get) | | `cursor` | string | No | Opaque cursor from a previous response's `nextCursor`. Omit for the first page. | | `nudgeId` | string | No | ID of the nudge (guide or survey) to retrieve. | | `platform` | string ("web" | "ios" | "android" | "react-native" | "desktop" | "flutter") | No | Filter by target platform. 'web' also matches rows with no platform set. | | `createdBy` | string | No | Filter by the email (or login id) of the user who created the guide/survey. Exact match against the stored `createdBy` value. | | `projectId` | string | Yes | Project ID (appId) to list Guides and Surveys for. Prompt the user if not specified. | | `rationale` | string | No | Why this Guides and Surveys read is needed. | | `createdAfter` | string | No | ISO 8601 lower bound on created timestamp (inclusive). | | `createdBefore` | string | No | ISO 8601 upper bound on created timestamp (inclusive). | | `includeArchived` | boolean | No | Include archived (soft-deleted) items. Defaults to false. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | array | Yes | Array of content blocks returned by the tool | ### Use amplitude ai feedback **Slug:** `AMPLITUDE_MCP_USE_AMPLITUDE_AI_FEEDBACK` Read Amplitude AI Feedback (customer VoC) for a project — surveys, support tickets, app reviews, and grouped themes. This is CUSTOMER product feedback (what users said in connected sources). NOT for: - AI/LLM agent session quality, transcripts, or agent analytics → use get_amplitude_agent_analytics_info - Reporting that you (the agent) are stuck → use report_agent_feedback (requires user approval) Set `facet` to choose what to read: - `sources` → connected feedback integrations + sourceIds (call first when you need sourceIds for filters) - `comments` → raw feedback comments with search, categories, pagination - `insights` → grouped themes (requests, complaints, loved features, …) sorted by popularity - `mentions` → drill into comments behind ONE insightId or trendId (do not call for every insight) - `trends` → saved themes tracked over time TYPICAL WORKFLOWS: 1. Bootstrap: facet=sources → facet=comments or facet=insights 2. Themes: facet=insights → facet=mentions with insightId when user asks for examples 3. Tracked themes: facet=trends → facet=mentions with trendId EXAMPLES: - Connected sources: {"facet": "sources", "projectId": "123456"} - Complaints this month: {"facet": "insights", "projectId": "123456", "types": ["complaint"], "dateStart": "2026-06-01", "dateEnd": "2026-06-30"} - What are customers saying about pricing: {"facet": "comments", "projectId": "123456", "search": ["pricing", "price"]} - Show comments behind insight 42: {"facet": "mentions", "projectId": "123456", "insightId": 42} #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Optional page number for pagination (default: 1) | | `ampId` | string | No | Optional Amplitude user ID to filter insights by specific amplitude user | | `facet` | string ("sources" | "comments" | "insights" | "mentions" | "trends") | Yes | Discriminator: determines which set of parameters applies (sources | comments | insights | mentions | trends) | | `types` | array | No | Array of insight types to filter by | | `search` | string | No | Search term(s) to filter comments by body text. Multiple terms are OR-matched. Pass granular synonyms for better recall. | | `dateEnd` | string | No | Optional end date for filtering comments (ISO date string) | | `trendId` | number | No | The trend ID to retrieve mentions for (required if insightId not provided) | | `category` | string | No | Optional category filter (e.g., request, complaint, lovedFeature). Legacy values (bug, painPoint, takeaway) are still accepted for backwards compatibility. | | `pageSize` | integer | No | Optional page size for pagination (default: 50, max: 50) | | `sourceId` | number | No | Source ID to filter mentions by - should match get_feedback_insights query | | `dateStart` | string | No | Optional start date for filtering comments (ISO date string) | | `insightId` | number | No | The insight ID to retrieve mentions for (required if trendId not provided) | | `projectId` | string | Yes | The project ID (appId) to get feedback sources for | | `rationale` | string | No | Brief explanation of why you are calling this tool and what you expect to learn from the result. | | `sourceIds` | array | No | Optional source IDs to scope comments to specific feedback sources (default: all sources). Get IDs from get_feedback_sources. | | `categories` | array | No | Optional insight categories (e.g. ["complaint","request"]). Keeps only comments with an extracted point in one of these categories. Pass all categories to keep only actionable comments (drop noise with no insights). | | `labelFilters` | array | No | Optional label filters as "labelKey:valueKey" tokens (e.g. ["product_area:onboarding_flow", "severity:high"]). Multiple values for the same labelKey are OR-matched; different labelKeys are AND-matched. Use the value keys returned in a comment's labels field, not display names. | | `orderDirection` | string ("asc" | "desc") | No | Optional sort direction by mention count (default: desc) | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | array | Yes | Array of content blocks returned by the tool | ### Use amplitude chart monitors **Slug:** `AMPLITUDE_MCP_USE_AMPLITUDE_CHART_MONITORS` Read and manage chart alert monitors. One tool with eight actions selected by `action` (default `get_alerts`). ACTIONS: - `get_alerts` (default) → recent alert anomalies for a chart (`chartId`) or project (`projectId`). - `list` → custom chart monitors you created or are subscribed to (email / Slack / Teams). Includes ones others created if you are a recipient. Chart name + short summary + alertsLast30Days. Optional `projectId`. Does not need `chartId`. - `get_config` → a chart's monitor configuration + subscribers when `chartId` is set. Omit `chartId` to list (same as `list`). Charts with no monitor return hasMonitor=false — then use `create`. - `create` → add a monitor on a chart that does not have one. Requires `chartId`. Defaults to smart anomaly detection (99% CI, above or below) and emails the current user. - `history` → audit trail of monitor config changes (who changed what, when). Requires `monitorId` or `chartId`. Not alert firings — use `get_alerts` for those. - `subscribe` / `unsubscribe` → add/remove an alert subscription (email for the current user, or a Slack/Teams channel). Requires `monitorId` and `deliveryMethod`. - `update` → enable or disable a monitor. Requires `monitorId` and `enabled`. INSTRUCTIONS: - If the user asks what chart alerts or monitors they have, call `list` (or `get_config` without chartId). That returns monitors they created or are subscribed to — not every monitor in the org. - If `get_config` returns hasMonitor=false, call `create` with that `chartId` instead of telling the user to use the Amplitude UI. - Resolve a `monitorId` first with `get_config` (from a `chartId`) before `subscribe` / `unsubscribe` / `update`. For `history`, you may pass `chartId` directly instead of `monitorId`. - For `get_alerts` and `list`, `projectId` is optional when you have access to exactly one project; otherwise provide it to scope. Pass `chartId` to scope `get_alerts` to one chart. - Email subscriptions only manage the current user; for Slack/Teams pass `deliveryChannel` (and `deliveryWorkspaceId` when needed). DO NOT USE FOR: - Reading chart data → use 'get_amplitude_charts' (include='data') or 'query_dataset'. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | No | create: optional monitor name. Defaults to the chart name. | | `limit` | integer | No | get_alerts: max alerts (default 20). list: max monitors per group (default 50). 1-100. | | `action` | string ("get_alerts" | "list" | "get_config" | "create" | "history" | "subscribe" | "unsubscribe" | "update") | No | What to do: 'get_alerts' (default), 'list', 'get_config', 'create', 'history', 'subscribe', 'unsubscribe', or 'update'. | | `chartId` | string | No | Chart ID. Scopes get_alerts to one chart; required for create; for get_config, omit to list monitors. Optional for history (resolves monitorId). | | `enabled` | boolean | No | update: true enables the monitor, false disables it. | | `frequency` | string ("daily" | "hourly") | No | create: 'daily' (default) or 'hourly'. | | `monitorId` | string | No | history / subscribe / unsubscribe / update: the monitor to act on. For history, chartId is an alternative to monitorId. | | `projectId` | string | No | Project ID. Scopes get_alerts and list. Optional with single-project access. | | `rationale` | string | No | Brief explanation of why you are calling this tool and what you expect to learn from the result. | | `conditions` | array | No | create: alert conditions. Defaults to smart anomaly detection at 99% CI, above or below. | | `includeUnseen` | boolean | No | get_alerts: return only alerts not yet marked seen. | | `deliveryMethod` | string ("email" | "slack" | "teams") | No | subscribe / unsubscribe: delivery method (email, slack, or teams). | | `deliveryChannel` | string | No | subscribe / unsubscribe: Slack channel ID or Teams conversation ID (omit for email). | | `emailRecipients` | array | No | create: emails to notify. Defaults to the current user. Pass [] for none. | | `deliveryWorkspaceId` | string | No | subscribe / unsubscribe: optional workspace/tenant context for Slack or Teams. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | array | Yes | Array of content blocks returned by the tool | ### Use amplitude cohorts **Slug:** `AMPLITUDE_MCP_USE_AMPLITUDE_COHORTS` Work with Amplitude cohorts end to end. One tool with eleven actions selected by `action` (default `list`). DISCOVER & READ: - `list` (default) → browse/search the project's cohorts by name (`projectId` required, optional `query`). Use this FIRST when you don't have cohort ids — never guess or use placeholder ids. - `get` → full cohort definitions/metadata for known ids (`cohortIds`, max 50). - `find` → ad-hoc audience: individual users who performed an event (`projectId`; optional `event`, defaults to any active user; optional `timeRange`, `limit`). Returns user records + session replays, without creating a cohort. - `membership` → is a user in these cohorts? (`cohortIds` max 5 + one of `amplitudeId` / `userId` / `email`). CREATE: - `create` → save a new cohort (`projectId`, `name`, `definition`). Definition uses andClauses/orClauses condition sets. SYNC & EXPORT: - `get_destinations` → configured sync destinations for a project (`projectId`). Call BEFORE `sync`. - `get_syncs` → sync jobs + status (`projectId` for the whole project, or `cohortIds`). - `get_history` → execution logs for one cohort's syncs (`cohortId`, `projectId`, `target`). - `sync` → trigger a one-time sync now (`cohortId` + `targetId` from get_destinations; `partner` too for classic integrations). Two-step confirm: first call returns a preview, re-call with `confirmed: true`. Cohorts under 10k sync synchronously; 10k+ return `submitted` — tell the user it was queued, then poll `get_history`. - `export_submit` → start a CSV export of members (`cohortId`), returns `exportRequestId`. - `export_download` → poll export status / fetch CSV url (`cohortId` + `exportRequestId`). INSTRUCTIONS: - Resolve cohort ids with `list` before `get`/`membership`/`sync`/`export_*`. - For `sync`: always call `get_destinations` first — a targetId is only unique within a partner. - `membership` accepts `userId`/`email` directly (resolved to an amplitudeId automatically, cached). DO NOT USE FOR: - Aggregate counts/trends over a cohort → use 'query_dataset' with a cohort segment filter. - One user's profile or event timeline → use 'get_amp_user_data'. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | No | create: name of the new cohort. | | `email` | string | No | membership: email to check (resolved to an amplitudeId automatically). | | `event` | object | No | find: event the users performed (defaults to "_active" — any active user). Call get_events first to confirm exact event names. | | `limit` | integer | No | list: max cohorts to return (default 20). find: max users to return (default 10). | | `query` | string | No | list: text to match against cohort names (omit to browse by recency). | | `action` | string ("find" | "list" | "get" | "membership" | "create" | "get_destinations" | "get_syncs" | "get_history" | "sync" | "export_submit" | "export_download") | No | What to do: 'list' (default), 'get', 'find', 'membership', 'create', 'get_destinations', 'get_syncs', 'get_history', 'sync', 'export_submit', or 'export_download'. | | `target` | string | No | get_history: sync destination to read logs for (e.g. "braze", "s3", "salesforce"). | | `userId` | string | No | membership: user id to check (resolved to an amplitudeId automatically). | | `partner` | string | No | sync: partner/integration type of a classic destination (e.g. "braze"), from get_destinations. Omit for Connector Manager destinations. | | `cohortId` | string | No | Single cohort ID for sync / get_history / export_submit / export_download. | | `pageSize` | integer | No | get_history: results per page (default 20, max 100). | | `propKeys` | array | No | export_submit: specific user properties to include. | | `targetId` | string | No | sync: destination target from get_destinations (with partner for classic integrations; alone for Connector Manager destinations). get_history: optional instance filter. | | `cohortIds` | array | No | Cohort IDs for get (max 50), membership (max 5), or to scope get_syncs (max 10). Resolve real ids via list first — never pass placeholders. | | `confirmed` | boolean | No | sync: set true only after the user reviewed the confirmation preview returned by the first call. | | `errorOnly` | boolean | No | get_history: only return failed sync executions. | | `projectId` | string | No | Project/app ID. Required for list / find / create / get_destinations; required for get_syncs when cohortIds is omitted; required for get_history. | | `rationale` | string | No | Brief explanation of why you are calling this tool and what you expect to learn from the result. | | `timeRange` | object | No | find: time window (defaults to Last 30 Days). | | `cohortType` | string ("redshift" | "clause_based_fine_grained_time" | "cluster" | "funnels" | "sessions") | No | create: computation engine (default "redshift" — only set for specialized cohort types). | | `definition` | object | No | create: cohort definition (andClauses of condition sets, countGroup, version). | | `pageNumber` | integer | No | get_history: page number (default 1). | | `amplitudeId` | string | No | membership: Amplitude ID of the user to check. | | `cohortOwner` | string | No | create: owner of the cohort (defaults to the current user). | | `exportRequestId` | string | No | export_download: the id returned by export_submit. | | `includeProperties` | boolean | No | export_submit: include user properties in the CSV (may slow the export). | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | array | Yes | Array of content blocks returned by the tool | ### Use amplitude data connections **Slug:** `AMPLITUDE_MCP_USE_AMPLITUDE_DATA_CONNECTIONS` Unified entry point for everything to do with a project's data connections — ingestion sources, import/export job history, Snowflake credentials, live Snowflake warehouse browsing, and Amplitude import-config recommendations. Replaces 10 previously separate tools (get_data_ingestion_sources, get_data_source_details, get_data_warehouse_jobs, get_data_warehouse_health, get_falcon_integrations, get_snowflake_warehouse_databases/_schemas/_tables/_columns/_rows, recommend_falcon_import_config). ROUTES (action='read', selected by `view`): - omit `dataSourceId` and `view` → list every configured source for the project ('data_connections.list (get_data_ingestion_sources)'). Start here. - `dataSourceId` set, `view` omitted or 'summary' → detail for that one source ('data_connections.summary (get_data_source_details)'). - `view: 'connections'` → list the project's Snowflake credentials/integrations ('data_connections.connections (get_falcon_integrations)'). Use this to find an `integrationId` for the browsing views below. - `view: 'jobs'` → import/export batch job history for one connection ('data_connections.jobs (get_data_warehouse_jobs)'). Requires `dataSourceId` in `vacuum:{id}` / `falcon:{id}` / `gyrfalcon:{id}` form (as returned by the list route; `gyrfalcon:` answers `supported: false` — no per-run history yet, not "never ran"); auto-resolved when the project has exactly one configured source. - `view: 'health'` → project-wide health of EVERY import and export connection in one call ('data_connections.health (get_data_warehouse_health)'): which are failing, degraded, running, healthy, idle or unknown, worst first, with last-success age per connection. No `dataSourceId`. Optional `direction` (imports or exports only), `since` (failure-counting window, default 7 days) and `maxConnections`. Use this instead of listing sources and destinations and then calling 'jobs' per connection. - `view: 'databases' | 'schemas' | 'tables' | 'columns' | 'rows'` → live Snowflake warehouse browsing, one drill-down level at a time ('data_connections.databases (get_snowflake_warehouse_databases)' etc.). Needs a connection reference (`integrationId` or `sourceDestinationId`) — auto-resolved via 'connections' when the project has exactly one Snowflake credential. Snowflake-only today; other warehouse types will extend this enum, not rename the tool. ROUTES (action='recommend_import'): - Generates a heuristic Amplitude import config + ready-to-run SQL for one or more warehouse tables ('data_connections.recommend_import (recommend_falcon_import_config)'). This is the ONLY correct way to produce warehouse-import SQL — never hand-write it. WHEN TO USE: - Anything about "what's sending data into my project", "did this import/export succeed", "are any of my pipelines failing / is anything broken or stale" (that is 'health'), "what Snowflake credentials/connections exist", "what's in my Snowflake warehouse", or "generate an import config/SQL for this table". INSTRUCTIONS: - Always provide `projectId`. - Prefer omitting `dataSourceId`/connection refs on the first call in a session — this tool auto-resolves the connection when there's exactly one, and only asks you to disambiguate when there are several. - For 'jobs', pass the prefixed `dataSourceId` from the list route (e.g. `vacuum:42`, `falcon:abc-123`, `gyrfalcon:c-9`) — not a bare numeric id. - For 'health', omit `dataSourceId`; it inspects every connection. If the response says `truncated: true`, raise `maxConnections` or narrow with `direction` before concluding the project is healthy. - For browsing views, drill down one level per call: 'databases' → 'schemas' (needs `database`) → 'tables' (needs `database`+`schema`) → 'columns'/'rows' (needs a read-only `sql` SELECT). - For 'recommend_import', provide `tables` (fully qualified dotted names) and either `sourceDestinationId` (preferred — lets Amplitude introspect the warehouse; NOT the same id as `integrationId` from 'connections') or `warehouseKind` for a dry run with caller-supplied `columns`/`sampleRows`. EXAMPLES: - List sources: { "projectId": "123456" } - Job history: { "projectId": "123456", "view": "jobs", "dataSourceId": "vacuum:42" } - Health of every connection: { "projectId": "123456", "view": "health" } - Browse tables: { "projectId": "123456", "view": "tables", "database": "ANALYTICS", "schema": "PUBLIC" } - Recommend import: { "projectId": "123456", "action": "recommend_import", "sourceDestinationId": "789", "tables": [{"fullyQualifiedName": "ANALYTICS.PUBLIC.EVENTS"}] } NOTES: - Sensitive credential fields are never returned; empty strings stand in for secrets. - Databricks/BigQuery/GA4 warehouse-native browsing isn't implemented yet — only classic Snowflake. `recommend_import` returns a `WAREHOUSE_NOT_SUPPORTED_YET` error for other kinds; surface it without retrying. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sql` | string | No | 'columns'/'rows' views. A read-only Snowflake SELECT statement (e.g. SELECT * FROM DB.SCHEMA.TABLE). | | `view` | string ("summary" | "connections" | "jobs" | "health" | "databases" | "schemas" | "tables" | "columns" | "rows") | No | Which read outcome to fetch. Omit for the list/summary route. 'connections' lists Snowflake credentials. 'jobs' is batch job history for ONE connection; 'health' is a project-wide status report across every connection. 'databases'|'schemas'|'tables'|'columns'|'rows' drill into a live Snowflake connection one level at a time. | | `limit` | integer | No | 'jobs' view only. Max jobs per page (1-100, default 25). | | `since` | string | No | 'jobs' and 'health' views. Inclusive lower bound on job time, as a date or ISO-8601 date-time. A value with no timezone is read as UTC. On 'health' it scopes the failure-counting window. | | `until` | string | No | 'jobs' view only. Exclusive upper bound on job time, same formats as `since`. | | `action` | string ("read" | "recommend_import") | No | Defaults to 'read' (use `view` to pick the outcome). Set to 'recommend_import' to generate an Amplitude import config + SQL for warehouse tables — ignores `view`. | | `cursor` | string | No | 'jobs' view only. Opaque pagination token from a previous call. | | `schema` | string | No | 'tables' view. The Snowflake schema to list tables for. | | `status` | string ("SUCCESS" | "FAILURE" | "IN_PROGRESS" | "WAITING" | "COMPLETED_WITH_ERRORS" | "CANCELLED" | "ALL") | No | 'jobs' view only. Filter by unified job status. Defaults to no filter. | | `tables` | array | No | One or more tables to generate import recommendations for. | | `jobMode` | string ("automatic" | "manual") | No | 'jobs' view, export connections only. Defaults to 'automatic' (scheduled). Use 'manual' for manual/backfill export jobs. | | `numRows` | integer | No | 'rows' view only. Max sample rows to fetch (default 10 if omitted), capped at 1000. | | `options` | object | No | Optional tuning for sampling, ranking, and diagnostics. | | `database` | string | No | 'schemas'/'tables' views. The Snowflake database to drill into. | | `direction` | string ("import" | "export") | No | 'jobs' and 'health' views. On 'jobs' it overrides the inferred connection direction; only pass it if the inference is wrong. On 'health' it restricts the report to import sources or export destinations. | | `projectId` | string | Yes | The project ID (appId) to operate on. Call get_amplitude_context first if unknown — never guess. | | `rationale` | string | No | Brief explanation of why you are calling this tool and what you expect to learn from the result. | | `dataSourceId` | string | No | The data source id. Omit for the list route. For 'summary' pass the id from the list route (e.g. `library:ios-swift`, `vacuum:42`). For 'jobs' pass the prefixed id (`vacuum:{id}` or `falcon:{id}`). | | `integrationId` | string | No | Browsing views ONLY. A Snowflake credential id from the 'connections' view. Provide this or sourceDestinationId — auto-resolved when the project has exactly one. NOT valid for recommend_import (use sourceDestinationId there instead). | | `warehouseKind` | string ("SNOWFLAKE_IMPORT" | "BIGQUERY_IMPORT" | "DATABRICKS_IMPORT" | "GA4_IMPORT") | No | Warehouse kind, required only when no connection exists yet (dry run from caller-supplied inputs). Provide exactly one of sourceDestinationId or warehouseKind. Only SNOWFLAKE_IMPORT is implemented today. | | `maxConnections` | integer | No | 'health' view only. Max connections to inspect in one call (1-50, default 25). | | `sourceDestinationId` | string | No | Browsing views: an import source/destination id identifying the Snowflake connection, or integrationId may be used instead. recommend_import: REQUIRED connection identifier — integrationId is not accepted here, they are different ids. | | `includeSystemSchemas` | boolean | No | 'schemas' view only. Include account-metadata schemas such as INFORMATION_SCHEMA. Off by default. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | array | Yes | Array of content blocks returned by the tool | ### Use amplitude metrics **Slug:** `AMPLITUDE_MCP_USE_AMPLITUDE_METRICS` Unified entry point for metric definitions, goals, and goal alerts in a project. Replaces get_metrics, create_metric, update_metric, delete_metric, get_metric_goals, the five goal write tools, and the four goal-alert CRUD tools. WHEN TO USE: - Anything about defining metrics, setting targets on metrics, listing goals/pacing, or configuring goal alerts. - NOT for querying metric *values* over time — use query_metric or query_dataset instead. INSTRUCTIONS: - Select the operation with `action`. - Metric defs: resolve metricIds with search first; create_metric needs projectId, name, and metricType plus type-specific fields (same rules as the legacy create_metric tool). - Goals: use get_goals to discover goalIds before update / archive / restore / delete / alert actions. - update_metric may be two-step when changing a metric definition with dependents; delete_metric and delete_goal may also be two-step when dependents exist. For any of these operations, first call without confirmed, show the returned dependency payload to the user, then retry with confirmed: true only after user confirmation. - get_goals accepts either metricId OR projectId, not both. DO NOT USE FOR: - Chart or experiment metric *values* → query_metric / query_dataset. - Experiments and flags → get_experiments / get_flags / create_experiment. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | No | Human-readable name for the metric | | `event` | object | No | Event definition for single-event metrics (UNIQUES, TOTALS, PROPSUM, PROPAVG). | | `action` | string ("get_metrics" | "create_metric" | "update_metric" | "delete_metric" | "get_goals" | "create_goal" | "update_goal" | "archive_goal" | "restore_goal" | "delete_goal" | "get_goal_alert" | "create_goal_alert" | "update_goal_alert" | "delete_goal_alert") | Yes | What to do — metric defs: 'get_metrics', 'create_metric', 'update_metric', 'delete_metric'; goals: 'get_goals', 'create_goal', 'update_goal', 'archive_goal', 'restore_goal', 'delete_goal'; alerts: 'get_goal_alert', 'create_goal_alert', 'update_goal_alert', 'delete_goal_alert'. | | `endsAt` | integer | No | End of the goal timeframe, as a Unix timestamp in seconds. Must be after startsAt. | | `events` | array | No | Array of event definitions for FORMULA metrics. Each event is referenced by letter (A, B, C...) in the formula. | | `goalId` | string | No | Goal-scoped actions and goal alert actions. | | `formula` | string | No | Formula string for FORMULA metrics. Reference events by letter: A, B, C... Available functions: UNIQUES(A), TOTALS(A), PROPSUM(A), PROPAVG(A), PROPMIN(A), PROPMAX(A), PROPCOUNT(A), PROPCOUNTAVG(A), REVENUETOTAL(A). Example: "TOTALS(B)/TOTALS(A)" | | `metricId` | string | No | update_metric / delete_metric: target metric. get_goals: list goals on one metric. create_goal: metric to attach the goal to. | | `returnOn` | integer | No | Number of days to return on for RETENTION metrics (1–30). | | `startsAt` | integer | No | Start of the goal timeframe, as a Unix timestamp in seconds. | | `confirmed` | boolean | No | update_metric when changing a metric definition with dependents / delete_metric / delete_goal: set true only after the user confirms. | | `metricIds` | array | No | get_metrics: metric IDs to fetch (required for get_metrics). | | `projectId` | string | No | create_metric / update_metric / delete_metric: project ID. get_goals: list all goals in project (mutually exclusive with metricId). | | `rationale` | string | No | Brief explanation of why you are calling this tool and what you expect to learn from the result. | | `comparator` | string ("gte" | "lte") | No | Success direction: "gte" = metric should be at or above targetValue, "lte" = at or below. | | `countGroup` | string | No | What to count. "User" for unique users (default), "Event" for event totals. | | `funnelMode` | string ("ordered" | "unordered" | "sequential") | No | How funnel steps relate: "ordered" (this order), "unordered" (any order), "sequential" (exact order). | | `isOfficial` | boolean | No | Whether to mark this metric as official. Requires elevated permissions. | | `metricType` | string ("UNIQUES" | "TOTALS" | "FORMULA" | "PROPSUM" | "PROPAVG" | "RETENTION" | "CONVERSION") | No | Type of metric. UNIQUES: unique users who performed the event. TOTALS: total event count. FORMULA: custom formula combining multiple events (supports PROPCOUNT, PROPMIN, PROPMAX, etc. as formula terms). PROPSUM: sum of a numeric property. PROPAVG: average of a numeric property. RETENTION: retention metrics. CONVERSION: funnel / multi-step conversion metrics. | | `startEvent` | object | No | Start event definition for RETENTION metrics. | | `description` | string | No | Description of what this metric measures | | `returnEvent` | object | No | Return event definition for RETENTION metrics. | | `targetValue` | number | No | The numeric value the metric should hit over the timeframe. | | `funnelEvents` | array | No | Ordered funnel steps for CONVERSION metrics (minimum 2 events). Each step is an event with optional filters. Not used for FORMULA — use "events" for formula metrics. | | `alertDelivery` | object | No | Full replacement of alert delivery channels. Omit to preserve delivery, pass null to clear all channels, or pass an object containing every desired channel. | | `dipThresholdPct` | integer | No | Metric dip percentage that triggers an alert. Required when shouldAlertOnDip is true. | | `includeArchived` | boolean | No | get_goals: include archived goals when metricId is set. | | `returnOnInterval` | integer | No | 1 is for daily retention, 7 is for weekly retention, 30 is for monthly retention. | | `shouldAlertOnDip` | boolean | No | Send an alert when the metric dips by the configured threshold. | | `conversionSeconds` | integer | No | Maximum time window to complete the funnel, in seconds (e.g. 86400 = 1 day, 604800 = 7 days). | | `isExperimentMetric` | boolean | No | Set to true when this metric is intended for use in an experiment. Enables experiment-specific formula validation rules. | | `aggregationProperty` | object | No | Property to aggregate for PROPSUM and PROPAVG metrics. Specifies which numeric event/user/group property to compute the aggregation on. | | `funnelPathsToCollect` | string ("UNIQUES" | "TOTALS") | No | CONVERSION only: "UNIQUES" measures unique users who complete the funnel; "TOTALS" measures total conversion path counts. | | `funnelComputeProperty` | object | No | CONVERSION only: numeric property on the last funnel step to aggregate (e.g. revenue). Use with funnelComputePropFunction. | | `funnelConstantProperties` | array | No | CONVERSION only: properties held constant across funnel steps (same as funnel "holding constant" in the UI). | | `shouldAlertOnGoalReached` | boolean | No | Send an alert when the goal target is reached. | | `funnelComputePropFunction` | string ("SUM" | "AVG") | No | CONVERSION only: how to aggregate funnelComputeProperty on the last step — "SUM" (default when property set) or "AVG". | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | array | Yes | Array of content blocks returned by the tool | ### Use amp notebooks **Slug:** `AMPLITUDE_MCP_USE_AMP_NOTEBOOKS` Read and manage Amplitude notebooks. One outcome-based tool selected by `action`. ACTIONS: - `get`: read notebooks by `notebookIds` (or singular `notebookId`). Resolve IDs with `search_amp_entities` (entityTypes: NOTEBOOK). - `create`: create a notebook with `name` + `rows`. Chart cells accept saved chart IDs and temporary chart edit IDs interchangeably in `chartId`; edit IDs are saved as permanent charts automatically. - `edit`: update name and/or one layout edit. Call get first and pass its `lastModifiedAt` as `expectedLastModifiedAt`. Rows accept edit IDs the same way `create` does — use this to add a freshly queried chart to an existing notebook. ROW ITEMS: - Types: `chart`, `rich_text` (markdown content), `session_replay`, `video`, `image`, `cohort`. Use `rich_text`, not `markdown`. - Width 3–12 columns per item; row total ≤ 12; max 4 items per row. DO NOT USE FOR: - Finding notebooks by name: use `search`. - Creating a shared space, changing space members, or moving an existing notebook into a space: use `manage_amp_entities`. - Sharing / comments: use `share_amp_entities` / `use_amp_comments`. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `edit` | string | No | Optional single structural layout edit. | | `name` | string | No | Notebook name. | | `rows` | array | No | Notebook layout rows. | | `action` | string ("get" | "create" | "edit") | Yes | Discriminator: determines which set of parameters applies (get | create | edit) | | `metadata` | object | No | Optional metadata updates (e.g. name). | | `notebookId` | string | No | Singular notebook ID alias for notebookIds:[id]. | | `destination` | string | No | Where to save. Omit for the personal space (previous behavior). | | `notebookIds` | array | No | Notebook IDs to read. Resolve with search_amp_entities (entityTypes: ['NOTEBOOK']). | | `expectedLastModifiedAt` | integer | No | lastModifiedAt returned by get. Read the notebook first. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | array | Yes | Array of content blocks returned by the tool | ### Use amp skill **Slug:** `AMPLITUDE_MCP_USE_AMP_SKILL` Load an Amplitude skill — a workflow playbook describing the optimal sequence of Amplitude tools for a task. Consult a skill BEFORE improvising a multi-step Amplitude workflow (analysis, chart or dashboard creation, experiment review, replay debugging, instrumentation). Actions: - list: every available skill with its description. Use to browse what exists, or to find the name of the skill you want. - get: exact skill name or skill:// URI → that skill's full instructions. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `action` | string ("get" | "list") | No | What to do: 'list' everything, or 'get' one skill by name. | | `rationale` | string | No | Brief explanation of why you are calling this tool and what you expect to learn from the result. | | `skillName` | string | No | Exact skill name (e.g. 'analyze-chart') or full skill:// URI. Required when action is 'get'. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | array | Yes | Array of content blocks returned by the tool |