x-mcp-guide

# X MCP guide This plugin uses **X MCP**. The user taps Connect and signs in with X. Developer accounts are auto-created and auto-credited. They are not setting up an API app. On a core error, stop. Name the simple issue, then the next step. Do not explain enrollment mechanics, billing internals, Connected vs enrolled, or pay-per-use. Never retry 401 / 403-enrollment / credits-blocked / missing-tools unchanged. Never ask for keys or Bearer tokens. Chat PIN is allowed only via secret-request (never pasted in chat). Never tell them to create an app, Project, or Production env except the quoted [error 2](#2-account-not-ready) steps. X Chat is in this file — [X Chat](#x-chat). Do not look for a second skill. **Never tell the user to buy, purchase, or add credits until `get_usage_credits` has returned and `{credits}` is ~$0 or the planned job would exceed it.** Do not use “you’ll need to purchase credits at https://console.x.com” (or any “buy credits first” variant) on connect or before that check. Missing tools is not a pay CTA. ## Built-in X reads When the host says public X reads need no X connection, as Grok Bot does, it reads public posts, users, search, trends, and news through its own X access and doesn't spend the user's credits. For those reads, don't ask the user to connect X, check credits, or estimate a cost. `get_usage_credits` and `get_users_me` are only on the user's X connection, so their absence next to built-in reads is not [error 2](#2-account-not-ready) or an outage. The user's own account, home timeline, bookmarks, and X Chat need their X connection and the rest of this guide. ## Connect order Do this **before any user-facing X copy**: 1. Confirm X tools exist (tool list / server status). 2. If the plugin looks connected but tools are missing, that is [error 2](#2-account-not-ready) — stop. You cannot check credits without tools. 3. If not signed in / 401, that is [error 1](#1-sign-in-failed). 4. `get_users_me` (`user.fields=id,name,username,description,public_metrics`) and **`get_usage_credits`**. Cache `id` as `{me}` and `data.total_balance` as `{credits}`. 5. Then the [On connect](#on-connect) message. ## Credit balance Call **`get_usage_credits`** (`GET /2/usage/credits`). It is free. Response (values are **USD dollars and cents**; `20.0` = $20.00): ```json { "data": { "free_balance": 20.0, "free_grants": [ { "amount": 10.0, "expires_at": "2026-11-19T02:14:28.000Z" }, { "amount": 10.0, "expires_at": "2026-11-19T16:02:51.000Z" } ], "prepaid_balance": 0.0, "total_balance": 20.0 } } ``` - **`data.total_balance`** → `{credits}`. Use this for budgets and the ~$0 check. **Always tell the user how many credits they have** (`You have about $X.XX in credits.`), including $0.00. That is remaining balance, not the welcome gift. - **`data.free_balance`** → leftover starter grant, if any. Do **not** say “you received $X”. Prepaid can be negative, so `free_balance > 0` and `{credits}` ~$0 can both be true — `{credits}` ~$0 wins. - Ignore `free_grants` and `prepaid_balance` for user-facing copy. Do not choose what to spend. Fetch it: 1. **On connect** — after tools exist, before any capabilities text. 2. **When a session starts and X calls are required** — alongside `get_users_me`. 3. **When the user asks what they can do** — ideas, a setup, a budget, remaining credits. Do not fetch on every message. ### If they ask how much they received / starter credits Do **not** dump `total_balance` or `free_grants` as the gift amount. Starter credits depend on their Cursor plan. **Only quote a row if you actually know their plan.** Do not guess. There is no Hobby / Business / other row — if you do not know the plan, say remaining `{credits}` and skip the table. | Plan | Starter credits | | ---- | --------------- | | Cursor Ultra | $100 | | SuperGrok Plus | $50 | | Cursor Pro+ | $30 | | Cursor Pro | $10 | If they ask how much they have **left**, quote `{credits}` (`total_balance`) — same number you already state on connect. ## On connect Once tools exist and `{credits}` is cached, send this once. Adapt the wording to your voice. Keep every capability bullet. **`{credits}` ~$0 always wins:** keep the bullets, say **You have $0.00 in credits**, suggest only free lookups, and **then** send them to https://console.x.com to add credits — skip “With that, we could.” Do **not** use the error-3 quote. Do not skip the $0.00 line. > You're connected to X. Here's what I can do: > > - **Your account** — your profile, home timeline, your posts, and mentions > - **Posts** — open any post from a link, and see who liked, reposted, or quoted it > - **Users** — look up any account by handle, search for users, and read their posts > - **Search** — search posts across X and count post volume on a topic > - **News & trends** — search X news stories and get trends by location > - **Bookmarks** — list, add, and remove bookmarks, and organize them into folders > - **Chat** — read and reply to X Chat, and list, open, or accept message requests (needs a Chat PIN via secret-request, not pasted here). Posting tweets is not supported. > > You have about $X.XX in credits. > > With that, we could: (2–3 ideas from the matching [By budget](#by-budget) row, using `{credits}`). > > I'll show a cost estimate before anything expensive. Always include the **You have about $X.XX** line (`total_balance`). Do **not** say “you received $X” — that is the gift size; only the starter table if they ask how much they were given **and** you know their plan. Do not mention purchasing or console.x.com unless `{credits}` is ~$0. Send it once per session. If their first message already contains an ask, send this first, then do the ask if it fits the balance. ## The three errors Match `type`, `reason`, `title`, `detail`, or the missing-tools signatures below. Then say the quoted line. For **#1 and #2**, nothing else. For **#3**, the quoted line plus the free-only follow-up. ### 1. Sign-in failed **When:** not signed in; connect prompt; 401; Unauthorized; login loop; token refresh failed. Plugin is **not** connected. **Say:** > You're not signed in to X. Reconnect the X plugin in this chat. Don't paste keys or passwords. Then I'll retry. Trigger reconnect if you can. Probe once after. If it still 401s, stop. If status is `connected` but tools=0, that is #2, not this. ### 2. Account not ready **When (primary):** X is connected but the agent has **no tools** — the developer account is not set up or not enabled. Signatures: - Server status: `X [connected]` with `tools=0` - X namespace missing (`Use GetDynamicTools to discover available servers` and no X / `user-X` namespace) - **Every** X tool missing (`user-X-get_users_me` not found **and** no other `user-X-*` tools) Do **not** treat `get_usage_credits` not found as #2 by itself. If other `user-X-*` tools work, that is a missing endpoint or an outage — follow the 5xx / could-not-read-balance copy, not “create a Default Project and App.” Missing **Chat** tools (`get_chat_conversations`, `send_chat_message`, …) while timeline/search/`get_users_me` work is **not** #2. That is [X Chat scopes](#x-chat-scopes) — reconnect for `dm.read` / `dm.write`. **When (fallback):** `client-forbidden`; `user-not-enrolled`; `client-not-enrolled`; Client Forbidden; 403 on timeline / mentions / search / bookmarks after Connect. **Say:** > X is connected, but this account isn't ready yet. Please remove and reinstall the X connection, then reconnect. If this doesn't work, please try the following: > > 1. Visiting https://console.x.com and creating a developer account > 2. Ensure you have a Default Project created in the console > 3. Ensure you have an App created in the console Do not retry in a loop. Do not search. Do not send them to pay. Do not add extra enrollment speech beyond the quoted steps. Do not use “This X account isn't set up yet. Go to https://console.x.com, register and onboard…”. ### 3. Out of credits **When:** a billed request is blocked until credits are added; “does not have any credits”; credits-blocked. **Not** a successful `get_usage_credits` with `total_balance` ~$0 — that uses the [On connect](#on-connect) $0 copy (or the ~$0 [By budget](#by-budget) row). **Not** missing tools (#2). **Say:** > You're out of credits. Go to https://console.x.com and add credits, then I'll retry. Stop. Do not retry billed calls. Cache `{credits}` as $0. After the quoted line, you may offer **only free lookups** from the ~$0 [By budget](#by-budget) row: `{me}`, likers of a post, bookmark folders. Do not offer a cheaper paid search or timeline. After they add credits, re-fetch `{credits}` before retrying. If the payload is only `usage-capped` (no enrollment reason): > You hit a limit. Try again later. If `user-not-enrolled` or `client-not-enrolled` is present, that is #2, not this. ## Edge cases If the X connector is failing, stay on errors 1–3 or the 5xx outage line. Do **not** invent another way in. ### No browser / computer sign-in **When:** you would open x.com (or console.x.com) in the agent browser or on this computer to log the user in; type their X username, password, or 2FA; complete Google SSO for them. You cannot sign into the user's X account that way. Stop. Do not navigate to login, fill a form, or ask them to type a password into the agent browser. **Say:** > I can't sign into X from this browser or computer. Use the X plugin in this chat: tap Connect on the X card and sign in there. Don't paste keys or passwords. Then follow [error 1](#1-sign-in-failed) or [error 2](#2-account-not-ready) if that is the real failure. ### No Bearer tokens / direct API **When:** the connector is missing, 401s, or has no tools, and you would ask for a Bearer token, API key, app token, `X_BEARER_TOKEN`, or an Authorization header; or call `api.x.com` yourself with a pasted secret. Do not ask. Do not accept one if they offer. This plugin is OAuth via the X connector only. **Say:** > Don't paste a Bearer token or API key. I only use the X plugin in this chat — tap Connect on the X card and sign in with X. Then follow [error 1](#1-sign-in-failed) or [error 2](#2-account-not-ready). Do not curl, set headers, or stand up a local MCP with their token. ### X Chat scopes **When:** the user wants X Chat / DMs, other X tools work, but Chat tools are missing or a Chat call 403s for `dm.read` / `dm.write`. **Say:** > X Chat needs an extra sign-in. Reconnect the X plugin in this chat and approve access (including messages). Then I'll retry. Don't paste keys, tokens, or your Chat PIN here. Do not tell them to create a Project or App. Do not ask for a Bearer token. After reconnect, follow [X Chat](#x-chat): clone the helper yourself, use a [saved key](#saved-key) or secret-request **only** the Chat PIN into `CHAT_PIN`, then read/reply. ## Other errors `not-authorized-for-resource` (private account they don't own): stop. Their own timeline/bookmarks: probe current user, retry once with that id. > I can't open that. If it's yours, reconnect X. If it's someone else's private account, I don't have access. `resource-not-found`: resolve the id, retry **once**. Never retry the same id. > Paste a handle, profile link, or post link. | They asked | You do | Else ask | | ----------------------------- | ---------------------------------- | --------------------- | | `@handle` posts | User search; one match → that `id` | Paste the profile. | | A post | Parse `/status/{id}` | Paste the post link. | | Bookmarks, timeline, mentions | Current user → that `id` | Reconnect X. | | Bookmark folder | List folders on `{me}` | Which folder? | | News | News search | What topic? | | Search | Rewrite query | What should I search? | 429 `rate-limit-exceeded`: wait for `x-rate-limit-reset`, retry once. > I'll retry in a minute. 400 `invalid-request`: fix params, don't retry unchanged. 5xx / **503** / **`get_usage_credits` missing while other X tools work**: backoff once or twice. Do not treat it as $0 credits, a missing app, or [error 2](#2-account-not-ready). Other endpoints may still work. Then say: > X's API looks like it's having an outage (this one isn't on you). Try again in a bit. If it keeps failing, check [https://developer.x.com/status](https://developer.x.com/status). Do not start billed work without a credits read; wait for a successful `get_usage_credits` or for the user to say go. 200 + `errors[]`: use `data`, skip listed ids. ## Session start When X calls are required this session: confirm tools exist, then `get_users_me` and `get_usage_credits`. | Result | Next | | ------------------------------ | ---- | | Tools missing / not found | [Error 2](#2-account-not-ready). Stop. | | Success | Cache `{me}` and `{credits}`. If `{credits}` is ~$0, use the On connect $0 copy — not error 3. Otherwise do their ask if it fits. Prefer `{me}` for timeline, mentions, bookmarks. | | Error 1 | Quoted line only. Do not search. | | Error 2 | Quoted line only. Do not search. | | Error 3 | Follow [Out of credits](#3-out-of-credits). | | 5xx / 503 | Outage copy. Not $0, not error 2. Retry later. | | 200 + `errors[]` | Keep `data`. | ## Cost awareness Every X call can charge the user. Estimate the cost **before** calling. Read [references/pricing.md](references/pricing.md) — it has the tool-by-tool price table, per-endpoint prices, free endpoints, and cost-saving tips. Once per session, fetch live pricing from https://console.x.com/api/credits/pricing (plain GET, no auth); it wins over the reference file.