Amplitude MCP lets you query and create Amplitude content (charts, dashboards, experiments, cohorts) by talking to an AI client like Cursor, Claude, or ChatGPT. Use it when you want natural-language access to product data without writing SQL or clicking through the Amplitude UI. Pick your client below to set it up in about two minutes. Available to any existing Amplitude customer. You must use a code editor or application that supports MCP servers (for example, Cursor, Claude Code, ChatGPT, Lovable, or Kiro). The [official MCP servers registry](https://github.com/modelcontextprotocol/servers) on GitHub lists the Amplitude MCP server. You can also find MCP integration guides and examples in [Anthropic's Claude documentation](https://docs.anthropic.com/en/docs/build-with-claude/mcp), the [MCP quickstart resources](https://github.com/modelcontextprotocol/quickstart-resources), and [Cursor's MCP documentation](https://docs.cursor.com/context/model-context-protocol). ## What the MCP is for Use the Amplitude MCP for these jobs: - Search and read Amplitude content: charts, dashboards, notebooks, experiments, cohorts, events, and properties. - Query analytics, run ad-hoc segmentation, funnels, and retention, and analyze experiment results. - Manage taxonomy: events, properties, transformations, group types, and tracking-plan branches. - Create and edit objects: charts, dashboards, notebooks, experiments, cohorts, feature flags, and metrics. Don't use the Amplitude MCP for these jobs: - Sending production or high-volume event data. The MCP isn't an ingestion endpoint. Emit events with an [Amplitude SDK](/docs/sdks) or the [HTTP V2 API](/docs/apis/analytics/http-v2). The `create_events` tool registers event definitions in the tracking plan; it doesn't stream event data. - Reading public documentation in an AI client. Use the read-only [Docs MCP server](/docs/amplitude-ai/docs-mcp-server) instead. ### Choose an interface for AI agents When you build an AI agent that integrates with Amplitude, match each job to the right interface: | Job | Use | Why | | ----------------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------- | | Emit event data (production or high volume) | [SDK](/docs/sdks) or [HTTP V2 API](/docs/apis/analytics/http-v2) | The ingestion path. The MCP doesn't ingest events. | | Validate taxonomy, projects, and queries | Amplitude MCP | Read, search, query, and tracking-plan tools. | | Create or edit objects (dashboards, experiments, cohorts, charts) | Amplitude MCP tools, or [REST APIs](/docs/apis) in automation | MCP for conversational workflows, REST APIs for scripted pipelines. | | Read public docs in an AI client | [Docs MCP server](/docs/amplitude-ai/docs-mcp-server) | Read-only and unauthenticated. | | Anything the interfaces above don't cover | Browser UI | Use the Amplitude UI for the remaining gaps. | ## Remote server ## Regions | Region | MCP Server URL | | ------------------------------ | ---------------------------------- | | United States Server (Default) | `https://mcp.amplitude.com/mcp` | | EU Residency Server | `https://mcp.eu.amplitude.com/mcp` | Use the Standard Server URL unless your Amplitude data resides in the EU region. ## Available tools and capabilities The Amplitude MCP provides comprehensive access to your analytics through these tools: {% accordion title="Available tools" %} **Discovery and context** | Tool Name | Description | | ----------------------- | ---------------------------------------------------------------------------------------------------------------- | | `search` | Search for charts, dashboards, notebooks, experiments, events, properties, cohorts, and other Amplitude content. | | `get_from_url` | Retrieve the full object definition from any Amplitude URL, including charts, dashboards, and experiments. | | `get_context` | Get information about the current user, organization, and accessible projects. | | `get_project_context` | Get project-specific settings including time zone, currency, session definition, and AI context. | | `get_workspace_context` | Get settings information about a Data project or portfolio. | **Content retrieval** | Tool Name | Description | | ------------------- | --------------------------------------------------------------------------------------- | | `get_charts` | Retrieve full chart definitions by ID, including events, properties, and configuration. | | `get_dashboard` | Retrieve dashboards and all their charts, including chart IDs for individual queries. | | `get_cohorts` | Retrieve cohort definitions by ID, including audience criteria and metadata. | | `get_experiments` | Retrieve experiments by ID with state, variant configuration, and decision details. | | `get_users` | Retrieve user data from a project. | | `get_flags` | Retrieve feature flag definitions by ID, including variants and configuration. | | `get_deployments` | Retrieve all deployments (API keys for flags and experiments) for a project. | | `get_agent_results` | Retrieve results from AI agents that analyzed your dashboards or session replays. | **Taxonomy: Events and properties** These tools read and update the events, properties, custom and labeled events, transformations, and group types in your tracking plan. | Tool Name | Description | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `get_events` | Retrieve events from a project, with filtering by event type, a result limit, and cursor pagination. | | `get_properties` | Retrieve properties from a project's taxonomy. Use `propertyType` to select event, user, group, derived, or other property kinds. | | `update_properties` | Update a property's description, category, name, or official status. Use `propertyType` to select the kind of property to update. | | `get_custom_or_labeled_events` | Retrieve custom events, labeled (autotrack) events, or both, with optional filtering by ID or name, a result limit, and pagination. | | `update_custom_or_labeled_events` | Update the description, category, name, official status, or definition (source events and filters) of custom or labeled events. | | `update_event` | Update an event's metadata, including its name, description, category, and official status. | | `get_transformations` | Retrieve data transformations from a project. Transformations clean data by merging events, merging properties, or mapping property values. | | `get_group_types` | List a project's group types, the categories of groups, such as Company, Team, or Account. | **Session Replay** | Tool Name | Description | | --------------------------- | ---------------------------------------------------------------------------------------- | | `get_session_replays` | Search for session replays from the last 30 days, filtered by user properties or events. | | `list_session_replays` | List session replays with simple time-range pagination. | | `get_session_replay_events` | Retrieve processed interaction timelines from a session replay recording. | **Query and analysis** | Tool Name | Description | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `query_chart` | Query a single chart by ID and return its data. | | `query_charts` | Query up to three charts concurrently by ID and return their data. | | `query_amplitude_data` | Execute ad-hoc analytics queries for event segmentation, funnels, retention, and more using a two-mode discover/execute workflow. | | `query_experiment` | Query experiment analysis data, including variant performance and statistical significance. | | `render_chart` | Render a visual, interactive Amplitude chart from a query definition and return a chart edit URL. | **Creation** | Tool Name | Description | | --------------------- | ------------------------------------------------------------------------------------------- | | `save_chart_edits` | Save edits to existing charts or convert temporary chart edits into permanent saved charts. | | `create_dashboard` | Create dashboards with charts, rich text, and custom layouts. | | `create_notebook` | Create interactive notebooks with charts, rich text, and multi-column layouts. | | `create_experiment` | Create A/B test experiments across one or more projects with custom variants and metrics. | | `create_cohort` | Create cohorts based on user properties and behaviors. | | `create_flags` | Create multiple feature flags in batch. | | `create_metric` | Create reusable metrics (KPIs) for use in experiments or dashboards. | | `create_events` | Create new events or add ingested unexpected events to a project's tracking plan. | | `create_custom_event` | Create a custom event composed of one or more source events with optional filters. | | `create_properties` | Create event, user, or group properties in a project's tracking plan. | **Cohort sync** | Tool Name | Description | | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `get_cohort_sync_destinations` | List cohort sync destinations configured for a project. | | `get_cohort_syncs` | List cohort syncs and their destination, cadence, and status. | | `get_cohort_sync_history` | Retrieve sync history for a cohort sync, including added, removed, and skipped users. | | `sync_cohort` | Trigger a one-time cohort sync to a destination such as Braze, Iterable, S3, or a webhook. The tool previews the export and asks for confirmation before sending. | **Taxonomy: Branches** | Tool Name | Description | | ---------------- | ------------------------------------------------------------------------------ | | `get_branches` | List all branches in a project's tracking plan, including the main branch. | | `create_branch` | Create a new branch in a project's tracking plan, forked from the main branch. | | `update_branch` | Update the description of a branch in a project's tracking plan. | | `refresh_branch` | Pull the latest changes from main into a feature branch. | | `merge_branch` | Merge a branch into the main branch. | | `delete_branch` | Permanently delete a branch and all its uncommitted tracking plan changes. | **Editing and updates** | Tool Name | Description | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `edit_dashboard` | Edit an existing dashboard's metadata (title, description) and layout (add charts, remove charts, reorder sections) with optimistic concurrency protection to prevent conflicting edits. | | `edit_notebook` | Edit an existing notebook's metadata (title, description) and layout (add or remove charts, text blocks, and other content sections) with optimistic concurrency protection. | | `update_experiment` | Set or replace metrics on an experiment. | | `update_flag` | Update a feature flag or experiment's metadata, variants, testers, and deployments. | **Guides and Surveys** | Tool Name | Description | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `list_guides_surveys` | List guides and surveys in a project, with filters by type, platform, creator, date range, and archived status. Returns status, priority, and creator metadata for each item. | | `get_guide_or_survey` | Retrieve full details for a single guide or survey by ID, including status, priority, variants, step content, page targeting rules, and trigger configuration. | **Feedback** | Tool Name | Description | | ----------------------- | ---------------------------------------------------------------------------------------------------------------- | | `get_feedback_insights` | Retrieve processed feedback themes grouped by type: feature requests, bugs, complaints, praise, and pain points. | | `get_feedback_comments` | Retrieve raw feedback comments from connected sources with search and pagination. | | `get_feedback_mentions` | Retrieve individual user feedback comments associated with a specific insight. | | `get_feedback_sources` | Retrieve connected feedback integrations and their source IDs for filtering. | | `get_feedback_trends` | Get saved customer feedback trends tracked over time. | **Agent analytics** | Tool Name | Description | | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | `query_agent_analytics_metrics` | Aggregate quality, cost, performance, error, and trend metrics across AI agent sessions. | | `query_agent_analytics_sessions` | List and filter AI agent sessions by quality, cost, sentiment, user, topic, or agent with optional `groupBy` aggregation. | | `query_agent_analytics_spans` | Inspect individual operations (LLM calls, tool invocations) within AI agent traces for latency and error analysis. | | `get_agent_analytics_conversation` | Retrieve the full conversation transcript for an AI agent session. | | `search_agent_analytics_conversations` | Full-text search across AI agent conversation content for specific keywords or topics. | | `get_agent_analytics_schema` | Discover available fields, rubric definitions, and filter values (agent names, tools, topics) for agent analytics queries. | {% /accordion %} ## Progressive tool discovery If you connect to Amplitude MCP manually and want to reduce token spend, add `?discovery=progressive` to the MCP URL to enable progressive tool discovery. **Progressive URLs (copy/paste):** - US: `https://mcp.amplitude.com/mcp?discovery=progressive`. - EU: `https://mcp.eu.amplitude.com/mcp?discovery=progressive`. In this mode, the initial tool list is intentionally small. The server discovers tools on demand, and all supported tools remain callable after discovery. Use this workflow: 1. Call `get_context` to confirm organization and project access. 2. Call `list_tool_categories` to see available product surfaces. 3. Call `get_category_tools` with a category name to discover tools in that surface. 4. Call `describe_tool` for any tool you plan to call so you have the latest schema and required parameters. 5. Call the tool directly once you confirm the schema. {% callout type="note" %} In progressive mode, `tools/list` returns discovery tools plus `get_context` first. Use category discovery and `describe_tool` to find schemas before calling specific tools. {% /callout %} ### Example progressive discovery flow Use this sequence in your MCP client conversation: 1. "Run `get_context` and pick the right project." 2. "Run `list_tool_categories` and show which categories are available." 3. "For the `analytics` category, run `get_category_tools`." 4. "For `query_chart`, run `describe_tool` and then call it with valid parameters." ## Connect Amplitude MCP to your AI client Select your client to open its setup guide. {% card-grid columns="3" %} {% card kind="quickstart-link" title="Claude Code" href="/docs/amplitude-ai/amplitude-mcp/claude-code" icon="anthropic" tone="blue" %} Terminal-based AI workflow with Claude Code CLI. {% /card %} {% card kind="quickstart-link" title="Cursor" href="/docs/amplitude-ai/amplitude-mcp/cursor" icon="cursor" tone="blue" %} AI panel inside the Cursor editor, with one-click install available. {% /card %} {% card kind="quickstart-link" title="ChatGPT" href="/docs/amplitude-ai/amplitude-mcp/chatgpt" icon="openai" tone="blue" %} Browser or desktop ChatGPT with developer mode. {% /card %} {% card kind="quickstart-link" title="Claude" href="/docs/amplitude-ai/amplitude-mcp/claude" icon="claude" tone="blue" %} Claude.ai web or desktop app using a custom connector. {% /card %} {% card kind="quickstart-link" title="Gemini CLI" href="/docs/amplitude-ai/amplitude-mcp/gemini-cli" icon="googlegemini" tone="blue" %} Google Gemini CLI terminal workflow. {% /card %} {% card kind="quickstart-link" title="Replit" href="/docs/amplitude-ai/amplitude-mcp/replit" icon="replit" tone="blue" %} Replit workspace AI, with one-click install available. {% /card %} {% card kind="quickstart-link" title="Lovable" href="/docs/amplitude-ai/amplitude-mcp/lovable" icon="lovable" tone="blue" %} Lovable AI chat for product builders. {% /card %} {% card kind="quickstart-link" title="Figma Make" href="/docs/amplitude-ai/amplitude-mcp/figma-make" icon="figma" tone="blue" %} Figma Make connector for design workflows. {% /card %} {% card kind="quickstart-link" title="Kiro" href="/docs/amplitude-ai/amplitude-mcp/kiro" icon="kiro" tone="blue" %} Kiro IDE with user or workspace scope. {% /card %} {% card kind="quickstart-link" title="Codex CLI" href="/docs/amplitude-ai/amplitude-mcp/codex-cli" icon="codex" tone="blue" %} OpenAI Codex CLI terminal workflow. {% /card %} {% card kind="quickstart-link" title="Other clients" href="/docs/amplitude-ai/amplitude-mcp/other-clients" icon="⌁" tone="neutral" %} Any MCP-compatible client that supports HTTP and OAuth. {% /card %} {% /card-grid %} ## Query examples ### Analytics and charts > What were the daily active users over the last 7 days? > Show signup conversion rates by traffic source this month. > Create a chart showing weekly active users broken down by platform. > Why did this metric spike last week? [paste chart URL] ### Dashboards and notebooks > Build an executive dashboard for our product launch. > Summarize this dashboard for my exec meeting. [paste dashboard URL] > Add a retention chart to the KPI dashboard. > Remove the DAU chart from the overview dashboard. > Update the title of the KPI notebook to "Q2 Growth Metrics". > Move the funnel chart to the top of the onboarding dashboard and add a section header above it. ### Experiments and feature flags > Create an experiment to test the new checkout flow with a 50/50 split. > Should we ship the new onboarding experiment? Analyze the results. > Check on all running experiments — flag anything stale or missing metrics. > Create a feature flag for the redesigned settings page. ### Session Replay and debugging > Show me session replays where users rage-clicked on the checkout page. > A user reported a bug on the billing page. Find their session and walk me through what happened. > Audit the onboarding flow for UX friction using session replays. ### Feedback and opportunities > What are the top customer complaints this month? > How has feedback about the mobile app trended over the last 90 days? > Find me the biggest product opportunities — where are we losing users? ### AI agent analytics > How are our AI agents performing? Show quality, cost, and error rates. > What topics are users asking the AI assistant about? > Investigate the low-quality AI sessions from yesterday — what went wrong? ### Taxonomy and tracking plan > What branches exist in my project? > Create a branch called "q3-cleanup" for tracking plan changes. > Create an event called "Checkout Started" on the q3-cleanup branch. > Add unexpected events "app_opened" and "checkout_completed" to the tracking plan. > Create a user property called "plan_type" for my project. > Merge the q3-cleanup branch into main. ### Guides and Surveys > What are the published guides with the highest priority in my project? > Which guides are live on the pricing page right now? > Show me the full targeting and trigger configuration for guide 15731. ### Users, cohorts, and metrics > Create a cohort of power users who completed 10+ sessions in the last 30 days. > Create a "revenue per user" metric for the checkout experiment. > Compare user behavior between converters and drop-offs in the onboarding flow. > Sync my "High-intent buyers" cohort to Iterable. ## Typical workflows ### Analysis workflow Most analysis questions follow this pattern: 1. **Search**: Find relevant charts, dashboards, or experiments. 2. **Retrieve**: Get full definitions and metadata. 3. **Query**: Execute data queries and return results. 4. **Analyze**: Ask follow-up questions and dive deeper. Example conversation: > **You:** Why did weekly active users drop last Tuesday? > **AI:** [Searches for WAU charts, queries the data, identifies the drop] > **AI:** Looks like WAU dropped 12% on Tuesday. Let me check if any experiments or deployments landed that day. > **AI:** [Cross-references deployments and experiment launches] > **AI:** A deployment shipped Monday evening that changed the session timeout. That likely caused the drop. > **You:** Show me session replays from affected users. > **AI:** [Finds replays, extracts interaction timelines, summarizes friction patterns] ### Creation and editing workflow You can create and edit Amplitude content directly through conversation: 1. **Create**: Build new charts, dashboards, notebooks, experiments, cohorts, flags, or metrics. 2. **Configure**: Specify parameters and settings conversationally. 3. **Refine**: Edit and adjust layouts, metrics, or variants. For dashboards and notebooks, use `edit_dashboard` or `edit_notebook` to add or remove charts, reorder content, and update metadata. 4. **Deploy**: Save and use the content in Amplitude. Example conversation: > **You:** Set up an A/B test for the new pricing page. > **AI:** [Creates a "revenue per user" metric and a "checkout completion" guardrail metric] > **AI:** [Creates the experiment with control and variant, attaches both metrics] > **You:** Add the product team as testers so they can preview it. > **AI:** [Updates the flag with testers for the variant] > **You:** Build a dashboard so we can monitor results. > **AI:** [Creates a dashboard with experiment results, conversion funnel, and revenue charts] ## Plugins The [Amplitude MCP Marketplace](https://github.com/amplitude/mcp-marketplace/tree/main) is the official open-source plugin repository for Amplitude MCP. It provides a curated set of reusable skills, agents, and commands that extend what you can do with the Amplitude MCP server in Claude Code, Cursor, Claude, and Codex. ### Install the plugin ```bash # Add the Amplitude marketplace (one-time) /plugin marketplace add amplitude/mcp-marketplace # Install the plugin /plugin install amplitude@amplitude ``` ### Available skills The skills table uses seven areas: core analytics, product insights, session replay and debugging, AI agent analytics, analytics instrumentation, briefings, and bonus. #### Core analytics | Skill | Description | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | **create-chart** | Create Amplitude charts from natural language, with automatic event discovery, filters, groupings, and visualization. | | **create-dashboard** | Build dashboards from requirements or goals, organizing charts into logical sections with appropriate layouts. | | **analyze-chart** | Analyze a specific chart in depth to explain trends, anomalies, and likely drivers. | | **analyze-dashboard** | Synthesize an entire dashboard into talking points, surface concerns, and connect quantitative data to qualitative insights. | #### Product insights | Skill | Description | | -------------------------- | --------------------------------------------------------------------------------------------------------- | | **analyze-experiment** | Design A/B tests, monitor running experiments, and interpret results with statistical rigor. | | **monitor-experiments** | Triage all active and recently completed experiments by importance. | | **analyze-feedback** | Synthesize customer feedback into grouped themes such as feature requests, bugs, pain points, and praise. | | **analyze-account-health** | Summarize B2B account health with usage patterns, risk signals, and expansion opportunities. | | **discover-opportunities** | Find product opportunities by cross-referencing analytics, experiments, replays, and feedback. | | **compare-user-journeys** | Compare two user groups side-by-side to surface behavioral differences. | #### Session Replay and debugging | Skill | Description | | ----------------------- | ----------------------------------------------------------------------------------------------------------------- | | **debug-replay** | Turn bug reports into numbered reproduction steps by extracting the interaction timeline from Session Replay. | | **replay-ux-audit** | Watch multiple session replays for a flow and synthesize a ranked friction map. | | **diagnose-errors** | Triage product issues across network failures, JavaScript errors, and error clicks. | | **monitor-reliability** | Generate a proactive reliability report from auto-captured error data so issues surface before users report them. | #### AI agent analytics | Skill | Description | | -------------------------- | ------------------------------------------------------------------------------------------------------------- | | **analyze-ai-topics** | Analyze what users ask AI agents about and how well each topic is answered. | | **investigate-ai-session** | Deep-dive specific AI agent sessions or failure patterns for root-cause analysis. | | **monitor-ai-quality** | Deliver a proactive health report on AI agents covering quality, cost, performance, and errors. | | **review-agent-insights** | Retrieve, synthesize, and prioritize all recent AI agent results across agent types into a unified narrative. | #### Analytics instrumentation | Skill | Description | | --------------------------------- | ---------------------------------------------------------------------------------------------------------- | | **diff-intake** | Read a PR or branch diff and output a structured change brief for analytics planning. | | **discover-event-surfaces** | List candidate analytics events from a change brief for PM prioritization. | | **discover-analytics-patterns** | Map how analytics is already implemented in the codebase (SDK calls, naming, imports). | | **instrument-events** | Build a concrete instrumentation plan and JSON tracking plan from prioritized event candidates. | | **add-analytics-instrumentation** | End-to-end workflow: read code, decide what to track, and produce a full instrumentation plan in one pass. | A typical flow runs `diff-intake` → `discover-event-surfaces` → `instrument-events`, with `discover-analytics-patterns` to align new tracking with existing conventions. #### Briefings | Skill | Description | | ---------------- | ------------------------------------------------------------------------------ | | **daily-brief** | Morning briefing of the most important changes across your Amplitude instance. | | **weekly-brief** | Weekly recap of trends, wins, and risks to share with your team or leadership. | #### Bonus | Skill | Description | | ----------------------- | ------------------------------------------------------------------------------------------------------------------ | | **taxonomy** | Generate, validate, audit, and score event tracking plans, naming conventions, and data governance best practices. | | **what-would-lenny-do** | Answer product strategy questions by searching Lenny Rachitsky's archive (requires `lennysdata` MCP server). | Skills activate automatically based on your request. For example, asking "Why did this metric spike last week?" triggers the `analyze-chart` skill, and asking "Summarize this dashboard for my exec meeting" triggers `analyze-dashboard`. ## Security and compliance ### Data access - The MCP server uses your existing Amplitude user permissions and access controls. - You can only access Amplitude projects and data that you already have permission to view in your regular Amplitude account. - You receive no additional data access beyond your current Amplitude account privileges. - OAuth authentication ensures secure connection between the MCP server and your Amplitude account. ### Privacy considerations The AI service you're using (for example, Claude or Gemini) processes your Amplitude data. Review your organization's policies regarding AI-powered data analysis tools and consider compliance requirements (General Data Protection Regulation, California Consumer Privacy Act). Third parties (for example, Anthropic) develop and maintain the AI models used with this MCP server. Amplitude isn't responsible for model outputs, including hallucinations, inaccuracies, or errors resulting from model behavior, even if such outputs use your Amplitude data. ### Admin controls MCP server access is **enabled by default** for all users in your organization. Organization administrators can opt out or restrict access if needed: 1. Navigate to _Settings > Content Access > MCP_ in your Amplitude organization settings. 2. Use the content access controls to allow or block the Amplitude MCP server. 3. Access restrictions apply to all MCP clients across all users in your organization. {% callout type="note" %} MCP access controls are an admin-only setting. Individual users can't override organization-level MCP restrictions. {% /callout %} ### Scope MCP access with roles For finer-grained control than the org-level toggle, two RBAC actions govern what the MCP server can do on a per-project basis: **Use MCP (read)** (`USE_MCP_READ`) and **Use MCP (write)** (`USE_MCP_WRITE`). Assign these actions to a role, then attach the role to users, groups, or service accounts to scope exactly what an agent can read from or write to. - **Project-level control**: restrict a role to read-only or no access on specific projects. An agent running as that user can't write to, or even read from, projects where the role doesn't grant the action. - **Groups and service accounts**: the same actions apply to permission groups and to Amplitude MCP service accounts, so team-wide policies and automated agent workflows get the same controls as individual users. - **Mixed access**: within a single session, a tool call such as `get_events` succeeds for a project where your role grants read access and fails for a project where it doesn't. - **Applies to everyone**: these actions override admin status. If a role doesn't grant the action, MCP calls fail even for an org administrator. - **Enabled by default**: existing roles already include these actions. Every role grants read access, and the Member, Manager, and Admin roles also grant write access, so nothing changes until an admin adjusts a role. To scope MCP access with a role: 1. In _Org Settings > Role Management_, create or edit a role. 2. In the **AI Features** category, enable **Use MCP (read)** and **Use MCP (write)**. 3. Assign the role to a user, group, or service account, scoped to the relevant projects. Amplitude enforces these actions on each MCP tool call, project by project. The tool list stays visible to all clients, so a call to a tool the role doesn't permit fails at call time rather than disappearing from the list. ## Troubleshooting ### Common issues **Authentication and OAuth issues** - Ensure your Amplitude account has proper project access. - Check that you have logged into the correct Amplitude account. - Make sure you're only logged into one Amplitude organization during the OAuth flow. Logging into multiple organizations can cause authentication issues. - Try disconnecting the MCP connection and re-authenticating through the OAuth flow. - Try logging out of Amplitude, then reconnecting. - Desktop apps may require restart after configuration changes. - Authorization page may appear to spin indefinitely (close tab after authentication). **Missing data** - Verify you have access to the specific Amplitude project. - Check if the data exists in your Amplitude interface. - Ensure proper permissions for the requested data. **Chart query issues** - AI platforms may truncate some large charts. - Querying charts from dashboards may use default chart settings instead of saved dashboard filters. **MCP client issues** - **Cursor tool call failures**: If MCP tool calls fail in Cursor, this is often due to expired or corrupted authentication tokens. Open the Command Palette (`Cmd+Shift+P` on Mac, `Ctrl+Shift+P` on Windows/Linux), type and select "Clear All MCP Tokens," then re-authenticate with your accounts. - **Token limit errors**: If you receive token limit exceeded errors, try starting a new conversation thread or increase the maximum token limit in your MCP client settings. - **Connection timeouts**: If queries are timing out, try breaking down complex requests into smaller, more focused questions. - **Tool loading failures**: If tools aren't loading, restart your MCP client application and re-authenticate. ### Getting help If you encounter issues not covered here: 1. Verify your setup matches the configuration examples. 2. Test with a simple query like "What Amplitude projects are accessible?" 3. Check that your Amplitude account has the necessary permissions. 4. Contact your Amplitude administrator for organization-specific setup help. ## Send feedback Amplitude is constantly improving the Amplitude MCP server and would appreciate hearing from you. Share your feedback, suggestions, or report issues using this [feedback form](https://docs.google.com/forms/d/e/1FAIpQLSeFgRd8607Y2Gzidva5ChEri2tk7wvl7vofUIwxcM_2aD2Nqw/viewform?usp=header). ## Technical specifications **Transport Type:** Streaming HTTP (Remote). **Authentication:** OAuth 2.0 with Amplitude.