Skip to content

Cursor plugin specification and official plugins

TypeScript

Request calls scopes and document scheduled-call tools.

Paul Vann58994c60919f
diff --git a/third_party/x/.cursor-plugin/plugin.json b/third_party/x/.cursor-plugin/plugin.json
index 9ef3293c..afeabbbe 100644
--- a/third_party/x/.cursor-plugin/plugin.json
+++ b/third_party/x/.cursor-plugin/plugin.json
@@ -1,11 +1,11 @@
{
"name": "x",
"displayName": "X",
- "version": "2.6.6",
+ "version": "2.7.0",
"minClientVersions": {
"cursor": "3.13.0"
},
- "description": "Search posts, read timelines, pull trends, manage bookmarks, and access X Chat.",
+ "description": "Search posts, read timelines, pull trends, manage bookmarks, access X Chat, and schedule X calls.",
"author": {
"name": "Cursor",
"email": "[email protected]"
@@ -23,6 +23,7 @@
"news",
"lists",
"bookmarks",
+ "calls",
"chat",
"social",
"mcp"
diff --git a/third_party/x/CHANGELOG.md b/third_party/x/CHANGELOG.md
index 9f690c80..60b22dd1 100644
--- a/third_party/x/CHANGELOG.md
+++ b/third_party/x/CHANGELOG.md
@@ -2,6 +2,12 @@
All notable changes to this plugin will be documented here.
+## 2.7.0 — Scheduled X calls
+
+- Requested `calls.read` and `calls.write` so agents can list, schedule, update, cancel, and RSVP to X calls on `https://api.x.com/mcp`.
+- The guide covers `schedule_call`, `list_scheduled_calls`, `get_scheduled_call`, `update_scheduled_call`, `cancel_scheduled_call`, and `respond_to_scheduled_call`. Schedule, update, cancel, and RSVP only when the owner asked. Missing call tools while other X tools work means reconnect, not a new Project or App.
+- Existing installs need to sign in to X again to pick up the new scopes.
+
## 2.6.6 — media.write scope
- Requested `media.write`.
diff --git a/third_party/x/README.md b/third_party/x/README.md
index 965db845..501045c9 100644
--- a/third_party/x/README.md
+++ b/third_party/x/README.md
@@ -2,7 +2,7 @@
Cursor plugin that connects agents to the [X API](https://docs.x.com) through X's official hosted [Model Context Protocol](https://modelcontextprotocol.io/) server at `https://api.x.com/mcp`.
-This plugin signs you in with OAuth as your own X account. It is no longer read-only: alongside searching and reading public X data, agents can manage your lists, bookmarks, blocks, and mutes, and call X Chat endpoints.
+This plugin signs you in with OAuth as your own X account. It is no longer read-only: alongside searching and reading public X data, agents can manage your lists, bookmarks, blocks, and mutes, call X Chat endpoints, and schedule X calls.
## Install
@@ -37,6 +37,8 @@ Or run `/add-plugin x` in chat.
"bookmark.write",
"dm.read",
"dm.write",
+ "calls.read",
+ "calls.write",
"media.write",
"developer.billing.write",
"developer.write",
@@ -61,6 +63,7 @@ Or run `/add-plugin x` in chat.
| Bookmarks | Read and manage your bookmarks |
| Blocks & mutes | Read your blocks and mutes; add or remove blocks |
| Chat | List conversations, fetch events, send messages, typing, and read receipts; list, open, and accept message requests |
+| Calls | List and open scheduled X calls; schedule, update, or cancel one; RSVP to an invitation |
| Developer account | Read your X developer account settings and credit balance |
Posting is not included: the plugin does not request the `tweet.write` scope, so agents cannot publish posts as you.
@@ -73,7 +76,7 @@ Requests run in your user context, so they count against your account's rate lim
## Scopes requested
-`tweet.read`, `users.read`, `follows.read`, `space.read`, `mute.read`, `like.read`, `list.read`, `list.write`, `block.read`, `block.write`, `bookmark.read`, `bookmark.write`, `dm.read`, `dm.write`, `media.write`, `developer.billing.write`, `developer.write`, `offline.access`
+`tweet.read`, `users.read`, `follows.read`, `space.read`, `mute.read`, `like.read`, `list.read`, `list.write`, `block.read`, `block.write`, `bookmark.read`, `bookmark.write`, `dm.read`, `dm.write`, `calls.read`, `calls.write`, `media.write`, `developer.billing.write`, `developer.write`, `offline.access`
## X documentation search
diff --git a/third_party/x/mcp.json b/third_party/x/mcp.json
index 8a2ccedb..bdb1b4b3 100644
--- a/third_party/x/mcp.json
+++ b/third_party/x/mcp.json
@@ -20,6 +20,8 @@
"bookmark.write",
"dm.read",
"dm.write",
+ "calls.read",
+ "calls.write",
"media.write",
"developer.billing.write",
"developer.write",
diff --git a/third_party/x/skills/x-api-mcp-guide/SKILL.md b/third_party/x/skills/x-api-mcp-guide/SKILL.md
index 54b59fc9..dc366ef3 100644
--- a/third_party/x/skills/x-api-mcp-guide/SKILL.md
+++ b/third_party/x/skills/x-api-mcp-guide/SKILL.md
@@ -13,7 +13,10 @@ description: >-
live in THIS file: clone xchat-grokbot-helper and run xchat_lite.py locally —
do not wait for the user to name the helper or another skill. Missing chat
tools or dm.read/dm.write while other X tools work: reconnect the X plugin.
- Estimate every X call and confirm before anything expensive.
+ Scheduled X calls use schedule_call, list_scheduled_calls, get_scheduled_call,
+ update_scheduled_call, cancel_scheduled_call, and respond_to_scheduled_call.
+ Missing those tools or calls.read/calls.write while other X tools work:
+ reconnect the X plugin. Estimate every X call and confirm before anything expensive.
---
# X MCP guide
@@ -97,6 +100,7 @@ Once tools exist and `{credits}` is cached, send this once. Adapt the wording to
> - **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.
+> - **Calls** — list the X calls on your calendar, schedule or change one, and RSVP to an invitation
>
> You have about $X.XX in credits.
>
@@ -136,6 +140,8 @@ Do **not** treat `get_usage_credits` not found as #2 by itself. If other `user-X
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`.
+Missing **call** tools (`schedule_call`, `list_scheduled_calls`, …) while other X tools work is **not** #2. That is [X call scopes](#x-call-scopes) — reconnect for `calls.read` / `calls.write`.
+
**When (fallback):** `client-forbidden`; `user-not-enrolled`; `client-not-enrolled`; Client Forbidden; 403 on timeline / mentions / search / bookmarks after Connect.
**Say:**
@@ -202,6 +208,16 @@ Then follow [error 1](#1-sign-in-failed) or [error 2](#2-account-not-ready). Do
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.
+### X call scopes
+
+**When:** the user wants to list, schedule, change, cancel, or RSVP to an X call, other X tools work, but the call tools are missing or a call 403s for `calls.read` / `calls.write`.
+
+**Say:**
+
+> X calls need an extra sign-in. Reconnect the X plugin in this chat and approve access to your calls. Then I'll retry. Don't paste keys or tokens.
+
+Do not tell them to create a Project or App. Do not ask for a Bearer token. After reconnect, follow [Scheduled calls](#scheduled-calls).
+
## 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.
@@ -259,6 +275,8 @@ Every X call can charge the user. Estimate the cost **before** calling. Read [re
X Chat is free for this plugin. X Chat reads (`GET /2/chat/*`) and public key lookups are free everywhere, in Grok Bot and in Cursor. Do not estimate a cost, ask for confirmation, or check or require credits for `get_chat_conversations`, `get_chat_message_requests`, `get_chat_message_request`, `accept_chat_message_request`, `get_chat_conversation`, `get_chat_conversation_events`, public key lookups, `add_conversation_keys`, `send_chat_message`, typing indicators, or marking a conversation read.
+Scheduled X calls are not in [references/pricing.md](references/pricing.md). Check the live pricing table before one. If `calls` is not listed, do not invent a price. Schedule, update, cancel, and RSVP still need a yes, because they change the owner's calendar and can email invitees.
+
The live payload:
- `eventTypePricing` — price **per resource returned** (each post, user, news story…).
@@ -339,6 +357,26 @@ When they ask what they can do, re-fetch `{credits}`, say how many they have lef
- Bookmarks: list `{me}`. Save: parse status id, create bookmark.
- One post: parse status id, lookup.
- X Chat / inbox / DMs / message requests: [X Chat](#x-chat). Clone the helper if missing — do not ask the user to find it. Use a [saved key](#saved-key) or secret-request the Chat PIN only. Owner must approve outbound text unless they already said to send or reply. Accept a request only when they said to accept.
+- X calls on the calendar: [Scheduled calls](#scheduled-calls). List or open when they ask. Schedule, update, cancel, or RSVP only when they asked.
+
+## Scheduled calls
+
+These tools are the owner's X Calls calendar. They are not X Chat and not a livestream. Do not clone the Chat helper, ask for a Chat PIN, or send a chat message to schedule a call.
+
+| Tool | Does | Scope |
+| --- | --- | --- |
+| `list_scheduled_calls` | X calls on the calendar in a window (defaults to the next 24 hours, at most 7 days) | `calls.read` |
+| `get_scheduled_call` | One scheduled call by `id` | `calls.read` |
+| `schedule_call` | Put a call on the calendar and invite people | `calls.write` |
+| `update_scheduled_call` | Move, rename, or re-invite a call the owner organizes | `calls.write` |
+| `cancel_scheduled_call` | Cancel a call the owner organizes | `calls.write` |
+| `respond_to_scheduled_call` | RSVP. `response` is `accepted`, `declined`, or `tentative` | `calls.write` |
+
+List or open a call when they ask. Schedule, update, cancel, or RSVP only when they asked, and repeat the time, who is invited, and the RSVP before you do it. A write can email invitees.
+
+`id` is the scheduled-call id from a list or schedule result. On a recurring call, pass `scope` and `occurrence_start_time` only when they said which occurrences: one, this one and the ones after it, or all of them. Default is all.
+
+If the tools are missing or a call returns 403 for `calls.read` / `calls.write`, that is [X call scopes](#x-call-scopes). Reconnect. Do not create a Project or App.
## X Chat
@@ -560,6 +598,8 @@ If `add_conversation_keys` returns `UNAUTHORIZED_REQUESTING_USER` or similar: yo
- Quote `total_balance` or `free_grants` as “you received $X”. Gift size by plan is the starter table, and only if they ask **and** you know the plan. Always say remaining balance (`You have about $X.XX in credits.`, including $0.00).
- Treat tools=0 / `user-X-*` not found as a paywall. That is [error 2](#2-account-not-ready).
- Treat missing Chat tools as “create a Project and App.” If other X tools work, that is [X Chat scopes](#x-chat-scopes) — reconnect.
+- Treat missing call tools as “create a Project and App.” If other X tools work, that is [X call scopes](#x-call-scopes) — reconnect.
+- Schedule, update, cancel, or RSVP to an X call unless the owner asked. Do not use the X Chat helper for calls.
- Wait for the user to name `xchat_lite`, the helper repo, or a second X Chat skill. Clone it yourself.
- Treat a reply as accepting a message request. Accept only with `accept_chat_message_request`, and only when the owner said to accept.
- Call `get_chat_message_request` while scanning requests. That marks them delivered. List with `get_chat_message_requests`.