Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to the X Ads MCP server

Vendor MCP
Open markdown

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

Tools
74
What they doRead · write · destructive
40 · 23 · 1140 read23 write11 destructive
Users sign in with
OAuth app
Your own X Ads MCP server app

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 X Ads connection

    In AgentKit > Connections, create a X Ads connection and copy its redirect URI. The name you give it is the connection_name your code passes. See Configure connections.

  4. Register an OAuth app

    X Ads MCP server connections use your own OAuth app. Register one with X Ads MCP server and add the redirect URI you copied.

    Then enter the app's Client ID and Client Secret on the X Ads connection.

  5. 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 = 'xadsmcp'
    const identifier = 'user_123'
    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize X Ads:', 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: 'xadsmcp_list_ads_accounts',
    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
  • xadsmcp_estimate_audienceEstimate the audience size for a set of targeting criteria (JSON body of targeting criterion objects)Read-only

    Estimate Audience

    Estimate the audience size for a set of targeting criteria (JSON body of targeting criterion objects)

    Inputs

    account_idstringrequired
    The ID of the ads account.
    targeting_criteriaarrayrequired
    Targeting criterion objects to size. Each also carries a targeting_value whose JSON type varies b...
  • xadsmcp_get_account_mediaGet a single account media object by IDRead-only

    Get Account Media

    Get a single account media object by ID

    Inputs

    account_idstringrequired
    The ID of the ads account.
    account_media_idstringrequired
    The ID of the account media item.
    with_deletedboolean
    Include the record even if soft-deleted (default false).
  • xadsmcp_get_account_statsGet synchronous analytics (impressions, engagements, spend) for an ads accountRead-only

    Get Account Stats

    Get synchronous analytics (impressions, engagements, spend) for an ads account

    Inputs

    account_idstringrequired
    The ID of the ads account.
    end_timestringrequired
    ISO 8601 end of the metrics window (exclusive).
    entitystringrequired
    Entity type to fetch metrics for.one of ACCOUNTCAMPAIGNFUNDING_INSTRUMENTLINE_ITEMMEDIA_CREATIVEPROMOTED_ACCOUNTPROMOTED_TWEETORGANIC_TWEET
    entity_idsstringrequired
    Comma-separated IDs of the entities to fetch metrics for (max 20).
    granularitystringrequired
    Granularity of the returned time series.one of DAYHOURTOTAL
    metric_groupsstringrequired
    Comma-separated metric groups, e.g. ENGAGEMENT,BILLING,VIDEO (max 10; MOBILE_CONVERSION groups mu...
    placementstringrequired
    Placement to scope the metrics to.one of ALL_ON_TWITTERPUBLISHER_NETWORK
    start_timestringrequired
    ISO 8601 start of the metrics window, e.g. 2026-07-01T00:00:00Z.
  • xadsmcp_get_active_entitiesList which ads entities had metrics change in a time window (use before requesting account stats)Read-only

    Get Active Entities

    List which ads entities had metrics change in a time window (use before requesting account stats)

    Inputs

    account_idstringrequired
    The ID of the ads account.
    end_timestringrequired
    ISO 8601 end of the activity window (exclusive); must be a whole hour (minutes and seconds 0).
    entitystringrequired
    Entity type to check for metric activity.one of CAMPAIGNFUNDING_INSTRUMENTLINE_ITEMMEDIA_CREATIVEPROMOTED_ACCOUNTPROMOTED_TWEET
    start_timestringrequired
    ISO 8601 start of the activity window; must be a whole hour (minutes and seconds 0).
    campaign_idsstring
    Comma-separated campaign IDs to scope the check to (max 200; exclusive with the other ids filters).
    funding_instrument_idsstring
    Comma-separated funding instrument IDs to scope the check to (max 200; exclusive with the other i...
    line_item_idsstring
    Comma-separated line item IDs to scope the check to (max 200; exclusive with the other ids filters).
  • xadsmcp_get_app_event_tagGet a single mobile app conversion event tag by IDRead-only

    Get App Event Tag

    Get a single mobile app conversion event tag by ID

    Inputs

    account_idstringrequired
    The ID of the ads account.
    app_event_tag_idstringrequired
    The ID of the app event tag.
    with_deletedboolean
    Include the tag even if soft-deleted (default false).
  • xadsmcp_get_app_listGet a single app list by IDRead-only

    Get App List

    Get a single app list by ID

    Inputs

    account_idstringrequired
    The ID of the ads account.
    app_list_idstringrequired
    The ID of the app list.
    with_deletedboolean
    Include the app list even if soft-deleted (default false).
  • xadsmcp_get_campaignGet a single campaign by IDRead-only

    Get Campaign

    Get a single campaign by ID

    Inputs

    account_idstringrequired
    The ID of the ads account.
    campaign_idstringrequired
    The ID of the campaign to retrieve.
    with_deletedboolean
    Include the campaign even if soft-deleted (default false).
  • xadsmcp_get_campaign_reachGet reach and average-frequency metrics for campaignsRead-only

    Get Campaign Reach

    Get reach and average-frequency metrics for campaigns

    Inputs

    account_idstringrequired
    The ID of the ads account.
    campaign_idsstringrequired
    Comma-separated campaign IDs to fetch reach for (max 20).
    end_timestringrequired
    ISO 8601 end of the metrics window (exclusive); must be in the past (a future end_time is rejected).
    start_timestringrequired
    ISO 8601 start of the metrics window.