X Ads MCP API reference

Every X Ads tool the MCP server exposes, with its parameters. 51 tools, 75 metrics and 4 dimensions, on a dedicated endpoint.

View as Markdown

Performance alertsAvailable on Team and Enterprise. Check supported metrics, levels and dimensions before creating a rule.

Campaigns, ad groups, promoted posts, image/video libraries, website cards and carousels, targeting, conversion events and native performance.

To connect another identity without replacing your existing access, open this source in the dashboard and choose Add another account. Select accounts from the combined list and save. See account scoping for selection, plan limits and reconnection.

Connection

Platform id: x_ads
Tool prefix: x_ads_
Account parameter: account_id
Dedicated endpoint: https://mcp.getmcpads.com/x-ads/mcp
Access: Connect your own X Ads account and select the advertisers to expose. Free permits reads; Pro, Team and Enterprise permit writes. Reconnect older connections for media.write. X controls account verification and delivery eligibility.
Tools: 51, 23 of which write
Metrics: 75
Dimensions: 4

Scope requested

Scope requested
Scope	Grants	Allows writes
`ads.read`	Read authorized X Ads accounts, campaigns, creatives, targeting and performance.	No
`ads.write`	Create and manage X Ads campaigns, ad groups, targeting and promoted posts.	Yes
`media.write`	Upload images and videos for X Ads creatives.	Yes
`offline.access`	Renew the X authorization without another sign-in.	No

Catalogues

Images, video and website cards

Upload PNG or JPEG images up to 5 MB, animated GIFs up to 15 MB and MP4 videos up to 16 MB. The Campaign Launcher uploads your files to X itself before it builds the website cards and carousels. Reconnect an older X Ads connection in Sources to grant media.write. Customers authorize their own X account through Get MCP Ads; they do not need to create a developer application.

Call get_capabilities with platform x_ads, then describe_tool for the operation you need. Advanced tools remain callable through run_tool even when your assistant's initial tool list is short.
Preview x_ads_upload_media with the selected account_id, media_type and base64 file bytes in media_base64. Confirm the reviewed upload. It returns a media ID and media_key; it does not create an ad.
For video or GIF processing, call x_ads_get_media_upload_status using the returned media ID. Respect check_after_secs and wait for processing_info.state to become succeeded before using the asset.
Register the media_key with x_ads_create_media_library_item. Use the library read, update and delete tools to inspect, rename or remove library entries.
Create a promoted-only post with x_ads_create_ad_post, or create a website card with x_ads_create_card and attach its card_uri to a new post. Cards support a single image/video or a carousel of 2 to 6 media keys with one website destination. Replacing a card requires creating a new one.
Attach the post with x_ads_promote_post. Read it back with x_ads_list_account_posts, x_ads_get_promoted_post or x_ads_list_promoted_posts, and inspect x_ads_list_post_previews. Every write needs its own preview and confirmation. Keep the parent campaign and ad group paused until delivery is explicitly approved.

Campaigns, targeting and conversion events

Create campaigns and ad groups in pause, then update names, bids, budgets, schedules, placements and frequency settings. Budgets and schedules belong to ad groups (line items). Search location/interest targeting, add or remove criteria, and read them back. Website event tags can be created, read, updated and deleted; creating a tag does not install a pixel or generate conversion traffic.

Permissions, billing and limits

Free permits reads; Pro, Team and Enterprise permit writes within the selected accounts and provider permissions. Media tools require ads.read, ads.write and media.write on the X connection. The status tool is read-only but still requires those provider scopes.
X API credits, advertising budgets and account verification are separate. A 402 credits-depleted upload error concerns the developer application: contact Get MCP Ads support for a hosted connection. Buying advertising credit or changing your Get MCP Ads plan does not resolve that error.
Uploads are not automatically retried. If a partial failure returns an allocated media ID, retain it and inspect its status before starting another upload. The tool accepts file bytes, not an arbitrary download URL.
X controls verification, advertiser eligibility, creative review and objective prerequisites. Premium verification may block delivery while paused creation still succeeds. App-install and app-engagement objectives require a suitable mobile app.
App/lead cards, multiple website destinations per carousel and files larger than the upload limits are outside this connector's current scope. X Ads is not yet included in the gateway's cross-platform business reviews or creative galleries. Native performance and post-preview tools remain available.

Write tools (23)

Absent from the tool list on the Free plan. Each one previews by default and needs a second call with confirm: true.

