認証情報を選ぶ
API キー版は引き続き
list_models、get_balance、chat_completion、generate_image、generate_video、get_task です。同名でも個人トークンでは入力が異なるため、接続後に tools/list を取得してください。
トークンの作成と接続
- ダッシュボード → Agent にログインし、Personal MCP を開きます。
- 名前と必要最小限の権限を選び、有効期限を 1～365 日（既定 30 日）に設定します。
models:invokeまたはutilities:invokeには自分の有効な API キーを紐付けます。モデル制限、予算、RPM はそのまま適用されます。アカウント照会には正の残高は不要です。- 作成時に
mcp_user_トークンをクライアントのシークレット設定へ保存します。コード、チャット、ログに記載しないでください。不要になったら同じ画面で取り消します。
Authorization ヘッダーに対応したクライアントが必要です。バージョンはクライアントが交渉します。OAuth は未対応で、OAuth 専用クライアントは接続できません。表は接続情報であり、特定クライアント用の設定ファイルではありません。
呼び出す前にツールを確認
接続初期化後、get_capabilities を {} で呼び出し、tools/list を確認します。audience: user、ownership: self、許可された scopes とツール、oauth: false が返ります。他の個人用ツールでは、業務パラメーターがなくても input オブジェクトが必要です。
権限
権限はサイトで設定します。MCP 自身による認証情報作成、権限拡大、管理者への昇格はできません。非表示ツールを直接呼んでも、毎回所有者と権限が確認されます。usage:content には明示的な取得要求とキーの内容記録設定も必要です。
書き込み・結果・再試行
書き込みごとに、その意図専用のidempotencyKey（空白なしの印字可能 ASCII 1～191 文字）を事前に保存します。応答を失ったら同じツール・入力・キーで再試行します。別入力で同じキーを使うと idempotency_conflict になります。アップロードの各手順には個別のキーを使います。
structuredContent と content の JSON テキストで返ります。初回は下記の形式です。再送時は replayed: true と識別子を含む小さな receipt を返し、完全な結果やキーの秘密値は返しません。
execution_pending（409）は初回の結果待ちです。execution_unknown（409）または status: unknown は、操作がすでに行われた可能性を示します。get_execution と対象タスク・注文・操作を確認します。新しいキーでこれらの状態を回避しないでください。 MCP 実行完了でも、モデルタスクやサイト確認は保留中の場合があります。
モデルとユーティリティの利用
list_models → get_model_schema で公開モデル ID を選びます。body には対応する HTTP JSON リクエスト全体を渡します。モデル ID は body.model、generate_content では代わりに外側の model が必須です。ファイル指定は edit_image の image、image[]、mask のみ。他のメディア入力には公開 URL を使います。
task_id を保存して get_task で確認します。stream: true のイベントは最終 MCP 結果にまとめられます。SDK のリアルタイム配信には HTTP API を使います。任意の UUID v4 client_request_id は動画リクエスト照合用で、idempotencyKey とは別です。モデル実行はクレジットを消費する場合があります。
モデル結果の収集上限は 8 MiB・300 秒です。中断または上限超過時は、判明している request_id が実行記録に残ります。まず get_execution と既存のリクエスト・タスクを確認し、未解決の呼び出しを新たな有料リクエストや新規冪等キーで置き換えないでください。クライアントの切断は、受理済みモデルタスクのキャンセルを意味しません。
32 種類のユーティリティは list_utilities → get_utility_schema → run_utility の順に使います。利用条件と上限は維持され、一部の一括操作には有料アカウント資格が必要です。値は parameters、自分のファイル ID は files に入れます。バイナリや大きな出力は一時ファイルとなり、ファイル入力・非 JSON 出力には files:write も必要です。
ファイルのアップロードと取得
- ファイル名・MIME 型・正確なバイト数で
begin_uploadを呼びます。最大 250 MiB です。 - 0 始まりの
indexと Base64dataでupload_chunkを呼びます。復号後は最大 1 MiB、インデックスは 0 から連続させます。 file_idと任意の小文字 SHA-256 でfinish_uploadを呼び、status: readyを確認します。- 対応ツールへ ID を渡します。
get_artifactはメタデータ、offset指定時は Base64 バイトを返します。next_offsetがnullになるまで続けます。ダウンロードリンクには所有者のサイトログインが必要です。
upload_image と upload_media は別の公開操作です。結果の URL は共有可能なので、その URL でアクセスを許可するファイルだけ公開してください。
ファイル操作は内容を読む前に、所有者、準備状態、件数、サイズを確認します。同じ ID を繰り返しても、各参照が件数と合計サイズに加算されます。
upload_media：最大 20 ファイル、合計 250 MiB。upload_image：1 ファイル、最大 50 MiB。edit_image：全フィールドで最大 20 ファイル、うちmaskは最大 1 ファイル。1 ファイル 50 MiB、合計 100 MiB。入力スキーマの各配列上限も適用されます。run_utility：get_utility_schemaが返す件数・個別サイズ・合計サイズの上限に従います。カタログの値が大きくても、合計は 250 MiB を超えられません。
サイト確認と支払い
- API キー秘密値：
start_reveal_key_action→ ユーザーがconfirmation_urlで承認 → 操作のidをaction_idとしてreveal_api_key。そのキーと認証情報に紐付き、操作作成から 15 分で失効し、一度だけ利用できます。create_api_keyはメタデータのみ返します。 - 契約解約：
cancel_subscriptionで確認を開始し、ユーザーがサイトで実行します。完了報告前にget_account_actionと契約状態を確認します。 - パスワード・アカウント削除：
start_account_actionにpassword_changeまたはdelete_accountを指定。メールコードとパスワードはユーザーがサイトに入力し、アシスタントには渡しません。削除後はアクセス失効・ログアウトとなるため MCP の照会を続けません。 - 支払い：
list_billing_products→create_checkout→ ユーザーが支払い →get_payment_status。リンク作成は支払完了ではありません。 - 実際の送信：
resend_invoiceとtest_credit_alertはメールや Webhook を送信します。ユーザーが明示的に依頼した場合だけ実行します。
重複操作を避けてエラーに対処
接続・認証エラーは HTTP エラーの場合があります。ツール失敗はisError: true となり、structuredContent.error.code、status、execution_id、receipt を確認します。再送では未完了の実行 status が返る場合もあります。
読み取りから始める例
- 支出確認：
get_balance→summarize_usage→ 個別のlist_usage。 - 失敗調査：
task_idでdiagnose_request。再実行前に実際のエラーと返金を確認。 - 接続準備：
list_models→get_model_schema→get_api_guide。ガイド取得にモデル実行は不要。 - 安全確認：
list_api_keys→get_api_key→list_login_records。
from 以上・to 未満です。既定は直近 30 日、最大 366 日。保存期間内の記録のみで、日付の欠落は利用ゼロを意味しません。get_overview.timezoneOffset は JavaScript getTimezoneOffset の分（UTC−現地時刻）で既定 0。履歴一覧と集計は UTC です。
summarize_usage の creditsCharged と netCreditsCharged は保存記録の純請求額です。linkedRefundCredits は非同期タスクに紐付いた既知の返金のみ。knownGrossCredits は純額とその返金の和で、完全な総支出ではありません。totalTokens、averageLatencyMs、pending、processing は一致する保存記録の値です。
全ツールリファレンス、認証、HTTP API エラーも参照してください。