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 athttps://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/mcpreturns401 UnauthorizedwithWWW-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 varianthttps://api.x.com/.well-known/oauth-protected-resource/mcp), advertisingauthorization_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, advertisingauthorization_endpoint(https://x.com/i/oauth2/authorize),token_endpoint(https://api.x.com/2/oauth2/token), PKCE (S256),authorization_codeandrefresh_tokengrants, and token endpoint auth methodsnone(public PKCE client) andclient_secret_basic.
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/mcpwith 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
Authorizationheader on the MCP client. No browser login; read-only endpoints only, with no user context (can’t act as you). - Optional:
xurl mcpbridge (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
- Create or reuse an X app in the X Developer Console with OAuth 2.0 enabled.
- 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 neverclient_secret_post, which X rejects. - Register the callback URI for your client:
- 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)
- Create an X app in the X Developer Console.
- Copy your App-only Bearer token from the app’s Keys and tokens page.
- Point your client at
https://api.x.com/mcpwith the token as anAuthorizationheader — 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:
- Create an X app with OAuth 2.0 enabled.
-
Register the redirect URI
http://localhost:8080/callbackon the app (required for the first-run browser login). To use a different one, setREDIRECT_URIand register that instead. -
Copy your
CLIENT_IDandCLIENT_SECRET— you’ll put them in the client config. If you ever runxurl auth oauth2manually (e.g., the headless flow below), export them as environment variables in that shell first — the login fails in the browser without them. -
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):
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 togrok.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.accessfor 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:
"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 sendsPOST https://api.x.com/mcp, the server responds with 401 Unauthorized and:
- Fetch Protected Resource Metadata from
https://api.x.com/.well-known/oauth-protected-resource(orhttps://api.x.com/.well-known/oauth-protected-resource/mcp), which returnsresource: "https://api.x.com/mcp",authorization_servers: ["https://api.x.com"],bearer_methods_supported: ["header"], and the supported X API scopes. - Fetch Authorization Server Metadata from
https://api.x.com/.well-known/oauth-authorization-server, which returnsauthorization_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"], andtoken_endpoint_auth_methods_supported: ["none", "client_secret_basic"]. - Run OAuth 2.0 Authorization Code + PKCE (
S256) using your pre-registered X app’sclient_id. Includeoffline.accessin your scopes so tokens refresh automatically.
(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: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:
startup_timeout_sec.
Headless / remote machines
No reachable browser? Authenticate once out-of-band withxurl, 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)."--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
initializeresponse includes instructions saying the connection is read-only, which MCP clients can pass on to the model.
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:
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
~/.xurland access tokens as secrets — don’t paste them into chats, logs, or shared configs. Prefer per-project.mcp.json/.grok/config.tomlthat 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 occasional429s and back off. - Keep credentials local — whether connecting directly via OAuth 2.0 PKCE or through the optional
xurl mcpbridge, requests authenticate over TLS toapi.x.comwith Bearer tokens.
Docs MCP — documentation search
X hosts an MCP server for the X API documentation athttps://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: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/mcp.json or .cursor/mcp.json):
Example