---
title: "MCP 工具参考"
description: "Twexapi MCP 工具：端点发现、认证 API 调用、工作流交接与安全AI Agent执行。"
---

Twexapi API MCP 服务器暴露 2 个工具：`explore` 与 `twexapi_request`。使用 `x-api-key` 或 OAuth 2.1 Bearer 认证连接 `https://api.twexapi.io/mcp`。

Agent 应在调用 `twexapi_request` 前用 `explore` 检查 API 目录。这样端点选择更明确，便于保留请求 schema，并避免误调 MCP 不可用的路径。

## 工具

| 工具 | 用途 |
| --- | --- |
| `explore` | 搜索 API 端点目录，返回方法、路径、类别、参数、示例与安全标记。 |
| `twexapi_request` | 对白名单相对路径执行已认证的 Twexapi API 调用。 |

## `explore`

搜索 API 端点目录。只读，不访问 X/Twitter 网络，不消耗端点额度。调用仍需要 API 密钥或 OAuth Bearer 令牌的 MCP 认证。

使用 `explore` 发现可用端点、检查参数、比较类别，并在执行调用前找到正确的 API 路径。

### 输入

| 名称 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `query` | string | 否 | 在端点名称、方法、路径、类别、描述与示例中关键词搜索。 |
| `category` | string | 否 | 精确类别过滤，如 `trending`、`search`、`users`、`articles` 或 `write`。 |
| `include_writes` | boolean | 否 | 包含有副作用的端点。写端点标记为 `read_only: false`。 |

### 目录结构

```ts
interface EndpointInfo {
  name: string;
  method: string;
  path: string;
  category: string;
  description: string;
  read_only: boolean;
  parameters_schema?: Record<string, unknown>;
  example?: {
    method: string;
    path: string;
    query?: Record<string, unknown>;
    body?: unknown;
  };
}
```

### 示例

查找趋势端点：

```json
{
  "category": "trending"
}
```

按关键词搜索：

```json
{
  "query": "advanced search tweets"
}
```

包含可写端点：

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

## `twexapi_request`

对你的 Twexapi 账号执行 API 调用。认证从 MCP 请求自动注入，AI Agent只需传入端点方法、相对路径及可选的 query/body。

### 输入

| 名称 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `method` | string | 是 | `explore` 返回的 HTTP 方法，如 `GET` 或 `POST`。 |
| `path` | string | 是 | Twexapi API 相对路径。绝对 URL 会被拒绝。 |
| `query` | object | 否 | 请求的查询参数。 |
| `body` | object、array 或标量 | 否 | 非 GET 请求的 JSON 请求体。 |

:::warning
  先调用 `explore` 并使用目录返回的精确相对路径。勿通过 `twexapi_request` 调用 `/openapi.json`、文档页、控制台或隐藏框架路由。
:::

### 响应契约

`twexapi_request` 返回 MCP 执行元数据及底层 REST 响应：

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

从 `result` 保留持久化字段，包括 ID、游标、任务 ID、额度字段与写操作 ID。当页面包含 `has_more` 与 `next_cursor` 时，将游标传入 `explore` 返回的文档化后续端点或查询参数。

## 工作流示例

以下示例展示Agent 应产出的结构。实际使用时先运行 `explore` 以确认当前 schema。

### 带交接行的推文搜索

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

要求AI Agent返回紧凑交接对象：

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

### 获取趋势推文

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

存在时存储 `country`、`topic`、`content`、推文 ID、作者用户名、互动字段、`has_more` 与 `next_cursor`。

### 导出粉丝到 CRM

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

存储 `user_id`、`username`、`name`、`description`、`followers_count`、源账号及分页/任务字段。若端点返回任务 ID，存储并轮询文档中的状态/下一页端点。

### 以 Markdown 读取 X 文章

```json
{
  "method": "GET",
  "path": "/x/article/1803006263529541838/markdown"
}
```

存储文章 ID、标题、作者、Markdown 正文、提取的链接与源 URL。

### 发推或回复

```json
{
  "method": "POST",
  "path": "/twitter/tweets/create",
  "body": {
    "tweet_content": "Hello from Twexapi MCP",
    "reply_tweet_id": null,
    "media_url": null
  }
}
```

:::warning
  将 `read_only: false` 的端点视为生产操作。发帖、回复、关注、屏蔽、删除、书签或发私信前须要求用户明确确认。
:::

存储 `tweet_id`、`write_action_id`、`status`、`charged_credits`、回复目标、媒体 URL 与用户确认记录。

## AI Agent交接模式

MCP 返回 JSON。对AI Agent队列、CRM、电子表格、数仓与无代码工作流，返回包含原始任务、所用路由、待存储的规范化行或 ID，以及下一游标或待轮询任务的小型持久对象。

### 推文搜索到 JSON

调用 `POST /twitter/advanced_search/page`。存储推文 ID、正文、作者元数据、创建时间、链接、`has_more`、`next_cursor` 与原始查询。

### 抓取回复

有界页面调用 `GET /twitter/tweets/{tweet_id}/replies/{count}`，游标分页调用 `GET /twitter/tweets/{tweet_id}/replies/page`。存储回复 ID、作者用户名、正文、指标、`has_more` 与 `next_cursor`。

### 导出粉丝

调用 `GET /twitter/followers/{screen_name}/{count}` 或 `explore` 返回的 page/task 端点。存储用户 ID、用户名、名称、简介、粉丝数、源账号、任务 ID 与下一游标。

### 跟踪写操作

对写端点存储端点路径、请求体哈希或确认文本、返回的推文 ID 或写操作 ID、状态、扣费额度与媒体引用。

### 发送私信

仅在用户确认后调用私信端点。存储消息 ID、收件人用户 ID、账号、媒体引用与投递状态。共享 MCP 输出中勿包含完整私信正文。

## 端点类别

| 类别 | 常见用途 |
| --- | --- |
| `trending` | 国家、话题、内容标签与趋势推文。 |
| `search` | 高级搜索、话题标签搜索、股票标签搜索与分页搜索。 |
| `users` | 用户查询、账号认证、用户搜索与账号状态。 |
| `tweets` | 回复、串、推文查询、相似推文、情感、引用、转推者与点赞者。 |
| `followers` | 粉丝、关注、最新粉丝与分页关系数据。 |
| `communities` | 社区元数据、成员、推文、搜索与社区推文搜索。 |
| `lists` | 列表创建、列表推文、成员、订阅者与列表搜索。 |
| `dm` | 私信状态、发送私信与私信历史。 |
| `articles` | X 文章查询、Markdown 获取、草稿、封面、内容更新与发布。 |
| `timeline` | 用户时间线与推文/回复分页。 |
| `accounts` | Cookie 校验、账号信息、账号认证与账号状态。 |
| `write` | 发帖、回复、点赞、转推、关注、屏蔽、书签、删除、发私信等有副作用的操作。 |

## 错误处理

MCP 认证失败时工具不会执行。客户端收到 JSON-RPC 错误：

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

当 `twexapi_request` 已执行且底层 Twexapi API 返回非 2xx 时，保留 MCP 元数据与 Twexapi 错误：

```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 认证。 |
| `403` | API 密钥不可用、额度耗尽或操作不允许。 |
| `429` | 超出速率限制。请在限制窗口后重试。 |
| `5xx` | 服务端故障或上游 X/Twitter 抓取问题。 |

REST 与 MCP 恢复模式见 [错误处理](/guides/error-handling) 与 [速率限制](/guides/rate-limits)。