X MCP server: connect Claude or Grok to X

#Quick answer

X runs three hosted MCP servers. api.x.com/mcp exposes X API tools (post lookup, full-archive search, users, bookmarks, trends, news, Articles). docs.x.com/mcp searches the developer documentation. ads-api.x.com/mcp exposes 74 X Ads tools for reading, analysing and managing campaigns. They are separate endpoints with separate auth, and the API one needs a local bridge because X's OAuth does not support dynamic client registration.

Last updated: October 2026

#Three servers, not one

Most writeups of the X MCP server are describing one of three different things, which is why the setup instructions you find never quite match what you are looking at. Here is the actual map.

Model Context Protocol is the open standard for connecting a model to tools, so any MCP-capable client reaches all three the same way: Claude Code, Cursor, Grok Build, VS Code in agent mode, or something you wrote yourself on the MCP SDKs.

The timeline matters for figuring out which one a given article is about. The X API MCP server arrived quietly, bundled into the 6 February 2026 pay-per-use launch alongside the Developer Console, the XDK and the Playground. The Ads server was the one that got headlines, launching 23 August 2026 - after Meta shipped the same idea in April 2026 and TikTok, Pinterest and Snapchat followed.

#The X API server, and why it needs a bridge

This is the part that trips people up, and X is unusually candid about it in its own documentation: "X's OAuth requires your own developer app. There is no dynamic client registration, and api.x.com/mcp does not advertise native MCP OAuth discovery."

Translated: you cannot paste the URL into a client and let it negotiate. The modern remote-MCP flow where a client registers itself and walks you through consent does not exist here. So X ships a tiny local process, the open-source xurl mcp bridge, that owns the app identity, does the one-time browser login, caches the token in ~/.xurl, and refreshes it from then on - including a forced refresh after a 401.

A working Claude Code or Cursor entry looks like this:

{
  "mcpServers": {
    "xapi": {
      "command": "npx",
      "args": ["-y", "@xdevplatform/xurl", "mcp", "https://api.x.com/mcp"],
      "env": {
        "CLIENT_ID": "YOUR_X_APP_CLIENT_ID",
        "CLIENT_SECRET": "YOUR_X_APP_CLIENT_SECRET"
      }
    }
  }
}

Three details that are not optional:

• Register http://localhost:8080/callback on the app, or the first login fails in the browser. You can override it with REDIRECT_URI, but then register that instead. Getting an app set up in the first place is covered in how to get an X API key.
• Set the startup timeout to 300 seconds or more. The bridge holds the MCP handshake open until you finish the browser login. A client with a 30-second default will decide the server is dead while you are still typing your password.
• Do not run the client verbose. The bridge writes diagnostics to stderr on purpose so stdout stays a clean JSON-RPC channel. Mixing them produces garbled tool output.

There is a simpler route if you only need reads. Point a client straight at api.x.com/mcp with an app-only Bearer token in an Authorization header: no bridge, no browser. You lose auto-refresh and you lose user context, which means no writes and no acting as you.

One trap worth naming because it is silent: the OAuth login authorises whichever X account is signed in when the browser opens, not necessarily the account that owns the app. Hook up a bot account without switching accounts first and you have just given an agent your personal timeline.

#The Ads server is the more interesting one

Ads MCP is built into X's API gateway and behaves like a proper remote MCP server - Streamable HTTP, PKCE, no local bridge. Point a client at https://ads-api.x.com/mcp, complete consent, and 74 tools appear with no Ads API client code written at all.

What those tools cover:

• Reads: ads accounts, campaigns, line items, placements, funding instruments, promoted posts, account posts, active entities
• Analytics: get_account_stats, get_campaign_reach
• Targeting: interest and location search, targeting criteria, estimate_audience
• Audiences: custom audiences and do-not-reach lists, including batch user operations
• Creatives and media: cards, media library, account media, media creatives, post previews
• Conversion tracking: web event tags (pixels), app event tags, tracking tags, app lists
• Writes: create_campaign, update_campaign, activate_campaign, create_line_item, add_targeting_criterion, remove_targeting, create_ad_post, promote_post

