企业官网建设流程全解析

X API MCP 接入指南：用 Cursor 的 X 插件以 OAuth 身份连接官方 MCP 服务器

【免费下载链接】pluginsCursor plugin specification and official plugins项目地址: https://gitcode.com/GitHub_Trending/plugins125/plugins

本篇技术指南围绕本仓库 third_party/x/README.md 展开，完整讲解 Cursor 官方 X 插件（X API MCP）的安装方式、MCP 配置、OAuth 认证流程与权限作用域、Agent 能力范围，并结合仓库内的 X MCP 使用指南技能 与 定价参考，深入剖析连接时序、信用额度读取、三大典型错误处理、成本预估模型与预算分档工作流。读完本文，你将掌握如何让 Cursor 中的 Agent 以你自己的 X 账号身份安全地搜索帖子、读取时间线、管理书签与列表，并在每个 API 调用前做出成本判断。

插件定位：官方托管的远程 MCP，不再需要本地桥接

X 插件是本仓库third_party目录下的官方集成插件之一（根 README 中将其归类为 Integrations，描述为 "Search posts, read timelines, pull trends, and manage bookmarks"）。它的核心设计是：直接对接 X 官方托管的 Model Context Protocol 服务器，地址为https://api.x.com/mcp，Agent 无需在本地搭建任何代理或桥接进程。

与 1.0.0 时代通过X_BEARER_TOKEN环境变量、使用 app-only Bearer 路由的只读方案不同（见 CHANGELOG.md 的 2.0.0 版本记录），当前版本采用OAuth 用户登录：插件内置 X 官方的 OAuth client ID，用户在首次使用时通过浏览器完成 X 账号授权。这意味着插件不再是只读的——除了搜索和读取公开数据，Agent 还可以管理你的列表（lists）、书签（bookmarks）、屏蔽（blocks）与静音（mutes）列表。

安装插件

在 Cursor 中安装 X 插件有两种途径：

1. 打开Cursor Settings → Plugins，搜索X，点击Install，随后按提示完成 OAuth 登录；
2. 直接在聊天框中运行/add-plugin x。

安装完成后，插件通过仓库内的 mcp.json 声明 MCP 服务器配置，Cursor 会读取该文件并注册x服务器。

MCP 配置解析

插件的完整 MCP 配置如下（与仓库中 mcp.json 内容一致）：

{ "mcpServers": { "x": { "type": "http", "url": "https://api.x.com/mcp", "auth": { "CLIENT_ID": "NGdZYmo4VVp2T1BnRG55NlExOGQ6MTpjaQ", "scopes": [ "tweet.read", "users.read", "follows.read", "space.read", "mute.read", "like.read", "list.read", "list.write", "block.read", "block.write", "bookmark.read", "bookmark.write", "developer.billing.write", "developer.write", "offline.access" ] } } } }

各字段含义：

• type:http，表示这是一个基于 HTTP 传输的 MCP 服务器（即 Streamable HTTP / remote MCP），区别于本地stdio类型；
• url:https://api.x.com/mcp，X 官方托管的 MCP 服务器端点，Agent 的所有工具调用都经由该端点代理到 X API v2；
• auth.CLIENT_ID: X 官方公开发布的 OAuth client ID（NGdZYmo4VVp2T1BnRG55NlExOGQ6MTpjaQ），插件直接随包携带，用户无需自行申请或粘贴任何密钥；
• auth.scopes: OAuth 授权时向用户请求的权限作用域清单（详见下文"认证与作用域"）。

从仓库的 plugin.schema.json 可以看出，Cursor 插件清单中的mcpServers字段允许是路径、内联配置对象或两者组成的数组；本插件采用内联对象形式直接嵌入。这种"远程 HTTP + OAuth"的组合，使插件成为标准的零配置体验——不需要在用户机器上运行本地 MCP 进程，也不需要在环境变量中存放 token。

Agent 能力矩阵

插件向 Agent 开放的能力覆盖了 X API 的主要读取与管理面，README.md 中以表格形式列出的能力包括：

需要特别强调的是：发帖功能不在其中。插件没有请求tweet.write作用域，因此 Agent 无法以你的身份发布帖子（README 中明确注明 "Posting is not included"）。这一设计边界也体现在作用域清单里——15 个 scope 中没有任何写推文权限。

认证与作用域

零 token 的 OAuth 流程

无需粘贴任何 token：插件随包携带 X 的 OAuth client ID 并请求上述作用域。首次使用时，Cursor 会打开浏览器窗口，你在其中登录 X 并批准访问。由于作用域中包含offline.access，Cursor 可以自动刷新会话，因此你只需要登录一次。

请求以你的用户上下文（user context）运行，因此会占用你账号的速率限制额度。你可以随时在 X 账号的"已连接应用"设置中撤销访问权限。

作用域清单

