Skip to main content
Two MCP (Model Context Protocol) servers are available for working with X from AI tools:

X MCP — X API

Connect MCP-compatible AI tools such as Grok and Cursor directly to the X API. The model can then search the full archive, look up users, manage bookmarks, fetch trends and news, and draft Articles — all with your own X account’s permissions. The X API exposes a hosted Streamable HTTP MCP server at https://api.x.com/mcp (protocol 2025-06-18, serverInfo: xmcp). It advertises standard MCP OAuth discovery metadata, so MCP clients with native OAuth support can connect directly using your X app’s OAuth 2.0 Client ID. For clients without native OAuth support (or headless and multi-account workflows), you can also connect through the optional open-source xurl mcp local bridge.

Capabilities at a glance

How it works

api.x.com/mcp advertises standard MCP OAuth discovery (RFC 9728 Protected Resource Metadata and RFC 8414 Authorization Server Metadata):
  • An unauthenticated POST https://api.x.com/mcp returns 401 Unauthorized with WWW-Authenticate: Bearer resource_metadata="https://api.x.com/.well-known/oauth-protected-resource".
  • Protected Resource Metadata is served at https://api.x.com/.well-known/oauth-protected-resource (and the RFC 9728 path variant https://api.x.com/.well-known/oauth-protected-resource/mcp), advertising authorization_servers: ["https://api.x.com"], bearer_methods_supported: ["header"], and the supported OAuth 2.0 scopes.
  • Authorization Server Metadata is served at https://api.x.com/.well-known/oauth-authorization-server, advertising authorization_endpoint (https://x.com/i/oauth2/authorize), token_endpoint (https://api.x.com/2/oauth2/token), PKCE (S256), authorization_code and refresh_token grants, and token endpoint auth methods none (public PKCE client) and client_secret_basic.
There is no dynamic client registration (registration_endpoint is not advertised), so you still create your own OAuth 2.0 app in the X Developer Console and provide its Client ID to your MCP client. If your MCP client does not support native MCP OAuth with a pre-registered Client ID, you can run the optional xurl mcp local stdio bridge instead — it handles the OAuth 2.0 PKCE login and token refresh locally and forwards requests over HTTPS with a fresh Bearer token.

Getting started

Pick one of three routes:
  • Native OAuth 2.0 (recommended — direct URL). Point an OAuth-capable MCP client directly at https://api.x.com/mcp with your X app’s OAuth 2.0 Client ID. The client discovers the OAuth endpoints automatically, runs OAuth 2.0 PKCE (S256), and refreshes tokens. Works for reads and writes with your account’s scopes.
  • App-only Bearer (direct URL, read-only). Paste your app’s Bearer token into an Authorization header on the MCP client. No browser login; read-only endpoints only, with no user context (can’t act as you).
  • Optional: xurl mcp bridge (local stdio). For MCP clients that don’t support native OAuth with a pre-registered Client ID (or headless / multi-account setups), a local bridge handles the OAuth 2.0 PKCE login and auto-refreshes tokens.

Native OAuth 2.0 setup

  1. Create or reuse an X app in the X Developer Console with OAuth 2.0 enabled.
  2. Choose the app type: Native App (public client, PKCE only). Confidential clients (Web App / Automated App) also work with clients that use client_secret_basic (such as Grok Build), but never client_secret_post, which X rejects.
  3. Register the callback URI for your client:
  1. Copy your OAuth 2.0 Client ID from the app’s Keys and tokens page (the long string, not the numeric app ID).

App-only Bearer setup (read-only)

  1. Create an X app in the X Developer Console.
  2. Copy your App-only Bearer token from the app’s Keys and tokens page.
  3. Point your client at https://api.x.com/mcp with the token as an Authorization header — see App-only (direct URL) below.

Optional: xurl mcp bridge setup

