X Ads MCP: A Safe Developer Guide to AI-Powered Campaign Management

X Ads MCP is a hosted Model Context Protocol server that lets compatible AI clients inspect, analyze, create, and manage X advertising campaigns through natural-language requests. The official server is available at https://ads-api.x.com/mcp, and X documents 23 tools spanning account reads, analytics, targeting lookup, campaign management, and creative operations.

The important operational boundary is that X does not hand an agent an unrestricted advertising identity. The connection uses the user’s OAuth 2.0 token, scopes determine whether the client can write, and newly created campaigns and line items start paused. Nothing spends money until someone explicitly activates it.

This guide explains what the server exposes, how to connect it to Grok or Claude Code, how to configure read-only access, and what teams should verify before allowing an agent to touch a live ad account.

The short answer

X Ads MCP is useful when an advertiser wants an AI client to work with live X Ads context without writing a bespoke Ads API integration. A compatible client discovers the tools from the remote endpoint and can then perform requests such as:

• list accessible ad accounts and campaigns;
• retrieve campaign performance and reach estimates;
• search targeting interests and locations;
• create a paused campaign and line item;
• update campaign or line-item settings; and
• activate or pause work after human review.

X’s developer documentation says the server is compatible with Grok, Claude Code, and custom clients built with MCP SDKs. Independent reporting from PPC Land and MediaPost also confirms the August 2026 launch and its 23-tool advertising surface.

The safest starting point is a read-only connection using ads.read and offline.access. Add ads.write only when the client, app, account, and approval workflow have been tested.

What X Ads MCP actually exposes

The server divides its 23 tools into four practical groups. Nine are account and inventory reads, two return analytics, two resolve targeting identifiers, and ten can change advertising state.

The full list is in the official X Ads MCP reference. The split matters because nearly half of the exposed surface is state-changing. A client that can read campaign performance is not equivalent to a client that can also create line items, add targeting criteria, or activate a campaign.

The paused-by-default safety boundary

X states that campaigns and line items created through the server are always PAUSED. The model can chain the setup calls, but the resulting objects do not spend money until an explicit activation operation occurs.

That is a useful checkpoint, not a complete approval system. A model could still create an incorrect campaign name, objective, audience, budget, or creative association. Treat the paused object as a generated change proposal that must be inspected in Ads Manager or through a separate read-back request.

A good prompt makes the checkpoint explicit:

Create a paused campaign only. Before any activation, show the account, funding instrument, objective, daily budget, targeting IDs, dates, and all objects you created. Do not activate anything.

Architecture and request flow

The remote server sits between the MCP client and the X Ads API gateway. OAuth scopes and the user’s existing Ads permissions determine the account boundary; the MCP tool layer determines which operations the client can request.

Visual 1 — Original X Ads MCP request flow. The client can orchestrate several tool calls, but OAuth authorization and the paused-by-default rule remain the important control points. The endpoint and capabilities in this diagram are based on X’s official documentation.

The server uses Streamable HTTP. Requests are HTTP POST messages carrying JSON-RPC, and responses are framed as server-sent events. Tool discovery occurs through the normal MCP tools/list operation, so the client does not need a hand-written wrapper for every Ads API endpoint.

This remote architecture is distinct from a local script that stores a long-lived Ads API credential. For broader protocol deployment context, see the site’s MCP 2026-07-28 stateless migration guide, which covers the infrastructure and security implications of modern HTTP-native MCP servers.

Authentication and scope design

X Ads MCP authenticates with the user’s OAuth 2.0 token. The agent can see only advertising accounts that the user can already access. The token does not magically expand the user’s Ads permissions.

Three scopes are central:

• ads.read enables account reads and analytics;
• ads.write enables campaign, line-item, targeting, and creative writes; and
• offline.access enables token refresh.

For a reporting or diagnostic agent, use ads.read offline.access and omit ads.write. X says that write tools will fail with authorization errors when the write scope is absent. This is preferable to relying on a prompt such as “never change anything,” because the permission boundary is enforced by authorization rather than model compliance.

Access tokens last roughly two hours according to the documentation. Refresh tokens rotate, so an implementation must persist the newest refresh token safely. Never put access tokens, refresh tokens, client secrets, or Ads account credentials in prompts, source control, screenshots, or shared MCP configuration files.

Connect Grok Build

Create or reuse an app in the X Developer Console, enable the Ads Project, and copy the OAuth 2.0 Client ID. X’s documentation distinguishes this long client identifier from the numeric app ID displayed elsewhere in the console.

For Grok Build, add the remote server to ~/.grok/config.toml:

1[mcp_servers.ads-mcp]
2url = "https://ads-api.x.com/mcp"
3
4[mcp_servers.ads-mcp.oauth]
5clientId = "YOUR_OAUTH2_CLIENT_ID"
6callbackPort = 8080
7scopes = ["ads.read", "offline.access"]

The documented configuration uses camelCase keys such as clientId; X warns that snake_case keys can be silently ignored. The callback for Grok Build is http://127.0.0.1:8080/callback, not localhost.

After saving the configuration, open Grok, use /mcps, select ads-mcp, and complete the browser consent flow. Start with a read request:

List my accessible X Ads accounts and show which permissions this connection has.

Then ask for a bounded analytics query with an explicit date range. If the client returns no tools, stop and troubleshoot authentication before attempting a write.

Connect Claude Code

X documents a Claude Code setup using a public client because Claude Code sends client_secret_post, which X rejects for confidential clients. Register http://localhost:8080/callback for the Claude Code client, then add the server:

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

Run /mcp inside Claude Code and complete the login. X says Claude Code does not provide a command-line scope flag; to narrow access to read-only, configure the server entry in ~/.claude.json with the scopes ads.read offline.access.

