Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to the Supermetrics MCP server

Vendor MCP
Open markdown

The Supermetrics MCP connector routes your AI agent's tool calls to Supermetrics's own MCP server through Scalekit. Each user signs in to Supermetrics once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 21 tools.

Tools
21
What they doRead · write · destructive
12 · 9 · 012 read9 write0 destructive
Users sign in with
OAuth app
Scalekit's or your own

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv

  2. Set your credentials

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>

  3. Create the Supermetrics MCP connection

    In AgentKit > Connections, create a Supermetrics MCP connection. The name you give it is the connection_name your code passes. See Configure connections.

    Scalekit credentials are available for Supermetrics MCP server, so you don't need to register an OAuth app. To show your own app on the consent screen, use your own credentials instead.

    Use your own OAuth app

    Supermetrics MCP uses Dynamic Client Registration (DCR) — no client ID or secret is required. The only step is creating a connection in Scalekit and authorizing your Supermetrics account.

    1. Create a connection in Scalekit

      • In the Scalekit dashboard, go to AgentKit → Connections → Create Connection.
      • Search for Supermetrics MCP and click Create.
      • Note the Connection name — use this as connection_name in your code (e.g., supermetricsmcp).

    2. Authorize your Supermetrics account

      Generate an authorization link and open it in a browser to complete the Supermetrics OAuth flow.

      The user is redirected to Supermetrics to sign in and grant access. Scalekit stores the token and injects it automatically into every tool call — no further configuration is needed.

  4. Authorize a user and make your first call

    quickstart.mts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    import { createInterface } from 'node:readline/promises'
    

    const scalekit = new ScalekitClient(
      process.env.SCALEKIT_ENVIRONMENT_URL,
      process.env.SCALEKIT_CLIENT_ID,
      process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    

    const connector = 'supermetricsmcp'
    const identifier = 'user_123'
    

    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize Supermetrics MCP:', link)
    const rl = createInterface({ input: process.stdin, output: process.stdout })
    await rl.question('Press Enter after authorizing...')
    rl.close()
    

    // Make your first call
    const result = await actions.executeTool({
      connector,
      identifier,
      toolName: 'supermetricsmcp_data_source_discovery',
      toolInput: {},
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user signs in once. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • supermetricsmcp_accounts_discoveryList connected ad accounts and profiles for a marketing or advertising data source.Read-only

    Accounts Discovery

    List connected ad accounts and profiles for a marketing or advertising data source.

    Inputs

    ds_idstringrequired
    Data source ID from data_source_discovery (e.g. 'FA', 'AW', 'GAWA')
    compressstring
    Always recommended. Encodes response as compact text, reducing size and token usage. In tables, an empty cell means not set and list values are |-joined.
    filterstring
    Case-insensitive filter against account ID, name, group, tags (comma-separated)
  • supermetricsmcp_campaign_and_resource_getRetrieve campaign details, performance metrics, or related resources from an advertising platform.Read-only

    Campaign And Resource Get

    Retrieve campaign details, performance metrics, or related resources from an advertising platform.

    Inputs

    account_idstringrequired
    Ad account or profile ID for the selected data source.
    ds_idstringrequired
    Data source identifier (e.g. `GA4`, `FA`, `ADWORDS`). Use `data_source_discovery` to list available IDs.
    max_rowsstring
    Maximum number of rows to return.
    paramsstring
    Resource-type-specific parameters. See ResourceParams for which fields apply to each resource_type.
    resource_typestring
    Type of resource to retrieve (e.g. `CAMPAIGN`, `AD_GROUP`).
  • supermetricsmcp_data_queryQuery marketing analytics data from any connected data source, with optional date ranges, field selection, and filters.Read-only

    Data Query

    Query marketing analytics data from any connected data source, with optional date ranges, field selection, and filters.

    Inputs

    ds_idstringrequired
    Data source ID from data_source_discovery (e.g. 'FA', 'AW', 'GAWA')
    compare_end_datestring
    YYYY-MM-DD (when compare_type=custom)
    compare_showstring
    perc_change (default), abs_change, or value
    compare_start_datestring
    YYYY-MM-DD (when compare_type=custom)
    compare_typestring
    prev_range, prev_year, prev_year_weekday, or custom (with compare_start/end_date)
    compressstring
    Always recommended. Returns completed rows as a compact text table whose columns are the requested field IDs.
    date_range_typestring
    A date range is required for nearly all data sources (is_date_range_required=true in data_source_discovery config). Use a relative range: last_7_days, last_30_days, last_90_days, last_month, this_month, yesterday, etc. (append '_inc' to include the current period), or 'custom' with start_date/end_date. Pass as a root-level parameter, NOT inside settings.
    ds_accountsstring
    Account IDs from accounts_discovery, or free-text identifier when is_free_text_account_required=true. Required when has_account_list=true.
    end_datestring
    YYYY-MM-DD. Required when date_range_type=custom.
    fieldsstring
    Field IDs from field_discovery, comma-separated. List dimensions before metrics (e.g. 'date,clicks,cost'); if unsure whether a field is a dimension or metric, check field_discovery. All fields must share a common report_type if the source uses report types.
    filtersstring
    Filter expression: field_name operator value, combined with AND/OR. Operators: ==, !=, >, >=, <, <=, =@ (contains), !@ (not contains), =~ (regex), !~ (not regex), [] (in list). Example: "country == US AND clicks > 100"
    freshstring
    Skip stored results and run the query again. Use only to confirm a change right after a write, e.g. a budget or status update; it is slower and uses more quota. Only for campaign management data sources (e.g. Facebook Ads, Google Ads). Not available with API keys or for every client; the result notes say when it was not applied.
    max_rowsstring
    Max rows to return (default 1000). Higher values may be capped by your license.
    settingsstring
    Data source settings from data_source_discovery as a JSON object. Include report_type and all setting_ids here.
    start_datestring
    YYYY-MM-DD. Required when date_range_type=custom.
    timezonestring
    IANA timezone (e.g. 'America/New_York'). Default: UTC.
  • supermetricsmcp_data_source_discoveryList all available marketing and advertising data sources supported by Supermetrics.Read-only

    Data Source Discovery

    List all available marketing and advertising data sources supported by Supermetrics.

    Inputs

    compressstring
    Always recommended. Encodes response as compact text, reducing size and token usage.
    ds_idstring
    When provided, returns full config for this source. Omit to list all.
    filterstring
    Case-insensitive filter against ID, name, categories (e.g. 'ads,social')
  • supermetricsmcp_field_discoveryList available metrics and dimensions for a specific data source.Read-only

    Field Discovery

    List available metrics and dimensions for a specific data source. Returns field names usable in `data_query`.

    Inputs

    ds_idstringrequired
    Data source ID from data_source_discovery (e.g. 'FA', 'AW', 'GAWA')
    compressstring
    Always recommended. Encodes response as compact text, reducing size and token usage. In tables, an empty cell means not set and list values are |-joined.
    filterstring
    Case-insensitive filter against field ID, name, description, type, alias or report type. Comma-separated list of terms, e.g. 'click,impression'.
  • supermetricsmcp_get_async_query_resultsRetrieve results of an async `data_query` using the schedule ID returned by that query.Read-only

    Get Async Query Results

    Retrieve results of an async `data_query` using the schedule ID returned by that query.

    Inputs

    schedule_idstringrequired
    Schedule ID returned by `data_query` for async result retrieval.
    compressstring
    Whether to compress the response payload.
  • supermetricsmcp_get_business_contextRetrieve the durable business context a team has saved — guidelines, policies, and preferences — so analysis and changes follow them.Read-only

    Get Business Context

    Retrieve the durable business context a team has saved — guidelines, policies, and preferences — so analysis and changes follow them. Context is stored at three scopes, each read independently (a read returns one scope's entries, not a merge): - **Team** — applies everywhere (e.g. "report currency in EUR"). - **Data source** — a specific platform (e.g. "for Meta, break out Advantage+ separately"). - **Account** — a specific account (e.g. "this client reports last-click only"). Choose the scope with the ids: no ids → team level; `ds_id` → that data source's level; `ds_id`+`account_id` → that account's level. `tags` filters by category — a record matches if it carries **any** of the tags you pass (OR), and commas are just separators, so `tags: ["a,b"]` and `["a","b"]` both match records tagged a or b. Omit `tags` to read all entries at the scope; `tags` with no ids searches across all scopes, so a tag lookup isn't confined to one level. Results are grouped as `team`/`data_source`/`account` (empty omitted); a single-source data-source list is keyed `data_source:<ds_id>`. Prefer what the discovery tools already surface: `data_source_discovery` and `accounts_discovery` include team- and data-source-level context, and a narrowed `accounts_discovery` inlines an account's own context. Call this for a scope a discovery response did not cover — e.g. an account you are about to act on — to read tags whose context was too large to inline, or to re-read after a save.

    Inputs

    account_idstring
    Account ID; requires ds_id; scopes to account level
    ds_idstring
    Data source code (e.g. AW, FA); scopes to data-source level
    tagsstring
    Categories, comma-separated or JSON array, to filter by — a record matches any of them (OR). Omit to read every entry at the scope; with no ds_id/account_id, a tag lookup searches all scopes
  • supermetricsmcp_get_dashboardsRead Supermetrics Studio dashboards: 'list' the dashboards the user owns or has been shared with (metadata only, no code, newest first; optional 'filter' narrows by id, title, description or tag, and 'limit'/'offset' paginate — the response carries 'total'), 'get' one dashboard's source code and metadata by ID, or 'changelog' its version history.Read-only

    Get Dashboards

    Read Supermetrics Studio dashboards: 'list' the dashboards the user owns or has been shared with (metadata only, no code, newest first; optional 'filter' narrows by id, title, description or tag, and 'limit'/'offset' paginate — the response carries 'total'), 'get' one dashboard's source code and metadata by ID, or 'changelog' its version history. Load the current code with 'get' before editing.

    Inputs

    actionstringrequired
    'get' to retrieve a dashboard's source code and metadata by ID, 'changelog' to view its version history, 'list' to list the dashboards the user owns or has been shared with (metadata only, no code)one of getchangeloglist
    dashboard_idstring
    UUID of the dashboard. Required for 'get' and 'changelog'
    filterstring
    'list' only: narrow by id, title, description, or tag (case-insensitive substring)
    limitstring
    'list' only: page size (max 500)
    offsetstring
    'list' only: rows to skip for pagination

Workflows

Discover available data sources

Use supermetricsmcp_data_source_discovery to list all marketing and advertising data sources connected to the user’s Supermetrics account.

const sources = await actions.executeTool({
  connector: 'supermetricsmcp',
  identifier: 'user_123',
  toolName: 'supermetricsmcp_data_source_discovery',
  toolInput: {},
});
console.log(sources);

Query marketing analytics data

Use supermetricsmcp_data_query to pull structured metrics and dimensions from a connected data source. Call field_discovery first to find valid field names, and get_today to resolve relative date references.

const report = await actions.executeTool({
  connector: 'supermetricsmcp',
  identifier: 'user_123',
  toolName: 'supermetricsmcp_data_query',
  toolInput: {
    ds_id: 'GA4',
    fields: ['Sessions', 'Conversions', 'Date'],
    date_range_type: 'last_30_days',
    max_rows: 100,
  },
});
console.log(report);

Create an ad campaign

Use supermetricsmcp_campaign_create to create a new advertising campaign on a supported platform. Call accounts_discovery first to find the correct account ID.

const campaign = await actions.executeTool({
  connector: 'supermetricsmcp',
  identifier: 'user_123',
  toolName: 'supermetricsmcp_campaign_create',
  toolInput: {
    ds_id: 'FA',
    account_id: 'act_123456789',
    name: 'Q1 Brand Awareness',
    status: 'PAUSED',
    budget_amount: '50.00',
    budget_type: 'DAILY',
  },
});
console.log(campaign);
All 95 in Marketing