エージェント MCP ハンドオフ

AI エージェントと下流ワークフローへ Twexapi MCP アクセスを安全に引き渡す手順。

Twexapi MCP アクセスを AI コーディングエージェント、リサーチエージェント、ワークフローエージェント、社内アシスタントに渡すときにこのページを使いましょう。

要点: API MCP サーバーを接続し、API キーを渡し、twexapi_request の前に explore を呼ぶよう指示し、チャット要約だけでなく永続的なハンドオフ出力を要求します。

ハンドオフチェックリスト

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

まずドキュメントを読む

公開ドキュメント、API パラメータ、セットアップ、エラーコード、SDK ガイダンス、例には Docs MCP https://docs.twexapi.io/mcp を使用。

API ルートを探索

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

API 呼び出しを実行

API MCP twexapi_request で explore が返した正確なメソッドと相対パスを使用。ドキュメント化された query と body のみ渡す。

チャット外に永続化

バックエンドがリトライ、カーソル保存、ファイルダウンロード、スケジュールジョブ、バッチオーケストレーションを所有する場合は REST、SDK、キュー、ワークフローツールを使用。

結果をハンドオフ

エージェント実行終了前に、エンドポイントパス、リクエストパラメータ、返却 ID、has_more、next_cursor、task ID、write action 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 `twexapi_request` with the exact method and a relative path from the returned catalog entry.

Rules:
- Never call absolute URLs through `twexapi_request`.
- 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 any catalog entry with `read_only: false` as a production action.
- Ask for explicit user confirmation before posting, replying, liking, retweeting, following, blocking, bookmarking, deleting, sending DMs, or making any other write call.
- 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.
- 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 for /twitter/global-trending/countries
3. twexapi_request for /twitter/global-trending/topics
4. twexapi_request for /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 for /twitter/advanced_search/page
3. カタログがページネーションフローを返す場合は /twitter/advanced_search/page

ハンドオフフィールド: 元クエリ, ソートモード, tweet_id, text, author metadata, created time, direct URL, has_more, next_cursor.

フォロワーエクスポート

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

推奨ルート:

1. explore(category="followers")
2. twexapi_request for /twitter/followers/{screen_name}/{count} or a page/task endpoint returned by explore

ハンドオフフィールド: source account, user_id, username, name, bio, follower count, verified status, task 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 for /twitter/tweets/{tweet_id}/replies/{count} or /twitter/tweets/{tweet_id}/replies/page

ハンドオフフィールド: source tweet ID, reply ID, author username, text, metrics, page index, 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 for /x/article/{tweet_id}/markdown

ハンドオフフィールド: article ID, title, author, Markdown body, extracted links, source URL, generated summary.

書き込みアクションの実行

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. 正確な write body をユーザーに提示
3. 明示的確認を待つ
4. 返された write エンドポイントで twexapi_request

ハンドオフフィールド: confirmation text, method, path, request body, tweet_id, write_action_id, status, charged credits, reply target, media URLs.

ハンドオフ出力契約

永続ワークフロー向けに、エージェントへコンパクト 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、スプレッドシート、DB、キュー向けレコードは rows。次ワーカーが ID のみ必要なら ids。

安全モデル

Twexapi MCP には 3 つの重要なガードレールがあります。

エラー処理

MCP 認証失敗時、ツールは実行されません。JSON-RPC エラーを保持:

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

twexapi_request 実行後に基盤 Twexapi API が非 2xx を返した場合、ツール結果を保持させます:

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

解釈の目安:

本番ガイダンス

• エージェントが特定ワークフローのみ必要ならスコープ付き API キーを使用。
• 自律エージェントには読み取り専用ワークフローを優先。
• 書き込みワークフローではプロンプト、リクエストボディ、ルート名、MCP レスポンスをログ。
• read_only: false 呼び出し前に人間承認を必須化。
• cookie、auth token、API キー、非公開 DM 本文を最終ユーザー可視メッセージから除外。
• 別ワーカーがジョブ継続する場合、カーソルと task ID をチャット外に保存。
• リトライ、キュー、永続ストレージが必要なスケジュール本番ジョブは直接 REST または生成 SDK を使用。