---
title: "エージェント MCP ハンドオフ"
description: "AI エージェントと下流ワークフローへ Twexapi MCP アクセスを安全に引き渡す手順。"
---

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

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

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

1. **API MCP サーバーを接続**

    MCP クライアントに `https://api.twexapi.io/mcp` を追加。`x-api-key` または `Authorization: Bearer <token>` のいずれか。

2. **Docs MCP サーバーを接続**

    エージェントが API ルート選択前に Twexapi ドキュメントを検索すべきときは `https://docs.twexapi.io/mcp` を追加。

3. **呼び出し前に探索**

    タスクに合う query または category で、まず `explore` を呼ぶよう指示。

4. **相対パスを要求**

    `explore` が返した相対パスのみで `twexapi_request` を呼ぶよう指示。

5. **ハンドオフフィールドを保持**

    最終出力に ID、カーソル、task ID、ルート名、ステータス、クレジットフィールドを必須化。

6. **書き込みは慎重に**

    `read_only` が `false` のエンドポイント前に明示的なユーザー確認を要求します。

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

### まずドキュメントを読む

公開ドキュメント、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、課金クレジット、エクスポート/ポールルートを保存。

## コピペ用エージェント指示

システム指示、プロジェクト指示、タスクプロンプトに貼り付け:

```txt
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.
```

## よくあるワークフロー

### トレンドトピックのリサーチ

```txt
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`.

### ツイート検索

```txt
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`.

### フォロワーエクスポート

```txt
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`.

### 返信のスクレイピング

```txt
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 記事の取得

```txt
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.

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

```txt
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 を返させます。

```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 つの重要なガードレールがあります。

| ガードレール | 挙動 |
| --- | --- |
| API key auth | MCP は REST API と同じ API キー検証、クレジットチェック、アカウント制御を使用。 |
| Allowlisted paths | `twexapi_request` は MCP カタログ外のエンドポイントを拒否。 |
| Write flags | 副作用アクションは `read_only: false` とマークされ、エージェントが確認を要求可能。 |

## エラー処理

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

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

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

```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 取得問題。 |

## 本番ガイダンス

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