/x-api-mcp-guide

name: X MCP guide
description: >-
  ALWAYS read this when a user connects the X plugin or any X MCP, before using
  any X connection, and again on any X error. Do not call an X tool until this
  file has been read in the current turn. On first connect, confirm X tools are
  available, fetch get_usage_credits BEFORE any user-facing text, then send the
  congrats + capabilities message. Never tell the user to buy credits until that
  check returns ~$0 or a job would exceed the balance. If X is connected but
  tools are missing (tools=0, user-X-* not found), that is a setup failure — not
  a paywall. Estimate the cost of every X call before making it and confirm with
  the user before anything expensive.

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. Never tell them to create an app, Project, or Production env except the quoted [error 2](#2-account-not-ready) steps.

**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.

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):

{
  "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”. Do **not** congrats just because this is `> 0` (returning sessions still have leftover free grants). 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 / congrats 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:** skip congrats. 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.

**Congrats** only if `{credits}` is above $0 **and** they **just connected in this chat** (Connect completed this turn, first successful credits read right after signing in). Leftover `free_balance` on a later session is not a new gift — skip congrats.

If they just connected and `{credits}` is above $0, lead with:

> Congrats, you've received free X API credits to get started!

Then:

> 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 > > 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.

If they did **not** just connect this tur