AI Agent MCP Handoff

如何把 TwexAPI MCP 访问安全地交给 AI Agent 和下游工作流。

当你要把 TwexAPI MCP 访问权限交给 AI 编程 Agent、研究 Agent、工作流 Agent 或内部助手时，请参考本页。

简单来说：通过登录或 API 密钥连接 API MCP 服务器，要求 Agent 在调用其他工具之前先调用 explore，读取用 twexapi_request，写入只在确认后用 twexapi_write，并要求输出可持久保存的交接结果，而不只是聊天里的总结。

交接清单

Agent 调用路线

先查文档

用 https://docs.twexapi.io/mcp 上的 Docs MCP 查阅公开文档、API 参数、配置说明、错误码、SDK 指南和示例。

找到 API 接口

用 API MCP 的 explore 找到准确的接口、请求方法、请求结构、分类和安全标记。

执行 API 调用

只读接口用 twexapi_request，写入接口用 twexapi_write，使用 explore 返回的准确方法和相对路径。每条 explore 结果都会注明应使用的工具。只传入文档中列出的 query 和 body 字段。

在对话之外持久化

当后端需要负责重试、保存游标、下载文件、定时任务或批量编排时，请使用 REST、SDK、队列或工作流工具。

交接结果

在 Agent 运行结束前，保存接口路径、请求参数、返回的 ID、has_more、next_cursor、任务 ID、写操作 ID、扣除的额度，以及导出或轮询所需的接口。

可直接复制的 Agent 指令

把下面的内容粘贴到 Agent 的系统指令、项目指令或任务提示词中：

You have access to Twexapi MCP servers.

Use Twexapi Docs MCP first when you need product documentation, setup instructions, endpoint docs, authentication details, examples, or error-code explanations.

Use the API MCP tool `explore` before making API calls. Search by query or category to find the correct Twexapi endpoint. Then call the tool named in the catalog entry's `tool` field (`twexapi_request` for reads, `twexapi_write` for writes) with the exact method and a relative path from that entry.

Rules:
- Never call absolute URLs through `twexapi_request` or `twexapi_write`.
- Never call paths that were not returned by `explore`.
- Do not call `/openapi.json`, docs pages, dashboards, or hidden framework routes through API MCP.
- Treat every `twexapi_write` call as a production action. Ask for explicit user confirmation before posting or replying.
- Never repeat an X cookie or auth_token back in your answer.
- Preserve tweet IDs, user IDs, task IDs, cursors, write action IDs, status, credit fields, and response metadata in your final answer when they are useful for auditability.
- If a request fails, report the HTTP status, endpoint name, method, path, and Twexapi error message.
- If a tool returns "No credits left on this TwexAPI account", stop and tell the user to top up; do not retry.
- For downstream workflows, return compact JSON with route_used, request, rows or ids, has_more, next_cursor, and next_step.

常见工作流

研究热门话题

Use Twexapi MCP to find trending countries, choose the United States, fetch AI-related trending tweets, and summarize the top themes with tweet IDs.

推荐路线：

1. explore(category="trending")
2. 用 twexapi_request 调用 /twitter/global-trending/countries
3. 用 twexapi_request 调用 /twitter/global-trending/topics
4. 用 twexapi_request 调用 /twitter/global-trending/tweets

交接字段：country、topic、content、tweet_id、author_username、created_at、互动数据、has_more、next_cursor。

搜索推文

Search recent posts from @openai that mention AI agents and return the most relevant tweets with IDs, author metadata, and a short summary.

推荐路线：

1. explore(query="advanced search tweets")
2. 用 twexapi_request 调用 /twitter/advanced_search/page
3. 如果目录返回分页流程，继续使用 /twitter/advanced_search/page

交接字段：原始查询、排序方式、tweet_id、正文、作者信息、发布时间、原文链接、has_more、next_cursor。

导出粉丝

Export a page of followers for @openai in CRM-ready JSON.

推荐路线：

1. explore(category="followers")
2. 用 twexapi_request 调用 /twitter/followers/{screen_name}/{count}，或 explore 返回的分页/任务接口

交接字段：源账号、user_id、username、名称、简介、粉丝数、认证状态、任务 ID、has_more、next_cursor。

抓取回复

Fetch replies for a tweet and return reply IDs, author usernames, text, and engagement fields.

推荐路线：

1. explore(query="tweet replies")
2. 用 twexapi_request 调用 /twitter/tweets/{tweet_id}/replies/{count} 或 /twitter/tweets/{tweet_id}/replies/page

交接字段：源推文 ID、回复 ID、作者用户名、正文、互动数据、页码、has_more、next_cursor。

获取 X 文章

Fetch this X article as Markdown and turn it into a concise brief.

推荐路线：

1. explore(category="articles")
2. 用 twexapi_request 调用 /x/article/{tweet_id}/markdown

交接字段：文章 ID、标题、作者、Markdown 正文、提取出的链接、原文 URL、生成的摘要。

执行写操作

Draft a reply to this tweet, ask me for confirmation, then post only after I approve.

推荐路线：

1. explore(query="create tweet", include_writes=true)
2. 把准确的推文内容和回复对象展示给用户
3. 等待用户明确确认
4. 用 twexapi_write 调用 POST /twitter/tweets/create，在 cookie 中传入用户的 X Cookie

发推是 MCP 中唯一可用的写操作，其他写操作请使用 REST API。

交接字段：确认内容、请求方法、路径、推文内容、tweet_id、状态、扣除的额度、回复对象、媒体 URL。不要包含 Cookie。

交接输出约定

对于需要持久化的工作流，让 Agent 返回简洁的 JSON：

{
  "source": "twexapi_mcp",
  "job": "tweet_search",
  "route_used": "/twitter/advanced_search/page",
  "request": {
    "method": "POST",
    "path": "/twitter/advanced_search/page",
    "query": null,
    "body": {
      "searchTerms": ["from:openai AI agents"],
      "maxItems": 20,
      "sortBy": "Latest"
    }
  },
  "rows": [],
  "ids": [],
  "has_more": false,
  "next_cursor": null,
  "next_step": null
}

需要写入 CRM、表格、数据库或队列的记录放在 rows 中。如果下一个处理环节只需要持久的标识符，就用 ids。

安全模型

TwexAPI MCP 有三道防护：

错误处理

MCP 认证失败时，任何工具都不会执行。请保留 JSON-RPC 错误：

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": 401,
    "message": "Access token is invalid or expired"
  }
}

账号额度用完时，连接仍然有效，explore 也免费可用，但其他工具调用会返回：

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

工具执行后，如果底层 TwexAPI API 返回非 2xx 响应，让 Agent 保留工具结果：

{
  "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": []
  }
}

常见状态码的含义：

全部错误信息见 MCP 工具参考。

生产环境建议

• 如果 Agent 不需要发推，以只读方式连接（登录时取消勾选写入权限）。
• 自主运行的 Agent 优先使用只读工作流。
• 对写入类工作流，记录提示词、请求体、接口名称和 MCP 响应。
• 每次调用 twexapi_write 之前都需要人工确认。
• 不要在最终展示给用户的消息中出现 Cookie、认证 token、API 密钥和私信原文。
• 如果需要由另一个处理环节继续任务，把游标和任务 ID 保存在对话之外。
• 需要重试、排队和持久存储的生产定时任务，请直接使用 REST 或生成的 SDK。