X (Twitter) Ads API MCP server: what it can and can't do

X shipped an official Ads MCP server in August 2026, and it settles a question agency teams have been asking all year: can an AI agent run X campaigns without someone writing a custom API integration? For your own ad account, the answer is now yes. For the question that actually drives strategy, which competitors are buying and what creative they are running, the answer is still no.

That split is the whole story here. X now runs two first-party MCP servers. The first, XMCP, landed on 30 June 2026 and covers the organic X API only: posts, search, users, timelines, bookmarks, trends, articles. The second is Ads MCP, built into X's API gateway, and it is the one that touches spend, budgets and campaign structure.

Most advice about an "X Ads MCP server" still points at third-party wrappers written before August 2026, which is why so many evaluation posts and forum threads claim X has no official ads server at all. Below is what the official one does, how to connect it, what the access path costs you in time and money, and where it stops.

What the X Ads API MCP server actually is

Ads MCP is a remote Model Context Protocol server built into X's API gateway at ads-api.x.com/mcp. It exposes 23 Ads API tools to any MCP-capable client, so an agent discovers the full tool list from a single URL instead of you maintaining bespoke Ads API client code. X documents the benefit as zero integration cost: point a client at one endpoint and the tools appear.

The transport is Streamable HTTP. Every request is an HTTP POST carrying JSON-RPC, and responses come back SSE-framed. That matters if you are wiring a custom agent rather than using Claude Code or Grok, because a plain REST client will not speak it.

Authentication is the user's own OAuth 2.0 token. There is no shared service account and no separate agent identity, so an agent only ever sees the ads accounts that the signing-in user can already reach. If you manage twelve client accounts, the agent sees twelve. If a client revokes your access in the Ads Manager, the agent loses it too, without any code change on your side.

This is also why XMCP does not solve the same problem. XMCP has no campaign tools, no line items, no budgets, and no promoted-post analytics. Teams that connected it in July expecting weekly ad reporting found a tool list that was silent on spend. The two servers are separate products with separate endpoints, and running both against one client is a normal setup rather than a mistake.

The 23 tools, grouped by what they touch

The read and account surface is the widest group: list_ads_accounts, list_campaigns, get_campaign, list_line_items, list_funding_instruments, list_promoted_posts, list_targeting_criteria, list_account_posts, and get_active_entities. Anything you would normally open three screens in the Ads Manager to check is a single tool call.

Analytics is deliberately thin. Two tools cover it: get_account_stats and get_campaign_reach. That is enough for a conversational read on spend and delivery, and not enough to replace a warehouse. If you want month-over-month trend lines you still pull the numbers into storage yourself and let the agent query the copy.

Targeting search gives you search_targeting_interests and search_targeting_locations, which is what makes the agent useful for audience work rather than just reporting. Planning a campaign against competitor followers or a niche interest set stops being a manual rebuild every time.

The write group is where the server earns its keep: create_campaign, update_campaign, activate_campaign, create_line_item, update_line_item, activate_line_item, add_targeting_criterion, remove_targeting, create_ad_post for nullcast posts, and promote_post. Campaigns and line items are always created paused. Nothing spends money until activation is explicit, which is the single best safety decision in the whole design.

One structural detail trips up first attempts. X campaigns are three levels deep: campaigns hold budget and schedule, line items hold targeting, bidding and placement, and promoted posts are the creative. An agent that reads tool names alone will try to set targeting on a campaign and get a validation error. The documented test flow works because it lets the model chain tools in order: funding instrument lookup, then campaign, then line item, then targeting.

Connecting an agent: the setup steps and the traps

In the X Developer Console you create or reuse an app and enable Read and Write permissions. The app type should be a Native App, which is a public client using PKCE and no client secret. Under Keys and tokens you copy the OAuth 2.0 Client ID, described in the docs as the long string beginning TzNHbE5X rather than the numeric app ID shown elsewhere in the console.

Then you register a callback URI for whichever client you are using: grok.com/connectors-oauth-exchange-code for Grok on the web, http://127.0.0.1:8080/callback for Grok Build (127.0.0.1 specifically, not localhost), and http://localhost:8080/callback for Claude Code and manual token minting. Finally you open Project Access, click Manage, and select the Ads Project. Until that step is done the endpoint answers your calls with a 403 no matter how good your token is.

Scopes decide what the agent is allowed to do, and this is the part worth getting right on day one. ads.read grants the read and analytics tools. ads.write grants campaign and creative writes. offline.access enables token refresh, and you should always include it, because access tokens expire in roughly two hours and without a refresh scope there is no way to renew them. A read-only agent that browses and analyzes but never changes anything simply omits ads.write, and the write tools fail with authorization errors if anything tries.

