fix(x): clarify conflicting X MCP credit and billing guidance

Leggi third_party/x/skills/x-api-mcp-guide/SKILL.md insieme alla sezione della guida di Grok Bot collegata sugli errori del connettore X. Chiarisci l’ambito di fatturazione e le indicazioni sugli errori di credito per le letture pubbliche ospitate, le richieste ospitate ai connettori privati e le connessioni MCP locali manuali. Il lavoro è completato quando un lettore può determinare le indicazioni applicabili a ciascun ambito senza incontrare istruzioni contraddittorie.

Summary

The X MCP guide and Cursor's Grok Bot help give conflicting instructions for X developer credits. The guide applies broadly to the X plugin and any X MCP, states that all X tools are free, and prohibits checking credits or suggesting a credit purchase, including during bulk reads. The help page says the private X connector uses the user's developer account and requires X API credits. This makes it unclear which billing scope an agent should follow and can cause misleading cost or troubleshooting advice.

This report requests clarification of the documentation's scope. It does not establish a backend billing defect or claim that hosted Grok Bot's built-in public reads are charged.

Steps to reproduce

1. Open the X plugin from the Cursor marketplace and follow its source link to the guide at the baseline below.
2. Read the guide's description (lines 3–14), Ground rules (line 22), Billing (lines 30–32), and Built-in public reads (lines 59–61). The description includes “any X MCP”; Billing says “Every X tool is free” and directs agents to skip credit checks and purchase advice.
3. Read the Grok Bot How Tos section for a connected X plugin whose bookmarks, DMs, or timeline fail. It distinguishes built-in public reads from private connector requests, then tells users to check X developer credits, buy prepaid credits if needed, and retry. It also describes a known starter-credit provisioning issue.
4. Compare the instructions for the private connector. The guide prohibits the credit troubleshooting that the help page recommends. Also check whether the broad MCP trigger is intended to cover a manually configured local CLI connection or only the hosted Bot environment.

These documentation steps were executed during this investigation and require no X account calls or purchases.

Expected behavior

The plugin guide and official help should agree on when X developer credits are required and what an agent should do on a credit-related failure. The scope should distinguish hosted Bot built-in public reads, hosted Bot private connector requests, and manual local MCP connections wherever their billing treatment differs. A broad MCP trigger should not leave users or agents inferring an unverified billing exemption.

Actual behavior

The current marketplace-linked guide prohibits credit checks and purchase advice even for bulk pagination, while the current help page recommends those actions for private connector failures. The guide's Grok Bot context does not resolve that direct private-connector contradiction, and its broad description leaves the manual MCP boundary unclear.

Supporting historical execution evidence was supplied as normalized records by a separate test coordinator; it was not re-executed for this report. In a manually configured CLI OAuth x connection using the plugin's public endpoint/client configuration, two successful search_posts_all calls returned 10 and 8 distinct primary posts. Separately bracketed credit reads showed relative developer-credit decreases of $0.05 and $0.04. Later checks more than two minutes after each search retained those balances; the coordinator also reported an independent Developer Console readback with the same combined $0.09 decrease. The console and MCP absolute balance displays differed by one cent for an unproved reason; only changes measured on the same surface are compared here.

The supplied query inputs were from:USGSVolcanoes -is:retweet -is:reply and from:NASAGoddard -is:retweet -is:reply, each with max_results: 10, post.fields: id, sort_order: recency, no requested expansions, and no pagination. No personal API key was used. These are bounded balance observations, not per-request invoices: concurrent account-wide activity and earlier fetches were not fully audited or excluded. Hosted Bot private calls and zero-credit behavior were not tested. The raw private test streams are no longer retained; the normalized observations above are the supplied execution evidence.

Evidence

• Expected source: The plugin guide's billing and troubleshooting instructions and the official help's private-connector instructions should describe a consistent scope; the marketplace and help are linked in the reproduction steps.
• Failure source: The marketplace-linked guide at the inspected revision and the help section give opposite credit-troubleshooting instructions for the private connector.
• Evidence provenance: observed
• Local verification: reproduced
• Reproduction completeness: complete

The documentation contradiction was reproduced by fresh source and help inspection. Supporting historical CLI balance observations were supplied by the separate test coordinator and have the attribution limits stated above. No new X calls or runtime billing reproduction was run.

X API pricing currently lists post reads at $0.005 per resource, consistent with the supplied relative deltas, and documents resource deduplication. The credit endpoint schema describes developer-platform payer balances. Neither source establishes an exemption or backend eligibility rule for this plugin's OAuth client. Cursor model usage is separate from these X developer credits.

Restoration check

Read the same marketplace-linked guide and official help together. A reader should be able to determine the applicable billing scope and the correct next step for a private-connector credit failure without contradictory instructions. The guide should also make clear whether its no-cost/no-credit-check rule applies to manual local MCP connections. Retain any valid included hosted Bot behavior; no new chargeable account tests are needed to verify that these documentation instructions agree.

Runtime or environment

• Fresh default-branch and marketplace source baseline: cursor/plugins main, commit 9580c23696ac8d7abed0c166f2f9918800afb819; X plugin manifest version 2.10.0. The repository has no published GitHub releases or tags.
• Supplied historical runtime: Cursor CLI 2026.10.22-27dcf5f on macOS arm64, exact OS version not measured, Ask mode, model grok-4.7-low; updater reported current at the time of the tests.
• Supplied manual connection: HTTP/OAuth server x at https://api.x.com/mcp; the test coordinator compared the installed configuration's public fields with the plugin's mcp.json and reported a matching public client. No auth tokens or account identifiers are included.

Triage assessment

• Impact level: P2
• Assessment status: supported
• Impact basis: Conflicting financial and troubleshooting instructions can cause agents to give misleading cost guidance or omit a documented step for private-connector failures. The supplied local MCP observations show a bounded $0.09 developer-credit decrease; hosted Bot billing and broader affected reach remain unverified.
• Workaround status: unverified
• Workaround basis: Reading the separate help and pricing pages exposes the conflict, but this investigation did not establish a single verified billing/troubleshooting rule for all three environments. No account or purchase workaround was tested.