AI エージェントへの MCP 引き渡し

TwexAPI の MCP アクセスを AI エージェントや後続のワークフローに安全に引き渡す方法。

AI コーディングエージェント、リサーチエージェント、ワークフローエージェント、社内アシスタントに TwexAPI の MCP アクセスを渡すときは、このページを参照してください。

要点：API MCP サーバーにはサインインか API キーで接続し、エージェントには他のツールより先に explore を呼ばせ、読み取りは twexapi_request、書き込みは確認後に限り twexapi_write を使わせます。結果はチャットの要約ではなく、後から使える形で出力させてください。

引き渡しチェックリスト

エージェントのルートチェックリスト

まずドキュメントを読む

公開ドキュメント、API パラメーター、セットアップ手順、エラーコード、SDK のガイド、例を調べるには、https://docs.twexapi.io/mcp の Docs MCP を使います。

API のルートを見つける

API MCP の explore で、正確なエンドポイント、メソッド、リクエストスキーマ、カテゴリ、安全フラグを見つけます。

API を呼び出す

読み取り専用のエンドポイントには twexapi_request、書き込みエンドポイントには twexapi_write を使い、explore が返したメソッドと相対パスをそのまま指定します。explore の各結果には使うべきツールが書かれています。ドキュメントにある query と body のフィールドだけを渡してください。

チャットの外に保存する

バックエンドが再試行、カーソルの保存、ファイルのダウンロード、定期ジョブ、バッチ処理を担う必要がある場合は、REST、SDK、キュー、ワークフローツールを使ってください。

結果を引き渡す

エージェントの実行を終える前に、エンドポイントのパス、リクエストパラメーター、返された ID、has_more、next_cursor、タスク ID、書き込みアクション ID、消費したクレジット、エクスポートやポーリング用のルートを保存します。

コピーして使えるエージェント指示

次の内容を、エージェントのシステム指示、プロジェクト指示、またはタスクのプロンプトに貼り付けてください：

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 the tool named in the catalog entry's `tool` field (`twexapi_request` for reads, `twexapi_write` for writes) with the exact method and a relative path from that entry.

Rules:
- Never call absolute URLs through `twexapi_request` or `twexapi_write`.
- 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 every `twexapi_write` call as a production action. Ask for explicit user confirmation before posting or replying.
- Never repeat an X cookie or auth_token back in your answer.
- 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.
- If a tool returns "No credits left on this TwexAPI account", stop and tell the user to top up; do not retry.
- For downstream workflows, return compact JSON with route_used, request, rows or ids, has_more, next_cursor, and next_step.

よくあるワークフロー

トレンドトピックを調べる

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

引き渡すフィールド：country、topic、content、tweet_id、author_username、created_at、エンゲージメント指標、has_more、next_cursor。

ツイートを検索する

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 を続けて使う

引き渡すフィールド：元のクエリ、並び順、tweet_id、本文、投稿者情報、投稿日時、ツイートの URL、has_more、next_cursor。

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

Export a page of followers for @openai in CRM-ready JSON.

推奨ルート：

1. explore(category="followers")
2. twexapi_request で /twitter/followers/{screen_name}/{count}、または explore が返したページ／タスクのエンドポイント

引き渡すフィールド：元のアカウント、user_id、username、名前、プロフィール文、フォロワー数、認証状態、タスク ID、has_more、next_cursor。

リプライを取得する

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

引き渡すフィールド：元のツイート ID、リプライ ID、投稿者のユーザー名、本文、指標、ページ番号、has_more、next_cursor。

X の記事を取得する

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

引き渡すフィールド：記事 ID、タイトル、著者、Markdown の本文、抽出したリンク、元の URL、生成した要約。

書き込み操作を実行する

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. ツイートの本文とリプライ先をそのままユーザーに提示する
3. ユーザーの明示的な確認を待つ
4. twexapi_write で POST /twitter/tweets/create を呼び、cookie にユーザーの X の Cookie を渡す

MCP で使える書き込み操作は投稿だけです。その他の書き込み操作には REST API を使ってください。

引き渡すフィールド：確認の内容、メソッド、パス、ツイートの本文、tweet_id、ステータス、消費したクレジット、リプライ先、メディアの URL。Cookie は含めないでください。

引き渡し出力の形式

後から使うワークフローでは、エージェントにコンパクトな 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
}

CRM、スプレッドシート、データベース、キューに入れるレコードは rows に、次の処理が永続的な ID だけを必要とする場合は ids を使います。

安全モデル

TwexAPI MCP には 3 つの安全策があります。

エラー処理

MCP の認証に失敗した場合、ツールは実行されません。JSON-RPC のエラーを保持してください：

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": 401,
    "message": "Access token is invalid or expired"
  }
}

アカウントのクレジットがなくなっても接続は維持され、explore は無料ですが、その他のツール呼び出しは次を返します：

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

ツールが実行され、下位の TwexAPI API が 2xx 以外を返した場合は、エージェントにツールの結果を保持させます：

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

主なステータスの意味：

すべてのエラーメッセージは MCP ツールリファレンス を参照してください。

本番運用のガイド

• エージェントが投稿する必要がない場合は、読み取り専用で接続します（サインイン時に書き込みのチェックを外す）。
• 自律的に動くエージェントには、読み取り専用のワークフローを優先します。
• 書き込みを伴うワークフローでは、プロンプト、リクエストボディ、ルート名、MCP のレスポンスを記録します。
• twexapi_write を呼ぶ前には、毎回人による承認を必須にします。
• Cookie、認証トークン、API キー、DM の本文は、ユーザーに見せる最終メッセージに含めないでください。
• 別の処理が作業を引き継ぐ場合は、カーソルとタスク ID をチャットの外に保存します。
• 再試行、キューイング、永続的な保存が必要な本番の定期ジョブには、REST または生成された SDK を直接使ってください。