Skip to main content

MCP Server

MGM ships an MCP (Model Context Protocol) server so AI assistants can query your analytics directly.

URL: https://app.mostlygoodmetrics.com/mcp (streamable HTTP)

Connect​

  • Claude Code — install the Claude Code plugin, which connects the server and adds MGM-specific skills.
  • Codex — add the URL as an HTTP MCP server, then install the shared agent skills.
  • claude.ai — add it as a custom connector with the URL above.
  • Any MCP client — the server supports streamable HTTP with OAuth 2.0 (dynamic client registration included).

Authentication is browser-based OAuth: the first time your client calls an MGM tool, you're sent to sign in to Mostly Good Metrics and approve access. No API keys to copy around.

MCP tools provide access to MGM; portable agent skills teach Codex, Claude Code, and compatible agents how to combine those tools into reliable workflows. Install both when you want automatic workflow discovery.

Troubleshooting​

I added MGM, but its tools are not visible​

Most MCP clients discover tools when an agent or task starts. After adding MGM as a new server, start a fresh agent/task (or restart your MCP client) and try again. Completing OAuth alone does not always refresh a running agent's tool list.

Tools​

AreaTools
Account & projectswhoami, list_projects, create_project, list_api_keys, create_api_key, revoke_api_key
Dashboardget_dashboard, get_filters, list_widgets, add_widget, remove_widget, reset_widgets
Eventslist_events, list_event_types, define_event
Funnelslist_funnels, get_funnel, create_funnel, update_funnel, delete_funnel, execute_funnel
Retentionlist_retentions, get_retention, create_retention, update_retention, delete_retention, execute_retention
Querieslist_queries, get_query, create_query, update_query, delete_query, execute_query, query_metrics
Experimentslist_experiments, get_experiment, create_experiment, update_experiment, delete_experiment, start_experiment, stop_experiment

Ad-hoc analysis works without saving anything: execute_funnel, execute_retention, and execute_query all accept inline definitions, so an assistant can answer "where do users drop off between signup and purchase?" in one call.

Every tool describes its own parameters, so an assistant can discover the shape it needs without a round trip. The structured object behind execute_query, create_query, update_query, and query_metrics — metrics, dimensions, date ranges, and the filters object including custom property operators — is written out in full under Query definition.

Query several metrics efficiently​

Use query_metrics when an assistant needs several aggregate answers for the same project. It runs 1–10 independent queries with bounded server-side concurrency without tying up the shared MCP server, so the client makes one MCP call instead of repeatedly calling execute_query.

{
  "project_id": "PROJECT_UUID",
  "queries": [
    {
      "id": "purchases",
      "metric": "count_events",
      "event_filter": ["purchase_completed"],
      "date_range": "30d",
      "compare": "previous_period"
    },
    {
      "id": "active-users",
      "metric": "unique_users",
      "date_range": "30d"
    }
  ]
}

Each result repeats the caller-defined id and has a status. Successful scalar comparisons use equal-length completed periods ending before today, so a partial current day cannot look like a drop. They include current and previous values, absolute change, percentage change when the previous value is nonzero, and the actual current and previous start/end dates. Comparisons are limited to ungrouped scalar queries. For a grouped comparison, send two grouped queries with explicit custom date ranges and compare the returned groups. An invalid analytics definition or unsupported metric returns an error for that item without discarding other results. Missing or duplicate IDs and violations of the 1–10 query batch contract reject the whole call.

The tool is read-only and aggregate-only: it supports count_events, unique_users, unique_sessions, and dau, but does not return raw user IDs. MCP clients receive both a backwards-compatible JSON text result and MCP structuredContent; no MGM-specific client runtime or dashboard change is required.

Each query leg is limited to a 366-day scan, and one query_metrics call is limited to 3,660 day-scans across all queries and comparison legs. This keeps database work and MCP responses bounded; an overloaded server can also reject a batch immediately with a retry-later error. Seasonal month, quarter, and year-over-year ranges are not supported by query_metrics; use execute_query when that shape is needed.

API key safety​

MCP access continues to use OAuth. The project API keys managed by these tools are client-side ingestion credentials used by your SDKs and event API.

create_api_key requires an explicit safety mode. Pass one or more allowed_identifiers to restrict ingestion to specific Apple bundle IDs, Android package names/application IDs, or web domains (recommended), or set unrestricted to true when the key intentionally needs to accept every source. The full key is returned only when it is created; list_api_keys returns prefixes and restriction metadata without exposing raw keys. Use revoke_api_key with both the project and key IDs to disable a key.