把 X 官方 MCP 接进 Codex：文档、搜索和自己的 X 数据终于能打通了

为什么我会折腾这个

X Developers 发了一条消息，宣布 hosted X MCP 可以用了。我看到以后先想到的是：以后让 Codex 查 X，不用再靠网页片段和手动复制了。

以前让 AI 查 X，常见问题是它要么看不到，要么只看到网页片段，要么把搜索、作者、时间线、收藏夹混在一起说。现在 X 自己给了 MCP 入口，思路就顺很多：文档归文档，账号授权后的数据归数据。

我这次实际跑通的路径

X Developer App
开 OAuth 2.0 xurl 本地登录
保存授权 Codex 配置 xapi
通过 MCP 调 X API 新开线程或重启
工具才会加载出来

先分清两个 MCP

这里最容易绕晕。X 现在给到的是两类能力，不要把它们写到一起。

`x-docs`

地址是 https://docs.x.com/mcp。它只负责查 X 官方开发文档，适合问接口字段、鉴权方式、文档页位置。

如果你只是想让 Codex 看 X API 文档，不需要登录 X，也不需要 Developer App。

`xapi`

底层是 https://api.x.com/mcp，但我没有直接让 Codex 连它，而是用本地 xurl 做一层转接。

它会用你授权过的 X 账号去调用工具，比如搜索帖子、读自己的时间线、读 bookmarks、读 mentions，或者在你明确说了以后创建/删除收藏。

我建议先把 x-docs 装上。它没账号风险，出了问题也好排查。等文档 MCP 确认可用，再处理 xapi。

先装 x-docs，确认文档能查

Codex 里直接加远程 MCP：

codex mcp add x-docs --url https://docs.x.com/mcp

我做验证的时候，先跑 JSON-RPC 的 initialize。返回里能看到协议版本 2025-06-18，就说明这条 MCP 链路没问题。

这里不用急着碰 OAuth

查文档和访问你的 X 账号不是一回事。先让 Codex 能读官方文档，再决定要不要接账号授权数据。

X Developer App 创建流程里，入口不算好找

xapi 需要你自己的 X Developer App。这里我踩到的点是：中间页面不一定直接把 App 放在脸上，需要从 Developer Portal / Console 进去，先完成开发者账号，再进项目和 App。

OAuth 设置我按下面这样填：

权限选 Read and write，不要选 DM。
App 类型选 Web App, Automated App or Bot。
Callback URI 填 http://localhost:8080/callback。
Website URL 可以填自己的 X 主页或站点，比如 https://x.com/你的用户名。

Callback 用 localhost 是因为 OAuth 最后会回到你电脑上的本地监听地址。也就是说，授权页在浏览器打开，授权完成后，浏览器把结果交回本机 xurl。这一步不需要你放一个公网回调服务。

DM 权限我不建议选。我们这次要的是搜索、时间线、mentions、bookmarks 这类能力，不是让 AI 碰私信。权限越少，后面越安心。

用 xurl 做本地 OAuth，不把密钥写进 Codex 配置

Developer Portal 生成 OAuth 2.0 的 Client ID 和 Client Secret 后，我用 xurl 注册本地 app。这里千万别把真实值写到文章、截图或聊天里，命令里用环境变量就够。

npx -y @xdevplatform/xurl auth apps add xmcp \
  --client-id "$CLIENT_ID" \
  --client-secret "$CLIENT_SECRET" \
  --redirect-uri http://localhost:8080/callback

npx -y @xdevplatform/xurl auth default xmcp
npx -y @xdevplatform/xurl auth oauth2 --app xmcp

授权过程会打开浏览器。成功以后，浏览器页面会显示类似：

Authentication successful! You can close this window.

命令行里也会看到类似：

OAuth2 authentication successful!

我喜欢这个做法的原因是：Codex 的 MCP 配置里不需要出现 Client Secret，也不需要出现 token。Codex 只负责启动 xurl mcp，真正的 OAuth 和 token 刷新交给 xurl。

把 xapi 写进 Codex MCP 配置

最后在 Codex 的 MCP 配置里加这一段：

[mcp_servers.xapi]
command = "npx"
args = ["-y", "@xdevplatform/xurl", "mcp", "https://api.x.com/mcp"]

注意，这里没有 Client ID，没有 Client Secret，也没有 token。它只告诉 Codex：启动时用 xurl 去接 https://api.x.com/mcp。

新工具不一定立刻出现

我这次遇到的体验是：新加 MCP 后，当前 Codex 会话不一定马上看到新工具。通常新开一个线程，或者重启 Codex，工具列表才会重新加载。

怎么确认 xapi 真能用

我不会只看“配置写好了”。这类东西至少要看两层返回。

第一层：initialize

xapi 启动后，JSON-RPC initialize 返回里能看到 serverInfo 是 xmcp，协议版本是 2025-06-18。

第二层：tools/list

然后看 tools/list。我这次列出了 24 个工具，里面包括这些：

我看到的部分工具

search_posts_all、search_news、get_news
get_users_me、get_users_timeline、get_users_mentions
get_users_bookmarks、get_users_bookmark_folders
create_users_bookmark、delete_users_bookmark
get_posts_by_id、get_users_by_username

看到这些工具以后，才算真正从“配置成功”走到“Codex 能调用”。

以后它会在什么情况下触发

我会把这套 MCP 当成四种入口用。

查 X API 官方文档：优先走 x-docs。
查实时 X 内容：比如搜某个关键词、某条帖子、某个作者。
读自己的授权数据：比如 timeline、mentions、bookmarks。
做写入动作：只在我明确说“收藏这条”或“删除这个收藏”时才做。

这点要分清。能写不代表默认写。尤其是 bookmarks 这种动作，我希望 Codex 每次都先说清楚它要做什么，再动手。

安全边界要提前定好

这篇文章里我故意不放真实 Client ID、Client Secret、token、App ID，也不放本机临时文件路径。以后你自己写教程或截图，也最好按这个标准处理。

我会固定遵守的几条

只查文档时，用 x-docs，不用登录 X API。
Client Secret 和 token 不进 Codex 配置，不进博客，不进截图。
权限够用就行，不碰 DM。
创建收藏、删除收藏、发帖这类写操作，要明确授权。
新开线程或重启后，再确认工具有没有加载出来。

跑通以后，我最明显的感受是：Codex 终于能把“官方文档”和“实时资料”放到同一个工作流里了。以后要查 X API、追一条技术讨论、整理自己的收藏夹，不用再在浏览器和 AI 对话之间来回搬内容。