---
title: "AI Agent MCP Handoff"
description: "将 Twexapi MCP 访问安全交给 AI Agent 与下游工作流的说明。"
---

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

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

## Handoff 清单

1. **连接 API MCP 服务器**

    向 MCP 客户端添加 `https://api.twexapi.io/mcp`，使用 `x-api-key` 或 `Authorization: Bearer <token>`。

2. **连接 Docs 文档 MCP 服务器**

    Agent 应先搜索 Twexapi 文档再选 API 路由时，添加 `https://docs.twexapi.io/mcp`。

3. **调用前先进行接口探查**

    指导 Agent 先调用 `explore`，用与任务匹配的 query 或 category。

4. **限定使用相对接口路径**

    指导 Agent 仅用 `explore` 返回的相对路径调用 `twexapi_request`。

5. **保留关键交接字段**

    最终输出须含 ID、游标、task ID、路由名、状态与额度字段。

6. **严格审核与执行写操作**

    `read_only` 为 `false` 的任何端点前须明确用户确认。

## 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：

```txt
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.
```

## 常见工作流

### 研究热门主题

```txt
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`。

### 搜索推文

```txt
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`。

### 导出粉丝

```txt
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`。

### 抓取回复

```txt
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 文章

```txt
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、生成摘要。

### 运行写操作

```txt
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：

```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 有三条重要护栏：

| 护栏 | 行为 |
| --- | --- |
| API key auth | MCP 与 REST API 使用相同 API 密钥验证、额度检查与账号控制。 |
| Allowlisted paths | `twexapi_request` 拒绝 MCP 目录外端点。 |
| Write flags | 副作用操作标记 `read_only: false`，便于AI Agent请求确认。 |

## 错误处理

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

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

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

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

有用解读：

| 状态 | 含义 |
| --- | --- |
| `401` | 工具运行前 MCP 认证失败；检查 `x-api-key` 或 Bearer auth。 |
| `403` | API 密钥不可用、额度用尽或操作不允许。 |
| `429` | 超出速率限制。在限制窗口后重试。 |
| `5xx` | 服务端故障或上游 X/Twitter 抓取问题。 |

## 生产指南

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