Two traps cost real time. First, X keeps a single live OAuth grant per app and user pair, so signing in from a second client revokes the first client's tokens. If you need several clients running at once, create one X app per client. Second, Claude Code sends client_secret_post, which X rejects for confidential apps, so it needs the public Native App configuration to authenticate at all.

The Ads API itself still requires approved access. X's developer documentation says to submit the Ads API Access Form and allow up to 3 business days for review. Turning on the Ads Project in the console enables access for your app ID, but your X user also needs access to at least one ads account before there is anything for the agent to read.

For custom agents that can only send a static Authorization header, the docs include a manual PKCE token mint flow and a curl check against the endpoint with a tools/list JSON-RPC call. A 401 means the token is invalid or expired. A 403 means the app is not enrolled yet.

What the access path costs, and the line item that surprises people

Start with the honest headline: there is no meaningful free tier on the X API in 2026. New developers default to pay-per-use, the legacy Basic plan at $200 per month was retired with subscribers migrated after 1 June 2026, and the Pro plan at $5,000 per month is closed to new signups. The default is now credits plus per-request charges, capped at 2 million post reads per month before you are pushed toward Enterprise, which is a sales conversation rather than a checkout button.

The rate card is easy to reason about until you look at writes. Reads of your own posts run $0.001 each. Reading a third-party post runs $0.005. Reading a user, follower list or trend runs $0.010. Creating a text or media post without a link runs $0.015. Creating a post that contains a URL runs $0.20. That last line is a little over thirteen times the plain-text price, and it lands on exactly the workflow most teams automate: publishing links.

Two more details change how you budget. Per-resource pricing means a single call returning 100 posts is not one $0.005 charge, it is one hundred of them. And the 24-hour deduplication window, which only bills you once for the same resource within a UTC day, is described by X as a soft guarantee rather than a contract, so it is a discount you usually get and not a line you can forecast.

Also budget for throughput separately from cost. Rate limits are per endpoint and enforced in fifteen-minute and twenty-four-hour windows, and spending more credits does not lift them. Teams that plan for spend but not for volume meet HTTP 429 before they ever approach their spending ceiling.

One change from April 2026 is worth flagging because most pricing guides still quote the old numbers. Following, liking and quote-posting through API writes were removed from every self-serve tier on 20 April 2026. Those endpoints were withdrawn rather than repriced, so any engagement automation built on them stopped working rather than getting more expensive.

Keep one distinction clear when you model this. The published pay-per-use meter governs the X API v2 surface that XMCP runs on. Ads API access is a separate approval path with its own developer terms. Confirm the current Ads rates on X's pricing pages before you commit a high-volume agent to production, because X has changed its rate card more than once in the last twelve months.

The gap: the server manages your account, not the market

Here is the limit worth the most attention. Because authentication is the user's own token, Ads MCP operates strictly inside the accounts that user can access. It can tell you how your campaigns performed, draft a new line item, and pause a loser. It cannot tell you what any competitor is running, because it has no path to their accounts and no ad library to query.

X's public transparency surface is the Ads Repository, the archive X publishes under Article 39 of the EU Digital Services Act. It is real and it is useful, and it is also narrower than people assume. Article 39 requires designated platforms to publish a searchable archive of every ad delivered in the EU, retain each ad for a year after its last impression, expose advertiser and funding entity, run period, targeting and exclusion parameters, and per-country reach, and provide API access. Meta, TikTok, Google, LinkedIn and X are all in scope.

X's repository shows the advertiser, the funding entity, basic targeting parameters, impressions, reach and halted ads, with CSV export. It does not show budget, spend, ROAS, bid strategy or account structure. It is a compliance archive, not a spend tracker, and it covers EU-served ads rather than the global feed that people trained on Meta's Ad Library expect.

The practical consequence is blunt: X is structurally the weakest major platform for programmatic competitor creative research. Article 39 makes API access a legal requirement, but in practice Meta and TikTok are the two that ship real, usable APIs. For X you are largely working with an EU-scoped CSV archive, which means most advertisers running outside Europe leave no programmatic trail at all.

That is the seam where a platform MCP and an ad library MCP do different jobs, and it is worth being precise about which one you need. If the question is how do I run my own X campaigns faster, the official server is the right tool and it is free. If the question is what are my competitors doing, no amount of campaign tooling answers it, and you need a research layer that spans platforms. Our breakdown of how MCP servers connect agents to ad platforms covers that second lane end to end.