Write tools (23)
Tool	What it does	Kind	Discovery
`x_ads_activate_campaign`	Activate a campaign (set entity_status=ACTIVE).	Write	On demand
`x_ads_activate_line_item`	Activate a line item (set entity_status=ACTIVE).	Write	On demand
`x_ads_add_targeting_criterion`	Add one targeting criterion to a line item (call once per criterion).	Write	On demand
`x_ads_create_ad_post`	Compose a promoted-only ("nullcasted") post to use as an ad creative.	Write	On demand
`x_ads_create_campaign`	Create a campaign in an ads account.	Write	On demand
`x_ads_create_card`	Create a card from a JSON components payload.	Write	On demand
`x_ads_create_custom_audience`	Create an empty customer list (CRM) custom audience in an ads account.	Write	On demand
`x_ads_create_line_item`	Create a line item (ad group) under a campaign.	Write	On demand
`x_ads_create_media_library_item`	Register an existing media key as a named item in the account's media library.	Write	On demand
`x_ads_create_web_event_tag`	Create a website conversion event tag (pixel); the returned id can be set as a line item's primary_web_event_tag Preview by default.	Write	On demand
`x_ads_delete_card`	Delete a card from an ads account.	Write	On demand
`x_ads_delete_media_library_item`	Delete a media library object from an ads account Preview by default.	Write	On demand
`x_ads_delete_web_event_tag`	Delete a website conversion event tag Preview by default.	Write	On demand
`x_ads_promote_post`	Attach post(s) to a line item as its ad creative(s).	Write	On demand
`x_ads_remove_targeting`	Remove a targeting criterion from its line item (undo a targeting mistake).	Write	On demand
`x_ads_rename_campaign`	Rename an X Ads campaign.	Write	On demand
`x_ads_rename_line_item`	Rename an X Ads line item (ad group).	Write	On demand
`x_ads_update_campaign`	Rename a campaign or pause it (entity_status=PAUSED).	Write	On demand
`x_ads_update_custom_audience_users`	Add or remove people of an X customer list custom audience from normalized SHA-256 emails and phone numbers, in one batch of at most 2,500.	Write	On demand
`x_ads_update_line_item`	Update a line item's bid, budget, name, schedule, placements, goal, pacing, audience expansion (set audience_expansion=EXPANDED to turn on Optimized Targeting) or entity_status.	Write	On demand
`x_ads_update_media_library_item`	Update a media library object's metadata (e.g.	Write	On demand
`x_ads_update_web_event_tag`	Update a website conversion event tag Preview by default.	Write	On demand
`x_ads_upload_media`	Upload an image, GIF or MP4 to X.	Write	On demand

Read tools (28)

Tools marked Announced appear in your client's tool list. The rest are reachable through search_tools and run_tool, which run the same checks.

Read tools (28)
Tool	What it does	Kind	Discovery
`x_ads_get_account_stats`	Get synchronous analytics (impressions, engagements, spend) for an ads account Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.	Read	On demand
`x_ads_get_active_entities`	List which ads entities had metrics change in a time window (use before requesting account stats) Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.	Read	On demand
`x_ads_get_campaign`	Get a single campaign by ID Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.	Read	On demand
`x_ads_get_campaign_reach`	Get reach and average-frequency metrics for campaigns Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.	Read	On demand
`x_ads_get_card`	Get a single card by ID Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.	Read	On demand
`x_ads_get_custom_audience`	Get a single custom audience by ID, with its type, size and whether X can target it Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.	Read	On demand
`x_ads_get_line_item`	Get a single line item by ID Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.	Read	On demand
`x_ads_get_media_library_item`	Get a single media library object by media key Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.	Read	On demand
`x_ads_get_media_upload_status`	Read processing status of an upload owned by the connected X user.	Read	On demand
`x_ads_get_promoted_post`	Get a single promoted post by ID Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.	Read	On demand
`x_ads_get_targeting_criterion`	Get a single targeting criterion by ID Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.	Read	On demand
`x_ads_get_web_event_tag`	Get a single website conversion event tag by ID Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.	Read	On demand
`x_ads_list_account_posts`	List posts (tweets) usable for promotion by an ads account Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.	Read	On demand
`x_ads_list_ads_accounts`	List the ads accounts the authenticated user can access Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.	Read	Announced
`x_ads_list_campaigns`	List campaigns for an account Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.	Read	On demand
`x_ads_list_cards`	List the cards in an ads account Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.	Read	On demand
`x_ads_list_custom_audience_targeted`	List the line items and campaigns that target a custom audience Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.	Read	On demand
`x_ads_list_custom_audiences`	List the custom audiences of an ads account, with their type, size and whether X can target them (targetable, reasons_not_targetable) Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.	Read	On demand
`x_ads_list_funding_instruments`	List funding instruments (payment sources) for an ads account Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.	Read	On demand
`x_ads_list_line_item_placements`	List valid placement combinations per line item product type Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.	Read	On demand
`x_ads_list_line_items`	List line items (ad groups) for an ads account Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.	Read	On demand
`x_ads_list_media_library`	List the media library objects in an ads account Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.	Read	On demand
`x_ads_list_post_previews`	Get rendered HTML previews for published or scheduled posts Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.	Read	On demand
`x_ads_list_promoted_posts`	List promoted posts (promoted tweets) for an ads account Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.	Read	On demand
`x_ads_list_targeting_criteria`	List targeting criteria for an ads account's line items Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.	Read	On demand
`x_ads_list_web_event_tags`	List the website conversion event tags (pixels) in an ads account; a tag's id is what a conversion line item takes as its primary_web_event_tag Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.	Read	On demand
`x_ads_search_targeting_interests`	Search targetable interest categories by name.	Read	On demand
`x_ads_search_targeting_locations`	Search targetable locations by name.	Read	On demand

MCP resources

Read these with resources/read for machine readable metadata about the source.

MCP resources
Name	URI
X Ads reporting and writes	`x-ads://guide`

Manage your ads from your AI assistant

Start for free

Free with 1 ad account, no card. Pro is free for 7 days.