AI Agent MCP Handoff

将 Twexapi MCP 访问安全交给 AI Agent 与下游工作流的说明。

向 AI 编程 Agent、调研 Agent、工作流 Agent或内部助手授予 Twexapi MCP 访问时使用本页。

简要版：连接 API MCP 服务器、为 Agent 分配 API 密钥、指示先 explore 再 twexapi_request，并要求 durable handoff 输出而非仅聊天摘要。

Handoff 清单

Agent 路由清单

先读文档

公开文档、API 参数、示例、错误码、SDK 指南与无认证页检索用 Docs MCP https://docs.twexapi.io/mcp。

发现 API 路由

用 API MCP explore 找到精确端点、方法、请求 schema、类别与安全标志。

执行 API 调用

用 API MCP twexapi_request，方法与相对路径须与 explore 返回一致。仅传文档化 query 与 body 字段。

在聊天外持久化

后端须拥有重试、游标存储、文件下载、定时作业或批量编排时用 REST、SDK、队列或工作流工具。

Hand off 结果

结束Agent 运行前存储端点路径、请求参数、返回 ID、has_more、next_cursor、task ID、write action ID、charged credits 及任何导出或轮询路由。

可复制粘贴的Agent 指令

粘贴到Agent 系统指令、项目指令或任务 prompt：

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 `twexapi_request` with the exact method and a relative path from the returned catalog entry.

Rules:
- Never call absolute URLs through `twexapi_request`.
- 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 any catalog entry with `read_only: false` as a production action.
- Ask for explicit user confirmation before posting, replying, liking, retweeting, following, blocking, bookmarking, deleting, sending DMs, or making any other write call.
- 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.
- 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

Handoff 字段：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

Handoff 字段：原始查询、排序模式、tweet_id、文本、作者元数据、创建时间、直接 URL、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 返回的 page/task 端点

Handoff 字段：源账号、user_id、username、名称、简介、粉丝数、verified 状态、task 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

Handoff 字段：源 tweet 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

Handoff 字段：文章 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. 向用户展示精确写入请求体 (Request Body)
3. 等待明确确认
4. twexapi_request 调用返回的写端点

Handoff 字段：确认文本、method、path、请求 body、tweet_id、write_action_id、status、charged credits、回复目标、媒体 URL。

Handoff 输出契约

durable 工作流要求AI 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
}

rows 用于进入 CRM、电子表格、数据库或队列的记录。下一 worker 仅需 durable 标识符时用 ids。

安全模型

Twexapi MCP 有三条重要护栏：

错误处理

MCP 认证失败时工具不运行。保留 JSON-RPC 错误：

{
  "jsonrpc": "2.0",
  "error": {
    "code": 401,
    "message": "Missing MCP API token"
  }
}

twexapi_request 运行且底层 Twexapi API 返回非 2xx 时，要求AI Agent保留工具结果：

{
  "status_code": 403,
  "endpoint": "get_global_trending_tweets",
  "method": "GET",
  "path": "/twitter/global-trending/tweets",
  "result": {
    "detail": "Credits exhausted or action not allowed."
  }
}

有用解读：

生产指南

• AI Agent仅需特定工作流时使用 scoped API 密钥。
• 自主AI Agent优先只读工作流。
• 写工作流记录 prompt、请求 body、路由名与 MCP 响应。
• read_only: false 调用前须人工审批。
• cookie、auth token、API 密钥与私有 DM 文本勿出现在最终用户可见消息。
• 另一 worker 须继续作业时在聊天外存储游标与 task ID。
• 需要重试、队列与 durable 存储的定时生产作业用直接 REST 或生成 SDK。