MCP ツールリファレンス

TwexAPI MCP ツール：エンドポイントの検索、読み取り専用の X データ呼び出し、投稿、ワークフローの引き渡し、安全なエージェント実行。

https://api.twexapi.io/mcp の TwexAPI API MCP サーバーは、explore、twexapi_request、twexapi_write の 3 つのツールを提供します。サインインまたは API キー で接続してください。

エージェントはまず explore でエンドポイントを探し、explore がそのエンドポイントに指定したツールを呼び出します。読み取りと書き込みは別のツールに分かれているため、Claude などのクライアントは読み取りを自由に実行し、書き込みのたびに確認を求められます。

ツール

ユーザーが読み取り専用（スコープ mcp:read）でサインインした場合や、サーバーで書き込み操作が無効になっている場合、twexapi_write は表示されません。

explore

エンドポイントカタログを検索します。X/Twitter へのリクエストは行わず、クレジットも消費しないため、アカウントのクレジットが残っていなくても使えます。ただし、サインインまたは API キーは必要です。

入力

結果は最大 50 件です。

カタログの項目

interface EndpointInfo {
  name: string;
  method: string;
  path: string; // may contain {placeholders}; replace them before calling
  category: string;
  description: string;
  read_only: boolean;
  tool: "twexapi_request" | "twexapi_write"; // the tool that calls this endpoint
  cursor_paginated: boolean;
  parameters_schema: Record<string, unknown>; // JSON Schema of method, path, query, body
  example: { method: string; path: string; query?: Record<string, unknown>; body?: unknown };
  mpp_eligible: boolean; // accepts pay-per-call on /mcp/pay
}

例

{ "category": "trending" }

{ "query": "advanced search" }

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

twexapi_request

読み取り専用のエンドポイントを呼び出します。認証は MCP 接続から自動で付与されるため、エージェントはメソッド、相対パス、任意の query と body だけを渡します。

入力

レスポンス

ツールは MCP のメタデータと REST のレスポンスを返します：

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

status_code が 2xx 以外の場合、ツールの結果はエラーとして扱われます。result に含まれる ID、カーソル、タスク ID、クレジットのフィールドは保持してください。ページに has_more と next_cursor がある場合は、explore が返した次のエンドポイントにカーソルを渡します。

twexapi_write

書き込みエンドポイントを呼び出します。入力とレスポンスの形は twexapi_request と同じです。現在 MCP カタログにある書き込みエンドポイントは、ツイートまたはリプライを投稿する POST /twitter/tweets/create の 1 つだけです。

{
  "method": "POST",
  "path": "/twitter/tweets/create",
  "body": {
    "tweet_content": "Hello from TwexAPI MCP",
    "cookie": "auth_token=...; ct0=...",
    "reply_tweet_id": null,
    "media_url": null
  }
}

twexapi_write の呼び出しには、メソッド、パス、ボディから生成した Idempotency-Key が付きます。クライアントがタイムアウト後などに 10 分以内にまったく同じ呼び出しを繰り返すと、2 件目を投稿せず最初の結果を返します。詳しくは 投稿を安全に再試行する を参照してください。

いいね、リツイート、フォロー、ブックマーク、削除、DM、記事の公開など、その他の書き込み操作は REST API でのみ利用できます。

書き込みエンドポイントを twexapi_request で、読み取りエンドポイントを twexapi_write で呼び出すと失敗し、正しいツール名を示すメッセージが返ります。

ワークフローの例

以下は、エージェントが組み立てるべきリクエストの例です。実際に使うときは、まず 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": "2104354931595423762",
      "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
  }
}

フォロワーをエクスポートする

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

大量にエクスポートする場合は、カーソル付きの POST /twitter/followers/page、または explore が返すタスクのエンドポイント（/twitter/followers/task/{task_id}/status と /next）を使ってください。

X の記事を Markdown で読む

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

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

カタログには読み取り専用のエンドポイントが 54 個、書き込みエンドポイントが 1 個あります。

エラー処理

接続が認可されていない場合、ツールは実行されず、クライアントには HTTP 401 または 403 の JSON-RPC エラーが返ります：

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": 401,
    "message": "Sign in through your MCP client, or send your TwexAPI API key in the Authorization header. For pay-per-call without an API key, use /mcp/pay."
  }
}

アカウントのクレジットがなくなっても接続は維持されます。explore は結果を返し、その他のツール呼び出しは API を呼ばずにエラー結果を返します：

{
  "error": "No credits left on this TwexAPI account. Top up at https://twexapi.io/dashboard and try again."
}

ツールが実行され、REST API が 2xx 以外を返した場合は、MCP のメタデータと API のエラーを保持してください：

{
  "status_code": 429,
  "endpoint": "get_global_trending_tweets",
  "method": "GET",
  "path": "/twitter/global-trending/tweets",
  "result": {
    "code": 429,
    "msg": "Rate limit exceeded. QPS limit: 2 requests per second",
    "data": []
  }
}

復旧方法は エラー処理 と レート制限 を参照してください。