MCP ツールリファレンス

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

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

入力

カタログの形

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;
  };
}

例

トレンドエンドポイントを探す：

{
  "category": "trending"
}

キーワード検索：

{
  "query": "advanced search tweets"
}

書き込み可能なエンドポイントを含める：

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

twexapi_request

Twexapi アカウントに対して API 呼び出しを実行します。認証は MCP リクエストから自動注入されるため、エージェントはエンドポイントのメソッド、相対パス、任意の query/body のみ渡します。

入力

レスポンス契約

twexapi_request は MCP 実行メタデータと基になる REST レスポンスを返します：

{
  "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 を実行してください。

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

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

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

{
  "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
}

トレンドツイートの取得

{
  "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 にエクスポート

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

user_id、username、name、description、followers_count、ソースアカウント、ページネーション/タスクフィールドを保存します。エンドポイントがタスク ID を返す場合は保存し、ドキュメント化された status/next エンドポイントをポーリングしてください。

X 記事を Markdown で読む

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

記事 ID、タイトル、作者、Markdown 本文、抽出リンク、ソース URL を保存してください。

ツイートまたは返信を投稿

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

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 出力に含めないでください。

エンドポイントカテゴリ

エラーハンドリング

MCP 認証に失敗するとツールは実行されません。クライアントは JSON-RPC エラーを受け取ります：

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

twexapi_request が実行され、基になる Twexapi API が非 2xx を返した場合は、MCP メタデータと Twexapi エラーを保持してください：

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

REST と MCP のリカバリーパターンは Error Handling と Rate Limits を参照してください。