---
title: "MCP ツールリファレンス"
description: "エンドポイント探索、認証済み API 呼び出し、ワークフロー引き渡し、安全なエージェント実行のための Twexapi MCP ツール。"
---

Twexapi API MCP サーバーは `explore` と `twexapi_request` の 2 ツールを公開しています。`x-api-key` または OAuth 2.1 Bearer 認証で `https://api.twexapi.io/mcp` に接続してください。

エージェントは `twexapi_request` を呼ぶ前に `explore` で API カタログを確認すべきです。エンドポイント選択が明示的になり、リクエストスキーマを保ちやすく、MCP 経由で利用できないパスへの誤呼び出しを防げます。

## ツール

| ツール | 用途 |
| --- | --- |
| `explore` | API エンドポイントカタログを検索し、メソッド、パス、カテゴリ、パラメータ、例、安全フラグを返します。 |
| `twexapi_request` | 許可リストに載った相対パスに対して認証済み Twexapi API 呼び出しを実行します。 |

## `explore`

API エンドポイントカタログを検索します。読み取り専用で、X/Twitter ネットワーク呼び出しはなく、エンドポイントクレジットも消費しません。呼び出しには API キーまたは OAuth Bearer トークンによる MCP 認証が必要です。

`explore` で利用可能なエンドポイントの発見、パラメータ確認、カテゴリ比較、実行前の適切な API パスの特定ができます。

### 入力

| 項目名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `query` | string | No | エンドポイント名、メソッド、パス、カテゴリ、説明、例を横断するキーワード検索。 |
| `category` | string | No | `trending`、`search`、`users`、`articles`、`write` などの完全一致カテゴリフィルター。 |
| `include_writes` | boolean | No | 副作用のあるエンドポイントを含める。書き込みエンドポイントは `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 リクエストから自動注入されるため、エージェントはエンドポイントのメソッド、相対パス、任意の query/body のみ渡します。

### 入力

| 項目名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `method` | string | Yes | `explore` が返す HTTP メソッド（`GET` や `POST` など）。 |
| `path` | string | Yes | Twexapi API の相対パス。絶対 URL は拒否されます。 |
| `query` | object | No | リクエストのクエリパラメータ。 |
| `body` | object, array, or scalar | No | GET 以外の JSON リクエストボディ。 |

:::warning
  先に `explore` を呼び、カタログが返す正確な相対パスを使ってください。`/openapi.json`、ドキュメントページ、ダッシュボード、非公開フレームワークルートを `twexapi_request` 経由で呼ばないでください。
:::

### レスポンス契約

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

ID、カーソル、タスク ID、クレジットフィールド、書き込みアクション ID など、`result` の永続化に必要なフィールドを保持してください。ページに `has_more` と `next_cursor` がある場合は、`explore` が返すドキュメント化されたフォローアップエンドポイントまたはクエリパラメータにカーソルを渡します。

## ワークフロー例

これらはエージェントが生成すべき形の例です。実際の利用ではスキーマ確認のため先に `explore` を実行してください。

### 引き渡し行付きツイート検索

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

エージェントにコンパクトな引き渡しオブジェクトを返すよう依頼します：

```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 を返す場合は保存し、ドキュメント化された status/next エンドポイントをポーリングしてください。

### X 記事を Markdown で読む

```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` のエンドポイントは本番アクションとして扱ってください。投稿、返信、フォロー、ブロック、削除、ブックマーク、DM 送信の前に、ユーザーの明示的な確認を必須にしてください。
:::

`tweet_id`、`write_action_id`、`status`、`charged_credits`、返信先、メディア URL、ユーザー確認記録を保存してください。

## エージェント引き渡しパターン

MCP は JSON を返します。エージェントキュー、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、ユーザー名、表示名、bio、フォロワー数、ソースアカウント、タスク ID、次のカーソルを保存します。

### 書き込みアクションを追跡

書き込みエンドポイントでは、エンドポイントパス、ボディハッシュまたは確認テキスト、返却されたツイート ID または write action ID、ステータス、課金クレジット、メディア参照を保存します。

### DM を送信

ユーザー確認の後にのみ DM エンドポイントを呼び出します。メッセージ ID、受信者ユーザー ID、アカウント、メディア参照、配信ステータスを保存します。DM 本文全体は共有 MCP 出力に含めないでください。

## エンドポイントカテゴリ

| Category | Common uses |
| --- | --- |
| `trending` | 国、トピック、コンテンツタグ、トレンドツイート。 |
| `search` | 高度な検索、ハッシュタグ検索、キャッシュタグ検索、ページネーション検索。 |
| `users` | ユーザー参照、アカウント認証、ユーザー検索、アカウントステータス。 |
| `tweets` | 返信、スレッド、ツイート参照、類似ツイート、センチメント、引用、リツイートしたユーザー、いいねしたユーザー。 |
| `followers` | フォロワー、フォロー中、最新フォロワー、ページネーション付き関係データ。 |
| `communities` | コミュニティメタデータ、メンバー、ツイート、検索、コミュニティツイート検索。 |
| `lists` | リスト作成、リストツイート、メンバー、購読者、リスト検索。 |
| `dm` | DM ステータス、DM 送信、DM 履歴。 |
| `articles` | X 記事参照、Markdown 取得、下書き、カバー、コンテンツ更新、公開。 |
| `timeline` | ユーザータイムライン、ツイート/返信ページ。 |
| `accounts` | Cookie 検証、アカウント情報、アカウント認証、アカウントステータス。 |
| `write` | 投稿、返信、いいね、リツイート、フォロー、ブロック、ブックマーク、削除、DM 送信など副作用のある操作。 |

## エラーハンドリング

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 のリカバリーパターンは [Error Handling](/guides/error-handling) と [Rate Limits](/guides/rate-limits) を参照してください。