MCP 工具参考

TwexAPI MCP 工具：接口发现、只读 X 数据调用、发推、工作流交接与安全的 Agent 执行。

位于 https://api.twexapi.io/mcp 的 TwexAPI API MCP 服务器提供三个工具：explore、twexapi_request 和 twexapi_write。可以登录或使用 API 密钥连接。

Agent 应先调用 explore 找到接口，再调用 explore 为该接口指定的工具。读取和写入是两个独立的工具，这样 Claude 等客户端可以放心执行读取，并在每次写入前请用户确认。

工具

工具	用途	注解	何时出现
`explore`	搜索接口目录：请求方法、路径、分类、参数、示例，以及应调用的工具。	只读、幂等	始终
`twexapi_request`	用相对路径调用只读接口。	只读	始终
`twexapi_write`	调用写入接口（发推或回复）。	破坏性、非幂等	仅在有写入权限时

当用户以只读方式登录（权限范围 mcp:read），或服务器关闭了写操作时，不会列出 twexapi_write。

`explore`

搜索接口目录。它不会请求 X/Twitter，也不消耗额度，所以账号额度用完时也能使用。但它仍然需要登录或 API 密钥。

输入

名称	类型	必填	说明
`query`	string	否	在接口名称、路径和描述中按关键词搜索。
`category`	string	否	按分类精确筛选，例如 `trending`、`search`、`users` 或 `write`。见接口分类。
`include_writes`	boolean	否	同时返回写入接口。只有连接具备写入权限时才会返回。

每次最多返回 50 条结果。

目录条目

interface EndpointInfo {
  name: string;
  method: string;
  path: string; // may contain {placeholders}; replace them before calling
  category: string;
  description: string;
  read_only: boolean;
  tool: "twexapi_request" | "twexapi_write"; // the tool that calls this endpoint
  cursor_paginated: boolean;
  parameters_schema: Record<string, unknown>; // JSON Schema of method, path, query, body
  example: { method: string; path: string; query?: Record<string, unknown>; body?: unknown };
  mpp_eligible: boolean; // accepts pay-per-call on /mcp/pay
}

示例

{ "category": "trending" }

{ "query": "advanced search" }

{ "query": "create tweet", "include_writes": true }

`twexapi_request`

调用只读接口。认证信息由 MCP 连接自动注入，Agent 只需传入请求方法、相对路径，以及可选的 query 和 body。

输入

名称	类型	必填	说明
`method`	string	是	`explore` 返回的 HTTP 方法，例如 `GET` 或 `POST`。
`path`	string	是	`explore` 返回的相对路径，占位符需替换为实际值。绝对 URL 会被拒绝。
`query`	object	否	查询参数。
`body`	object、array 或标量	否	非 GET 请求的 JSON 请求体。

响应

工具返回 MCP 元数据以及 REST 响应：

{
  "status_code": 200,
  "endpoint": "list_global_trending_countries",
  "method": "GET",
  "path": "/twitter/global-trending/countries",
  "result": {
    "code": 200,
    "msg": "success",
    "data": []
  }
}

status_code 不是 2xx 时，工具结果会被标记为错误。请保留 result 中的 ID、游标、任务 ID 和额度字段。如果某页包含 has_more 和 next_cursor，把游标传给 explore 返回的后续接口。

`twexapi_write`

调用写入接口。输入和响应格式与 twexapi_request 相同。目前 MCP 目录中只有一个写入接口：POST /twitter/tweets/create，用于发推或回复。

{
  "method": "POST",
  "path": "/twitter/tweets/create",
  "body": {
    "tweet_content": "Hello from TwexAPI MCP",
    "cookie": "auth_token=...; ct0=...",
    "reply_tweet_id": null,
    "media_url": null
  }
}

请求体字段	必填	说明
`tweet_content`	是	推文或回复的内容。
`cookie`	是	发推账号的 X Cookie 或 `auth_token`。
`reply_tweet_id`	否	要回复的推文 ID。
`media_url`	否	要附加的公开媒体 URL。
`schedule`	否	定时发送的 ISO 时间。
`community_name`	否	要发布到的社区名称或 ID。
`delegated_account_username`	否	以哪个委托账号的身份发布。
`proxy`	否	请求使用的代理 URL。

每次调用 twexapi_write 都会带上一个根据方法、路径和请求体生成的 Idempotency-Key。如果客户端在 10 分钟内重复完全相同的调用（例如超时后重试），会直接拿到第一次的结果，不会再发一条。详见安全地重试发推。