Use this route if your MCP client does not support native MCP OAuth with a pre-registered Client ID, or if you want headless / multi-account CLI auth:
  1. Create an X app with OAuth 2.0 enabled.
  2. Register the redirect URI http://localhost:8080/callback on the app (required for the first-run browser login). To use a different one, set REDIRECT_URI and register that instead.
  3. Copy your CLIENT_ID and CLIENT_SECRET — you’ll put them in the client config. If you ever run xurl auth oauth2 manually (e.g., the headless flow below), export them as environment variables in that shell first — the login fails in the browser without them.
  4. Have Node.js installed (for npx), or install xurl:
First login needs a browser. On a headless/remote box, authenticate out-of-band first with xurl auth oauth2 --headless (paste-a-code flow), then the bridge just reuses the cached token. See Headless.

Connect your client

1. Grok Build (CLI)

Add to ~/.grok/config.toml (for native OAuth, keys under .oauth must be camelCase):
For Native OAuth, include offline.access in scopes so tokens refresh automatically, and pick only the X API scopes your agent needs (from the server’s advertised scopes_supported). No secret is needed with a Native App; if you use a confidential app, add clientSecretEnvVar = "X_MCP_CLIENT_SECRET" and export that variable in the same shell. Run grok → /mcps → select xapi → press i to complete the browser consent. Verify and list:

2. Grok (web)

Go to grok.com/connectors → New Connector → Custom:
  • Server URL: https://api.x.com/mcp
  • Client ID: your OAuth 2.0 Client ID
  • Client Secret: leave blank (Native App)
  • Token Auth Method: none (PKCE only)
  • Leave the auto-discovered OAuth endpoints as-is, pick the scopes you want (include offline.access for refresh), and complete the X consent screen.

3. Cursor

