Start free
    Menu
    How it worksIntegrationsCustomersPricingSign in

    integrations tools x-ads

    X Ads MCP for your AI agent

    Cogny's X Ads integration exposes 38 tools (16 read, 17 write, 5 destructive) to an AI agent over MCP. The same tools are available on every plan, from your own AI client or inside the Cogny app.

    • 16readonly reads data.
    • 17writecreates or changes something.
    • 5destructivedeletes, removes or replaces something.

    Over MCP your own AI client asks before it runs a write. To take a tool away from your agent, block it in Settings → Integrations. Plans, approvals and limits

    set it up.

    Add Cogny to your AI client once, then connect X Ads in Cogny. Every X Ads tool below appears in the client.

    • Claude CodeRun claude mcp add --transport http cogny https://app.cogny.com/mcp, then authorise in the browser.
    • Claude.aiSettings → Connectors → Add custom connector, URL https://app.cogny.com/mcp, then log in and pick your workspace.
    • ChatGPTSettings → Apps → Advanced settings → Developer mode → Create app, URL https://app.cogny.com/mcp, authentication OAuth.
    • CursorIn Cogny, Settings → Data & Integrations → Connect AI Clients shows the block to paste into .mcp.json, with an API key.
    • CodexRun codex mcp add cogny --url https://app.cogny.com/mcp.

    Full setup, and how to undo it

    Connecting and limits

    Connecting signs in with the X account that administers the ad account. The tools reach every ad account that login can manage, and the workspace can restrict which ones are allowed in Settings.

    A campaign in X Ads is a container: the objective, flight dates, budget, bidding and targeting all live on the line item (ad group), and the ad is a promoted tweet attached to it. tool_create_line_item takes the objective the X Ads UI shows as goal and fills in X's legacy billing field itself.

    An ad's policy-review status shows on the promoted tweet. tool_get_promoted_tweet returns approval_status (ACCEPTED / REJECTED / PENDING / REVOKED) plus the disapproval_reasons (each with a code and human-readable message) when X rejected the creative, and the review timestamps — so an agent can learn why an ad isn't serving without opening the X Ads UI.

    Known gaps

    • tool_appeal_promoted_tweet posts to X's creative-appeals endpoint, which is not available to every API consumer and can require additional account or app access. If X refuses the appeal, the fallback is to read the rejection reasons with tool_get_promoted_tweet and recreate the creative with adjusted copy (tool_create_promoted_tweet), not to retry the appeal.
    • Follower targeting only works for accounts the ad account itself can promote. tool_add_targeting_criteria with FOLLOWERS_OF_USER or SIMILAR_TO_FOLLOWERS_OF_USER on a third-party account (a brand or person you don't own) is refused by X. Reach that audience with interest, conversation or keyword targeting instead.
    • A post without a link cannot be promoted on a link-clicks line item. X refuses the pairing; boost such a post with an engagement or reach line item.
    • A campaign keeps the objective of its first line item for good, even after that line item is deleted. A different objective means a new campaign.
    • A frequency cap is impressions per user per duration_in_days (default one day). X has no lifetime cap.
    • tool_search_conversations matches topic names, not accounts: searching a company name returns X's catalogue of topics, which may not include that company.

    what each tool does.

    Read 16 · only reads data

    • tool_list_ad_accountsReadLists all X ad accounts accessible by the current user.
    • tool_get_funding_instrumentsReadGet funding instruments (payment methods) for an ad account.
    • tool_get_web_event_tagsReadList X Ads conversion pixels (Web Event Tags) on an account.
    • tool_search_locationsReadSearch X Ads location targeting values.
    • tool_search_conversationsReadSearch X Ads conversation topic targeting values.
    • tool_search_eventsReadSearch X Ads event targeting values.
    • tool_get_campaignsReadGet campaigns for an ad account.
    • tool_get_line_itemsReadGet line items (ad groups) for an ad account.
    • tool_get_promoted_tweetsReadGet promoted tweets (ads) for an ad account.
    • tool_get_promoted_tweetReadGet one promoted tweet (ad) with its full policy-review surface.
    • tool_get_analyticsReadGet performance analytics for campaigns, line items, or promoted tweets.
    • tool_get_tailored_audiencesReadList the account's custom audiences (website visitors, uploaded lists, lookalikes).
    • tool_get_targeting_criteriaReadGet targeting criteria for line items.
    • tool_get_tweetsReadFetch X Ads tweets — the actual creative behind a promoted tweet.
    • tool_get_cardsReadList X Ads Cards (creative attachments referenced by `card_uri` on a tweet).
    • tool_get_cardReadGet a single Card with its full `components` list.

    Write 17 · creates or changes something

    • tool_upload_mediaWriteUpload a video / image / GIF to X's media library and return a `media_key` usable in `create_card` (MEDIA component) and `create_tweet` (`media_keys`).
    • tool_create_campaignWriteCreate a new campaign.
    • tool_update_campaignWriteUpdate an existing campaign.
    • tool_update_campaign_statusWriteUpdate a campaign's status (pause, activate, or set to draft).
    • tool_create_line_itemWriteCreate a new line item (ad group) with its objective, schedule, budget and bidding.
    • tool_update_line_itemWriteUpdate an existing line item.
    • tool_update_line_item_statusWriteUpdate a line item's status (pause, activate, or set to draft).
    • tool_create_promoted_tweetWriteCreate a promoted tweet (ad) by associating an existing tweet with a line item.
    • tool_pause_promoted_tweetWritePause a promoted tweet: stop paying to show the post.
    • tool_appeal_promoted_tweetWriteSubmit a policy appeal / request a re-review of a disapproved promoted tweet.
    • tool_create_tailored_audienceWriteCreate a tailored audience (custom audience).
    • tool_update_tailored_audienceWriteUpdate a tailored audience.
    • tool_add_targeting_criteriaWriteAdd targeting criteria to a line item.
    • tool_create_tweetWriteCreate a new tweet usable as ad creative.
    • tool_update_tweetWriteUpdate a Promoted-only tweet (only nullcast=True tweets can be updated — published tweets are immutable).
    • tool_create_cardWriteCreate a new X Ads Card (V2).
    • tool_update_cardWriteUpdate a Card's name and/or components.

    Destructive 5 · deletes, removes or replaces something

    • tool_delete_campaignDestructiveDelete a campaign.
    • tool_delete_line_itemDestructiveDelete a line item.
    • tool_delete_promoted_tweetDestructiveStop promoting a post.
    • tool_delete_tailored_audienceDestructiveDelete a tailored audience.
    • tool_delete_targeting_criteriaDestructiveDelete targeting criteria from a line item.

    Exact input schemas come from tools/list once X Ads is connected; the free plan is enough to check. Missing something? Your agent can ask for it with request_feature.

    This page as markdownAll integrationsHow Cogny uses X Ads