The design decision that makes this usable rather than terrifying: campaigns and line items are always created paused. X documents that nothing spends money until it is explicitly activated. An agent can chain accounts to funding instruments to campaign to line item to targeting from one plain-English request, hand you a complete campaign, and still not have moved a cent. The human approval step is the activation.

Two setup specifics the docs are strict about. X wants a Native App (public client) registered, with Read and Write permissions and the Ads Project selected under Project Access, and the OAuth 2.0 Client ID is the long string, not the numeric app ID shown elsewhere in the console. And the callback differs per client - Grok Build needs 127.0.0.1:8080 rather than localhost, while Claude Code needs localhost:8080. X keeps a single live OAuth grant per app and user, so signing in from a second client revokes the first. Run one app per client if you want two agents at once.

Scopes are the real control surface

This is where you decide what an agent can do, and it is one array in a config file:

For an analyst agent that reads performance and suggests changes without touching anything, use ads.read and offline.access and nothing else. Write tools then fail with authorisation errors, which is the behaviour you want. media.write is not needed for read-only media browsing or ordinary campaign management.

#What MCP does not change

An MCP server is a transport. It is worth being specific about what stays exactly as it was, because "connect your AI to X" marketing tends to imply otherwise.

Billing is unchanged. Calls bill against the pay-per-use model X launched on 6 February 2026, which replaced the old fixed tiers. If you are budgeting, X API pricing covers what the per-request costs look like. MCP is not a cheaper door into the same endpoints.

The reply restrictions still apply. On 23 February 2026 X limited programmatic replies through POST /2/tweets to cases where the original author has summoned the replier, by @mentioning that account or quoting one of its posts, with extra restrictions on programmatic @mentions and quotes. Those changes hit self-serve tiers. An agent reaching the API through MCP is subject to all of it, so "I will have Claude run my reply strategy" does not survive contact with the API. The practical state of play is in what the X API is and how to use it.

Permissions are a ceiling, not a suggestion. Ads MCP only ever sees the ads accounts your user can access. The API server acts with your account's scopes. Neither grants an agent anything you do not already have, which is the right default and also means a misconfigured app is a you problem rather than a platform problem.

Your tokens are secrets. X's own guidance is to treat ~/.xurl and access tokens as secrets, prefer per-project config referencing environment variables over committed files, and use a dedicated app with only the scopes needed. Worth auditing which apps have access to your X account while you are in there.

#Where MCP genuinely helps, and where it does not

MCP is good at the thing that used to cost an afternoon: ad-hoc reads. "Which line items in this account have spend but no conversions this month" is a question that previously meant an analytics query, a schema check and a script. Now it is a sentence, and the model chains the tool calls itself.

It is also good at assembly with review. Building a campaign through the Ads API by hand is a five-object dance across accounts, funding instruments, campaigns, line items and targeting criteria. Having a model do that and hand you a paused result you can inspect is a real reduction in tedium with the risk retained on your side of the fence.

Where it does not help is organic growth. The API MCP server can search, read and bookmark; it cannot run the reply-driven presence that actually grows an account, because the February 2026 restrictions closed that route deliberately. Anyone promising an MCP server that automates X engagement at scale is either using enterprise access or not using the API at all.

That second category is where tools like X-Autopilot sit, and it is worth being plain about the trade. Driving your own browser on your own Mac is not the sanctioned API path. We do not claim it complies with X's terms - browser automation is a grey area, and X's automation rules are the document to read before you decide anything. What it does offer is a lower detection surface than cloud schedulers: residential IP, your own browser session, no delegate account, no shared cloud IP pool. Reduced exposure, not zero. If sanctioned access is a hard requirement for you, the API route is the one to take, and MCP is now the fastest way to drive it.

#The bottom line

Three servers, three purposes. Add docs.x.com/mcp today if you build against the X API at all - it costs nothing, needs no credentials, and stops your assistant inventing endpoint names. Add ads-api.x.com/mcp if you run campaigns, start with ads.read and offline.access only, and promote to write access once you trust what the agent proposes. Add api.x.com/mcp through the xurl bridge if you need real API calls, and set that 300-second startup timeout before you spend an hour debugging a handshake that was only waiting on your browser.

What none of it does is change the rules. The pay-per-use meter still runs, the reply restrictions still bind, and the scopes you grant are the real security boundary. MCP removes the integration work. It does not remove the arithmetic.