Set up X Ads MCP safely

This guide covers only the official X Ads MCP at https://ads-api.x.com/mcp and its documentation at https://docs.x.com/x-ads-api/mcp. It is not setup guidance for a general X API server. Before connecting, decide whether the agent should only analyze campaigns or may also prepare changes after human approval. For the first test, use a separate ads test account or a tightly bounded campaign.

Prepare the X app and Ads access

Create a new or existing app in the X Developer Console. Per X, enable the Read and Write app permission, choose a Native App for the usual PKCE route, and register exactly the callback URI required by the client you use. For Claude Code, X lists http://localhost:8080/callback; other clients may require different callback URIs documented by X. Enable Ads Project under Project Access. Also confirm that your X user actually has access to at least one ads account. An ordinary X profile is not sufficient without an ads-account or role authorization.

According to X, one app-and-user pair has only one active OAuth grant. Signing in with the same user from a second client can make the first client lose its tokens. Use a separate X app for each long-lived client and document who owns that app and its associated ads account.

Connect with the smallest scopes

Start with the OAuth scopes ads.read offline.access. This lets the agent list accounts and read analytics, but it cannot change campaigns, line items, creatives, or targeting. offline.access enables token refresh; without it, you must sign in again interactively after the access token expires. Add ads.write only when there is a clear change request and an approval path.

X documents this basic command for Claude Code:

claude mcp add x-ads https://ads-api.x.com/mcp --transport http --client-id YOUR_OAUTH2_CLIENT_ID --callback-port 8080

Then run /mcp in the client and complete browser login. X’s documented scope restriction for Claude Code is set in its server configuration as ads.read offline.access. Never paste an access token, refresh token, OAuth code, or client secret into a chat. Native apps do not need a client secret for PKCE.

Read first, then write deliberately

First ask the agent to list reachable ads accounts and explain one campaign with its performance data. Check that the account number, display name, and time range are correct. Tool results can include reach, spend, targeting, funding information, or promoted-post data; treat all of it as confidential.

For changes, have the agent first provide a plan: target account, campaign name, budget and schedule, targeting, creative, and the exact tool sequence. Review that plan independently of tool text. According to X documentation, new campaigns and line items are always created PAUSED. That prevents immediate spend, but it does not replace review: only activate_campaign or activate_line_item performs activation. Approval and activation should stay with an accountable person.

Limit the data path and prompt injection

Data flows from X to the MCP client and then, depending on client configuration, onward to the language model. With a cloud model, campaign, audience, and customer data can therefore also reach the model provider. Check privacy requirements, data-processing terms, log retention, and whether tool results are stored or used for training. Do not use real customer segments in early tests if their onward disclosure is unresolved.

Names from audiences, posts, or analytics fields are not trusted instructions. If a tool result asks to fetch more data or activate a campaign, that is prompt injection. Do not let tool data determine tool selection. Separate analysis from write access, require explicit confirmation for every activation, and use a test account whenever practical.

Observe rate limits and handle errors safely

X exposes limits and reset times in response headers. Respect token-level and, where present, ads-account-level headers. Batch requests, ask only for data changed since the last sync, and never retry errors blindly. A 401 can mean an expired token; refresh it through the intended OAuth flow. A 403 commonly means missing Ads Project access, app enrollment, or account permission. A 429 means wait until reset and reduce request rate.

Final check

Record which client, X app, user, and ads accounts are connected. Verify that an analysis-only session without ads.write cannot execute changes. Document who approves campaign activations, and review client configuration regularly for unnecessary tokens or over-broad scopes. This keeps X Ads MCP a controlled tool for ads analysis and prepared campaign work rather than an unattended write channel.