点赞、转推、关注、收藏、删除、私信、发布文章等其他写操作只能通过 REST API 完成。

用 twexapi_request 调用写入接口，或用 twexapi_write 调用只读接口，都会失败，错误信息会告诉你应该用哪个工具。

工作流示例

以下示例展示 Agent 应该生成的请求。实际使用时请先运行 explore，让 Agent 确认最新的参数结构。

搜索推文

{
  "method": "POST",
  "path": "/twitter/advanced_search/page",
  "body": {
    "searchTerms": ["from:openai AI agents"],
    "maxItems": 20,
    "sortBy": "Latest"
  }
}

让 Agent 返回一个简洁的交接对象：

{
  "source": "twexapi_mcp",
  "job": "tweet_search",
  "route_used": "/twitter/advanced_search/page",
  "query": "from:openai AI agents",
  "rows": [
    {
      "tweet_id": "2104354931595423762",
      "text": "...",
      "author_username": "openai",
      "created_at": "..."
    }
  ],
  "has_more": false,
  "next_cursor": null
}

获取热门推文

{
  "method": "GET",
  "path": "/twitter/global-trending/tweets",
  "query": {
    "country": "united-states",
    "topic": "technology",
    "content": "AI",
    "count": 20
  }
}

导出粉丝

{
  "method": "GET",
  "path": "/twitter/followers/openai/50"
}

大批量导出请使用带游标的 POST /twitter/followers/page，或 explore 返回的任务接口（/twitter/followers/task/{task_id}/status 和 /next）。

以 Markdown 读取 X 文章

{
  "method": "GET",
  "path": "/x/article/2104354931595423762/markdown"
}

接口分类

目录中有 54 个只读接口和 1 个写入接口：

分类	接口
`trending`	趋势国家、话题、内容标签、热门推文和各国趋势。
`search`	高级搜索（单次调用与分页）、话题标签和 cashtag。
`users`	按 ID 查询用户、用户搜索、蓝 V 与组织认证检查、账号状态。
`tweets`	推文查询、帖子串、相似推文和回复（按数量与分页）。
`followers`	粉丝与关注：最新、按数量、分页和长任务。
`engagement`	转推者、点赞者和引用推文。
`communities`	社区详情、搜索、成员和推文。
`lists`	列表搜索、推文、成员和订阅者。
`timeline`	用户时间线，以及推文与回复页面。
`articles`	按 ID 获取 X 文章，或以 Markdown 获取。
`accounts`	账号所在地以及“关于此账号”信息。
`dm`	用户的私信可达性（只读）。
`write`	发推或回复。

错误处理

连接未获授权时，任何工具都不会执行，客户端会收到 HTTP 401 或 403 的 JSON-RPC 错误：

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": 401,
    "message": "Sign in through your MCP client, or send your TwexAPI API key in the Authorization header. For pay-per-call without an API key, use /mcp/pay."
  }
}

错误	含义
`401` “Sign in through your MCP client…”	没有凭证。支持登录的客户端会据此发起登录。
`401` “Invalid or unavailable MCP API token”	API 密钥无效。
`401` “Access token is invalid or expired”	登录已过期或已被撤销，请重新登录。
`403` “This TwexAPI API key is disabled…”	在控制台中重新启用该密钥。
`403` “No usable API key on this account…”	登录的账号没有可用的 API 密钥，请在控制台创建。

账号额度用完时，连接仍然有效。explore 照常返回结果，其他工具调用会直接返回错误结果，不会调用 API：

{
  "error": "No credits left on this TwexAPI account. Top up at https://twexapi.io/dashboard and try again."
}

工具执行后，如果 REST API 返回非 2xx 响应，请保留 MCP 元数据和 API 错误：

{
  "status_code": 429,
  "endpoint": "get_global_trending_tweets",
  "method": "GET",
  "path": "/twitter/global-trending/tweets",
  "result": {
    "code": 429,
    "msg": "Rate limit exceeded. QPS limit: 2 requests per second",
    "data": []
  }
}

状态码	含义
`4xx`	参数无效、资源不存在，或操作不被允许。修正请求后再重试。
`429`	超出速率限制。等限制窗口过后再重试。
`5xx`	服务端故障或上游 X/Twitter 抓取问题。稍后重试。

恢复方法见错误处理和速率限制。