X Ads

X Ads is a separate connector from organic X. The Ads API requires approved Ads API access and three-legged OAuth 1.0a, so it cannot reuse the organic connector’s OAuth 2.0 token or permissions.

Before You Connect

The deployment administrator configures an approved X developer App in xAdsOAuth:

{
  "xAdsOAuth": {
    "consumerKey": "replace-with-x-ads-consumer-key",
    "consumerSecret": "replace-with-x-ads-consumer-secret",
    "redirectUri": "https://api.example.com/oauth/mcp/callback"
  }
}

Without the local-stack generator, set X_ADS_OAUTH_CONSUMER_KEY, X_ADS_OAUTH_CONSUMER_SECRET, and X_ADS_OAUTH_REDIRECT_URI on the backend. The connected X identity must have access to the required advertising accounts.

Add the exact callback to the X developer App’s approved callback URLs. The default local callback is http://127.0.0.1:3000/oauth/mcp/callback. X treats a different scheme, hostname, port, path, or query as a different callback. Set xAdsOAuth.redirectUri to an approved public HTTPS callback when the backend is externally reachable.

Choose:

• Read-only for accounts, funding, campaigns, line items, targeting, media libraries, audiences, A/B tests, and analytics.
• Full access for reviewed campaign, line-item, promoted-post, targeting, media-library, audience, and experiment changes.

Chat remains read-only. Consequential work runs as a Growth task through the action lifecycle.

Direct Tool Surface

• Advertising accounts and funding instruments.
• Campaign and line-item reads, paused creation, and reviewed updates.
• Promoted-post and targeting management.
• Targeting-option discovery.
• Account media-library reads and changes.
• Custom-audience lifecycle operations.
• Native A/B-test reads, creation, updates, and deletion.
• Synchronous analytics for up to twenty entities and seven days.
• Asynchronous analytics jobs for up to 90 unsegmented days or 45 segmented days.

New campaigns and line items are forced to PAUSED. The provider exposes fixed Ads API v12 resources and structured inputs; it has no raw endpoint executor.

Private Media

The x-ads-media companion shares Oblive’s verified private staging and chunking implementation with organic X while retaining a separate runtime grant and credential.

The companion infers images and GIFs as their ordinary X media categories. MP4 and MOV use amplify_video and are limited to 500 MB. After upload, add the returned media ID or key to the selected account through x_ads_manage_media_library.

Each upload is a durable external action. Provider acceptance is not proof that video processing or ad delivery completed; verify the media-library and campaign state before reporting success.

Experiments And Analytics

Native A/B-test group allocations must total 100 percent. Line-item tests allow at most five groups with one line item in each group. Use one metric definition, segmentation, attribution basis, and time window across variants.

Do not hold a task run open for an experiment window, analytics job, or media processing. Preserve the returned identifier and schedule a later task to read the provider state.