Set up X API MCP safely

This guide sets up the official general X API MCP, not X Ads MCP. Use https://docs.x.com/tools/mcp as the authoritative instructions. The current service is https://api.x.com/mcp; the local xurl mcp bridge performs OAuth login and speaks to the MCP client over stdio. The official repository https://github.com/xdevplatform/xMCP is an additional local FastMCP implementation of the general X API. Its GitHub stars belong only to that general repository, never to the Ads server.

Limit the purpose before connecting

First decide whether the client should only read public X data or act on behalf of an account. Public research, such as Posts, users, trends, or news, needs no user context. Bookmarks, Articles, Posts, follows, messages, or deletion are account actions. Define a read-only first test, for example a search for a narrowly bounded topic. Keep that client separate from any later write client. This prevents a model from accidentally acting with a token intended for analysis.

Prepare the app and OAuth 2 with PKCE

Create a dedicated App in the X Developer Console for this MCP purpose and enable OAuth 2. Register exactly http://localhost:8080/callback when using X’s documented default configuration. If a redirect URI differs, the exact URI must be present in both the App and REDIRECT_URI. Keep CLIENT_ID and CLIENT_SECRET only as local environment variables or in a secret store, never in a project file, prompt, or screenshot. A public client should not use a secret; follow X’s documented client type and PKCE flow.

Request the smallest scopes. An App-only Bearer token can be enough for analysis; it provides public read endpoints without acting as a user. For user context, start with tweet.read users.read and add only required scopes such as bookmark.read. Leave tweet.write, dm.write, media.write, list.write, and other write scopes absent until there is a clear request and approval. offline.access issues a refresh token; use it only when persistent access is necessary and protect the resulting token cache.

Connect the MCP client and verify login

Install Node.js if npx is unavailable. Configure the client with command and arguments npx -y @xdevplatform/xurl mcp https://api.x.com/mcp; pass CLIENT_ID and CLIENT_SECRET as local server environment. On first launch, the bridge opens a browser for PKCE sign-in. Before authorizing, check which X account is active in that browser, because that exact account grants access. Headless systems require X’s documented out-of-band flow, xurl auth oauth2 --headless.

After login, test only a harmless read tool. Confirm the client connects, sees the expected tools, and exposes no write permissions you did not request. X documents Cursor as a compatible client; other MCP-capable clients may work when they support the documented stdio or remote HTTP setup. A successful technical connection is not a permission increase.

Secure the data path, prompt injection, and changes

Tool results flow from X to api.x.com/mcp, through xurl or the client, and then — when the client includes them — to the language model. With hosted models, content can therefore also reach the model provider. Before production, check whether search results, profile information, bookmarks, or private results can enter logs, history, or training. Use test accounts and non-sensitive data while that question is unresolved.

Posts, handles, profile text, and search results can impersonate instructions. Treat them as data. A result must not request broader scopes, token disclosure, more data retrieval, or Post publication. That is prompt injection. For every mutation, an accountable person verifies account, text, recipient, IDs, and expected side effect. Have the agent present a plan first and approve the individual action outside tool output.

Observe limits and complete the review

Read x-rate-limit-limit, x-rate-limit-remaining, and x-rate-limit-reset response headers. Cache results, paginate, and retrieve only needed data. On a 429, wait for reset and reduce the rate; blind retries make the workflow worse. Writes also have limits and can be stricter. After testing, record the App, client, connected account, scopes, token location, approved tool families, and the person who approves changes. This keeps X API MCP a controlled general X API connection rather than confusing it with the separate Ads MCP.