It also explains why the same gap appears everywhere the pattern repeats. TikTok's ads API is a live, usable surface for agents, and it still hands you your own account rather than the market, which is the tension covered in our TikTok Ads API walkthrough for agents. The LinkedIn Ads API story follows the same shape.

The useful mental model is a two-sided stack: a platform server for control of your own spend, and an intelligence layer for everything you cannot authenticate into. The general version of that architecture, including which platform APIs actually expose competitor data and which only expose your own, is laid out in our LinkedIn Ads API MCP server breakdown.

Four workflows where the official server earns its place

Promote the posts that already worked. This is the play X advertisers keep coming back to, and it is the natural fit for an agent. Ask it to find the highest-engagement post from the last week and draft a promotion at a fixed daily budget. The agent calls list_account_posts, ranks by engagement, then drafts through promote_post. Because the draft is created paused, you review the targeting and the spend before anything is live.

Build handle and interest targeting without the manual rebuild. X's targeting leans on handles and interests more than the interest graphs other platforms favour, and rebuilding the same follower list campaign after campaign is exactly the kind of repetitive work agents are good at. search_targeting_interests plus add_targeting_criterion turns one instruction into a live criterion set.

Run a weekly waste sweep. Pull account and campaign stats, rank by cost per action, and draft pauses for anything above a threshold you set. The value is not that the agent is cleverer than you at cutting spend. It is that the sweep happens every week without a human remembering to do it, and every action still lands paused for approval.

Ask a plain-English question instead of building a report. Because get_account_stats and get_campaign_reach return structured data the model can reason over, a question like how did the retargeting line items do against the prospecting ones in the last thirty days gets answered from live numbers rather than a CSV export. For small teams without a warehouse, that is the highest-return use of the whole server.

If you are still deciding whether a platform MCP belongs in your stack at all, the control-versus-intelligence split is worth reading once before you wire anything up.

Official server versus the third-party Ads MCPs

The official server wins on cost and trust. It is first-party, maintained by X, requires no middleware, and creates everything paused. What it does not have is a review layer. There is no draft queue holding changes until a human approves them, and there is no multi-platform view. If your agent writes a bad targeting criterion, it writes it, and you catch it in the Ads Manager.

Third-party servers fill exactly that gap. AdKit positions its X Ads MCP around a draft-and-approve buffer, priced at $29 per month for a single project and $49 for unlimited projects, bundling several ad platforms into one server. Adzviser takes the managed route with read-only analytics across X and dozens of other platforms from under a dollar a month. CData Connect AI offers full read and write access with SQL-style queries over X Ads entities. Insightful Pipe targets cross-channel reporting.

The trade-off is straightforward. A hosted wrapper handling multiple platforms is more useful when X is one channel among six and you want one reporting surface. The official server is more useful when you are building a focused X workflow and would rather not add a subscription or a third party to the credential path.

One caution before you read comparisons: guides dated before late August 2026 routinely state that X has no official ads MCP. That was accurate for most of the year. It is not accurate now, and the claims to verify first are the ones about whether the official server does ads at all.

Where X ads work, and where they do not

The cost case for X is real. Across 2026 benchmark roundups, X CPMs run roughly $5 to $9 for broad audiences and $8 to $15 for tighter B2B targeting, against LinkedIn figures that sit in the $30s. One April 2026 roundup puts X at an average $6.46 CPM and $0.74 CPC against Facebook at $7.19 CPM and $1.41 CPC. If your audience is on the platform, the arithmetic is friendly.

The audience question decides everything. X performs for B2B software and developer tools, fintech and crypto, and news or media brands whose readers are already in the feed. It performs poorly for direct-to-consumer ecommerce, for visual lifestyle products, and for broad consumer brands, where shopping intent lives on other platforms and text-first placements convert worse.

One measurement trap deserves a warning for anyone reporting on this through an agent. X's engagement metric is unusually broad. Likes, retweets, replies, link clicks, profile clicks, hashtag clicks, media expansions and card clicks all count as engagements. That makes cost per engagement look impressively low next to Meta, and it does not mean those signals carry equal value. Segment link clicks out of the totals before you compare platforms to a client, or you will present a number that flatters X and explains nothing.

Read together, the honest position is this. If X is already the right channel for your audience, an agent connected to the official Ads MCP server removes a genuine amount of weekly drudgery from running it. If you are still deciding whether X is the right channel at all, the server will not help you answer that, because every number it can reach is your own.

Frequently asked questions