tweet.read、users.read、follows.read、space.read、mute.read、like.read、list.read、list.write、block.read、block.write、bookmark.read、bookmark.write、developer.billing.write、developer.write、offline.access

版本演进带来的差异

从 CHANGELOG.md 可以看到作用域策略的演变：

• 2.0.0：从X_BEARER_TOKENapp-only 路线切换为 OAuth 用户登录，作用域包含billing.write，Agent 开始可以管理列表、书签、屏蔽与静音；
• 2.2.0：请求developer.write与developer.billing.write，并移除billing.write，与 X MCP 服务器在https://api.x.com/.well-known/oauth-protected-resource/mcp处发布的声明保持一致；已安装用户需要重新登录一次 X 以拾取新作用域；
• 2.3.0：开发者账号自动创建并自动发放额度（详见下文成本部分）。

连接时序与信用额度读取

X MCP 使用指南 为 Agent 规定了严格的连接时序（Connect order），要求在向用户展示任何 X 相关内容之前完成：

1. 确认 X 工具存在（工具列表 / 服务器状态）；
2. 若插件显示已连接但工具缺失，判定为"账号未就绪"错误（error 2），停止；
3. 若未登录 / 401，判定为"登录失败"错误（error 1）；
4. 调用get_users_me（请求user.fields=id,name,username,description,public_metrics）与get_usage_credits，分别缓存{me}与{credits}；
5. 然后才发送"已连接"欢迎消息。

其中get_usage_credits对应GET /2/usage/credits，是一个免费端点。其响应（金额单位为美元，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}，是预算与"余额是否约等于 $0"判断的依据；Agent 应始终告知用户剩余额度（含 $0.00 的情形）；
• data.free_balance是剩余的新手赠金，不能仅凭其大于 0 就发送祝贺——老会话仍可能残留免费赠金；由于 prepaid 可以为负，可能出现free_balance > 0而{credits}约等于 $0 并存的情况，此时以{credits}为准；
• free_grants与prepaid_balance不进入面向用户的话术。

关于新手赠金（starter credits），技能文件要求 Agent 只在用户主动询问"获得了多少"且确切知道其 Cursor 套餐时，才按套餐档次作答：

而在连接成功且余额大于 0 时，Agent 发送的欢迎消息固定包含能力清单与一句"你当前约有 $X.XX 额度"，并给出 2～3 个基于当前余额的建议任务；余额约等于 $0 时跳过祝贺语，直接提示充值入口。

三大典型错误处理

技能文件将 X 接入过程中的核心故障收敛为三类，Agent 必须匹配错误签名后输出固定话术，不得自行发散：

错误 1 — 登录失败（Sign-in failed）：未登录、连接提示、401、Unauthorized、登录循环、token 刷新失败。话术引导用户"重新在聊天中连接 X 插件，不要粘贴密钥或密码"。

错误 2 — 账号未就绪（Account not ready）：X 已连接但工具数量为 0（tools=0），或找不到user-X-*命名空间，或client-forbidden/user-not-enrolled/ 403 等签名。此时属于开发者账号未完成配置，而非付费墙。话术引导：移除并重装 X 连接 → 仍不行则前往 X 控制台创建开发者账号、确认存在 Default Project 与 App。技能明确禁止将tools=0当作缺额度的提示。

错误 3 — 额度耗尽（Out of credits）：计费请求被阻止，提示"does not have any credits"。话术引导用户前往控制台充值后重试，随后只能提供免费查询（{me}、某帖的点赞者、书签文件夹）。

此外还有两类边界情况：禁止在 Agent 浏览器/本机代替用户登录 X（不得填写用户名密码或完成 Google SSO），以及禁止索要或接受 Bearer token / API key——本插件只走 X 连接器的 OAuth 通道。技能文件的"其他错误"表还覆盖了not-authorized-for-resource（私有账号）、resource-not-found（单次重试）、429 限流（等待x-rate-limit-reset后重试一次）、5xx / 503（按服务中断处理，不得误判为额度或账号问题）等场景。

成本感知与定价模型

X MCP 的调用会产生真实费用，因此技能文件要求 Agent在每次调用前预估成本，并以 references/pricing.md 为参考（每个会话还应从console.x.com/api/credits/pricing拉取一次实时价格，实时价格优先于参考文件）。

定价模型的核心规则：

• 读取按返回对象计费：例如返回 100 条帖子 = 100 × 帖子单价；expansions展开的对象同样计费；
• 写入按成功请求计费：每种请求类型有固定费率；失败的请求不收费；
• MCP 工具调用与 v2 端点 1:1 代理，价格与所包装的端点完全一致，不存在单独的 MCP 价目表；
• 金额以美元计，$1.00 = 1,000 credits，{credits}本身已是美元金额。

关键工具的单价速查（节选自 pricing.md）：