Do not assume that the same OAuth app can safely serve every client at once. X documents one live OAuth grant per app-and-user pair, meaning signing in from a second client can revoke the first client’s tokens. For teams that need concurrent clients, separate apps and separate ownership/audit rules are safer than sharing one grant.

A verification-first operating workflow

Use this sequence before allowing a production account or write scope.

1. Confirm the connection

Ask the client to list available tools and identify the granted scopes. A successful discovery response should expose the X Ads tool namespace. An empty list usually indicates an OAuth, enrollment, transport, or client configuration problem.

2. Run inventory reads

List accounts, campaigns, line items, and funding instruments. Require the agent to state the account identifier it is using. If the returned account is not the intended staging account, stop immediately.

3. Validate analytics against native reporting

Ask for a time-bounded campaign summary, then compare account, currency, date range, attribution window, and metric definitions with Ads Manager. An agent response is a convenient interpretation, not the financial source of truth.

4. Test targeting lookup without creating anything

Search for a targeting interest or location and inspect the returned identifiers. Do not let a model infer IDs from memory or from an unrelated account.

5. Create one paused staging object

If write access is required, use a staging or low-risk account. Ask the client to create exactly one paused campaign with a small test budget and no activation permission in the workflow. Read the object back and verify every field.

6. Keep activation separate

Activation should be a distinct human-approved step. Require a final checklist covering account, objective, budget, schedule, targeting, creative, tracking, and expected spend. Never combine “create and activate” in the first production test.

Security and privacy checklist

MCP standardizes the connection protocol; it does not make an AI client trustworthy by itself. Apply the same discipline used for other agent connectors, including the site’s Meta Developer Tools MCP guide and Snapchat Ads MCP integration guide.

• Begin with ads.read; grant ads.write only to a named workflow.
• Use a dedicated staging account for testing tool chains.
• Keep OAuth client credentials and rotating refresh tokens in a secret manager.
• Restrict the connected user to only the accounts required for the task.
• Record user, client, account, scopes, prompt purpose, tool calls, and final approval.
• Treat campaign data, budgets, audiences, creatives, and performance reports as sensitive business data.
• Review the AI client’s retention, training, regional processing, and enterprise controls.
• Require confirmation before activate_campaign or activate_line_item.
• Revoke the OAuth grant and remove the app when the integration is no longer needed.

The paused default reduces accidental spend, but it does not prevent an agent from producing a misleading recommendation or modifying a paused object incorrectly. Human review, narrow scopes, and auditable change records remain necessary.

Common errors

The client discovers tools but reads fail

Check that the user has access to at least one Ads account, the Ads Project is enabled for the app, and the token includes ads.read. A valid MCP connection does not guarantee valid Ads account authorization.

Write tools return authorization errors

The token probably lacks ads.write, or the user does not have the required Ads permissions. For a reporting client, this is the desired failure mode. Do not work around it by embedding a broader static token.

OAuth succeeds, then fails later

Confirm that offline.access was requested and that the newest rotated refresh token is being stored. Access tokens expire in roughly two hours; a client that discards rotated refresh tokens will eventually return 401 errors.

Claude Code cannot complete the flow

Use a public client and the documented localhost callback. X says confidential clients using client_secret_post are rejected. Also check that another client has not taken over the app-and-user OAuth grant.

A campaign appears but no money is spent

That is expected when the object was created through the MCP server: campaigns and line items begin paused. Activation is separate and must be deliberate.

When X Ads MCP is a good fit

X Ads MCP is a strong fit for interactive campaign analysis, bounded diagnostics, targeting lookup, and human-reviewed setup workflows. It can remove repetitive Ads API plumbing for teams that already use MCP-capable clients.

It is not a substitute for a reporting warehouse, a billing reconciliation system, a compliance archive, or a fully governed campaign deployment pipeline. For those systems, keep the native Ads API and first-party reporting as the source of truth, and treat the agent as an interface that proposes or retrieves work.

The practical rule is simple: let the agent accelerate discovery and preparation, but make authorization, activation, and spend-changing decisions explicit.

Frequently asked questions

Is X Ads MCP read-only?

No. It exposes both read and write tools. The connection can be made read-only by omitting ads.write from the OAuth scopes.

Does X Ads MCP work only with Grok?

No. X explicitly documents Grok, Claude Code, and custom MCP clients. Any compatible client still needs correct OAuth enrollment and Ads account permissions.

Will an agent spend money immediately after creating a campaign?

Not by default. X says campaigns and line items created through the server start paused. Spending begins only after explicit activation.

Can I use a static bearer token?

X documents a static-token path for clients that do not support OAuth login, but rotating OAuth tokens and narrow scopes are safer for normal integrations. Never hard-code a live token in a repository or prompt.

Sources and visual credits

• X Ads MCP official documentation — endpoint, tools, OAuth scopes, client setup, transport, and paused-by-default behavior.
• PPC Land: X Ads MCP gives Grok and Claude Code 23 tools — independent launch analysis and tool-surface reporting.
• MediaPost: X launches advertiser MCP — independent confirmation of the launch and third-party AI compatibility.
• Visual 1: original Mermaid architecture diagram by Essa Mamdani, based on the official X Ads MCP documentation.
• Visual 2: original comparison table synthesized from the official X Ads MCP tool categories.

Related reading

Continue exploring related AI engineering and developer tooling topics:

• Codex MCP Server Deprecation: App Server Migration Guide
• Spring Tools 5.2.0: Claude Code, Embedded MCP, and Safer Spring Boot Workflows
• Claude Code 2.1.246: Security, MCP, and Auto Mode Changes Developers Should Audit