Create ~/.cursor/mcp.json (global, all projects) or .cursor/mcp.json (this project only). Because api.x.com/mcp does not support dynamic client registration, configure Cursor’s auth object with your own X app’s OAuth 2.0 CLIENT_ID (with http://localhost:8787/callback registered on your X app for Cursor Desktop, and https://www.cursor.com/agents/mcp/oauth/callback if signing in from Cursor Web or Cloud Agents). Cursor reads the server’s OAuth discovery metadata automatically and authenticates with PKCE:
Include "offline.access" in auth.scopes so Cursor receives a refresh token (you can also use "${env:X_MCP_CLIENT_ID}" interpolation instead of hardcoding CLIENT_ID). Omit CLIENT_SECRET for a Native App (public client). Then open Cursor → Settings → MCP, sign in when prompted, and confirm xapi shows a green dot and its tools.

Authentication

OAuth 2.0 user context (native MCP discovery)

When an unauthenticated client sends POST https://api.x.com/mcp, the server responds with 401 Unauthorized and:
Clients follow standard MCP OAuth discovery from there:
  1. Fetch Protected Resource Metadata from https://api.x.com/.well-known/oauth-protected-resource (or https://api.x.com/.well-known/oauth-protected-resource/mcp), which returns resource: "https://api.x.com/mcp", authorization_servers: ["https://api.x.com"], bearer_methods_supported: ["header"], and the supported X API scopes.
  2. Fetch Authorization Server Metadata from https://api.x.com/.well-known/oauth-authorization-server, which returns authorization_endpoint: "https://x.com/i/oauth2/authorize", token_endpoint: "https://api.x.com/2/oauth2/token", code_challenge_methods_supported: ["S256"], grant_types_supported: ["authorization_code", "refresh_token"], and token_endpoint_auth_methods_supported: ["none", "client_secret_basic"].
  3. Run OAuth 2.0 Authorization Code + PKCE (S256) using your pre-registered X app’s client_id. Include offline.access in your scopes so tokens refresh automatically.
Because X keeps a single live OAuth grant per (app, user), signing in from a second client with the same app revokes the first client’s tokens. Use one X app per client if you connect multiple clients at once.

App-only (direct URL)

For read endpoints, you can point a client straight at the URL with a static App-only Bearer token. This is useful for clients that support remote MCP with custom headers:
Trade-off: no auto-refresh and no user context (no actions as you). Use OAuth 2.0 user context for full functionality.

Optional xurl mcp bridge

For clients without native pre-registered-client OAuth support, xurl mcp runs locally via npx (or an installed xurl binary) and exposes a stdio JSON-RPC channel while forwarding requests to https://api.x.com/mcp. Resolution order for credentials: CLIENT_ID/CLIENT_SECRET env vars → the active app in ~/.xurl. The bridge caches tokens in ~/.xurl and refreshes them automatically (including a forced refresh after a 401). All diagnostics go to stderr; stdout stays a clean JSON-RPC channel. With no cached token, the bridge prints to stderr and opens your browser:
The MCP handshake is held until you finish — that’s why clients using the bridge need a generous startup_timeout_sec.

Headless / remote machines

No reachable browser? Authenticate once out-of-band with xurl, then start the client using the xurl mcp bridge:

Multiple apps & accounts (xurl mcp)

The OAuth login authorizes whichever X account is logged in when the browser opens — not necessarily the account that owns the app. If you’re posting on behalf of a secondary/bot account, switch to that account in your browser before completing the login (or use -u with xurl mcp to pick a previously authorized user).
In a client config, add "--app", "my-app" or "-u", "alice" to args.

Read-only mode

Add ?read_only=true to the MCP URL to make a connection read-only. It works on both the X MCP (https://api.x.com/mcp?read_only=true) and the X Ads MCP (https://ads-api.x.com/mcp?read_only=true). On a read-only connection:
  • Only read tools are offered. Tools that post, send messages, or create, change, or delete anything are left out of the tool list.
  • Write tools are refused by the server. A call to a tool that was left out fails, even if your token has write scopes.
  • The client is told at connect time. The server’s initialize response includes instructions saying the connection is read-only, which MCP clients can pass on to the model.
OAuth scopes still apply to the read tools that remain — each one needs the scopes its endpoint requires. A read tool is one that makes a GET request to the API, so a tool that uses another method is left out even if it changes nothing (for example, estimate_audience on the X Ads MCP). In any client config above, add the parameter to the URL you already use:
Accepted spellings and values: The name can be read_only, readonly, or read-only, in upper or lower case. Any value other than false turns read-only mode on, including no value at all. Only false (in any case) or leaving the parameter off gives the full tool list.

xurl mcp bridge configuration reference

These settings apply when using the optional xurl mcp local bridge: Advanced env overrides (rarely needed): AUTH_URL, TOKEN_URL, API_BASE_URL, INFO_URL.

Verify & troubleshoot

Security & best practices

  • Treat ~/.xurl and access tokens as secrets — don’t paste them into chats, logs, or shared configs. Prefer per-project .mcp.json/.grok/config.toml that reference env vars over committing raw secrets.
  • Use a dedicated app for MCP with only the scopes you need.
  • Writes count against rate limits (bookmarks, article_publish) and are stricter than reads; expect occasional 429s and back off.
  • Keep credentials local — whether connecting directly via OAuth 2.0 PKCE or through the optional xurl mcp bridge, requests authenticate over TLS to api.x.com with Bearer tokens.

X hosts an MCP server for the X API documentation at https://docs.x.com/mcp. Connect it to your AI tool to search and read documentation pages without leaving your workflow.

Available tools

Configuration

Add the docs MCP server to your MCP client configuration:
This is useful when you’re building with the X API and want your AI assistant to look up endpoint details, authentication guides, or code examples on the fly.

Using both servers together

You can connect both MCP servers simultaneously. This gives your AI assistant the ability to both look up documentation and call the API. Grok Build (~/.grok/config.toml):
Example
Cursor (~/.cursor/mcp.json or .cursor/mcp.json):
Example

OpenAPI specification

The machine-readable API specification for all X API v2 endpoints.
You can use it to auto-generate API clients, import into Postman, feed into custom AI agents, or validate request/response schemas.