一个显著的成本特征：读取自己的数据有折扣。*标注的端点（如/2/users/:id/tweets、/2/users/:id/mentions、/2/users/:id/bookmarks、关注/粉丝/屏蔽/静音列表等）在读取本人数据时降至$0.001/对象，比读取他人数据便宜 5～10 倍。

成本预估公式与执行阈值

预估成本 =（请求的资源数量 × 每资源单价）+ 每请求单价。max_results限制读取范围，例如一次max_results=100且展开作者信息的搜索，成本约100 × $0.005 + 100 × $0.01；每次分页都会再次计费。

技能文件给出了明确的执行纪律：

• 低于约 $0.25 且余额足够：直接执行，不啰嗦；默认把max_results控制在 10～25 之间；
• 超过约 $0.25，或涉及分页循环 / 批量任务：先停下，给出单行预估并询问"这大约花费 $X.XX，要我继续吗？"，等待用户确认；执行中若累计花费将超过预估的两倍，再次停下确认；
• 预估超过{credits}：不执行；余额约等于 $0 时只做免费查询。

成本节省要点还包括：批量查询与单条查询按对象同价（但请求次数更少、限流更少）；只请求会用到的expansions；推文带 URL 时发布成本为 $0.20 而无 URL 仅 $0.015（这解释了插件刻意不开放发帖的原因之一）。

搜索与分页

搜索操作符

技能文件给出的标准搜索操作符如下（空格表示 AND 关系；近期搜索 query 最长 512 字符，全量存档搜索最长 1,024 字符）：

from:handle to:handle @handle #tag "exact phrase" url:example.com lang:en -is:retweet -is:reply is:verified has:images has:video_link has:links conversation_id:ID

注意：应使用min_likes:/min_reposts:，而不是旧式的min_faves:/min_retweets:。

字段请求与分页

请求帖子字段时建议携带created_at,public_metrics,author_id,lang,conversation_id，用户字段携带created_at,description,public_metrics,verified,location，展开项使用expansions=author_id,referenced_tweets.id。分页通过meta.next_token映射到pagination_token，当响应中不再出现next_token时停止翻页。技能还建议优先使用近期计数、本人数据读取，最后才考虑小规模的全量存档页面（近期窗口为 7 天）。

工作流与预算分档

技能文件把常见任务收敛为可复用的工作流：主页 / 提及 / 我的帖子用{me}加适度max_results；handle 解析用用户名查询；话题研究先看近期计数再取一小页搜索结果；书签保存解析 status id 后调用创建书签；单条帖子解析 status id 后查询。

当用户询问"能做什么"时，Agent 依据{credits}从预算分档表中挑选 2～3 个建议：

任何高于当前档位的任务都必须先给预估并取得用户同意。

附带的 X 文档检索 MCP（x-docs）

除了数据 API，X 还托管了一个无需认证的开发者文档 MCP 服务器。README 建议将其与本插件并列添加，让 Agent 在工作过程中随时查阅端点细节：

{ "mcpServers": { "x-docs": { "url": "https://docs.x.com/mcp" } } }

注意该配置没有type与auth字段——它仅用于查询 X API 文档，不涉及任何用户数据或计费。

仓库结构与验证

从仓库结构看，X 插件是一个标准的 Cursor 官方插件目录（third_party/x/）：

third_party/x/ ├── assets/logo.svg # X 官方品牌标识，黑底白字风格 ├── skills/x-api-mcp-guide/ │ ├── SKILL.md # Agent 运行时行为规范（连接、错误、成本、工作流） │ └── references/pricing.md # 工具级定价参考 ├── CHANGELOG.md # 1.0.0 → 2.3.0 演进记录 ├── LICENSE # MIT 协议 ├── README.md └── mcp.json # MCP 服务器声明

该目录同时被根目录 README.md 的市场列表收录，并受仓库 scripts/validate-plugins.mjs 的校验约束——该脚本会依据 schemas/plugin.schema.json 对每个插件的 manifest 做 JSON Schema 校验，确保mcpServers等字段的声明方式合法合规。插件以 MIT 协议开源（见 LICENSE）。

小结

X 插件代表了 Cursor 集成第三方服务的一种成熟形态：远程托管的 HTTP MCP 端点 + 内置 OAuth 客户端 + 面向 Agent 的行为规范技能（SKILL.md）。它让 Agent 以用户身份完成搜索、阅读与管理操作，同时通过get_usage_credits余额检查、成本预估和预算分档机制，把"每次 API 调用都花钱"的事实显式地纳入对话流程。对开发者而言，理解 mcp.json 的作用域声明、连接时序、三大错误签名与定价模型，是安全、经济地使用该插件的前提；对插件作者而言，这份插件同时也是一个"远程 MCP + OAuth + 成本感知技能"的完整参考实现。

【免费下载链接】pluginsCursor plugin specification and official plugins项目地址: https://gitcode.com/GitHub_Trending/plugins125/plugins