ワーカーエージェントを MCP から操作する

ワーカーエージェントは、画面だけでなく MCP クライアント（Claude Code など）からも作成・実行・確認できます。「部下の稼働状況を毎週確認して私のタスクに登録するエージェントを作って、いま1回試して、問題なければ毎週月曜の朝9時に実行して」のように話しかけるだけで、AI がツールを順に呼び出して設定まで進めます。

接続先

Claude Code への登録例（APIキーの発行手順は Claude Code セットアップ を参照）:

claude mcp add --transport http twp-worker-agent https://mcp.tocca.systems/api/mcp/worker-agent \
  --header "Authorization: Bearer twpu_xxxxxxxx"

必要なスコープ

個人用APIキーには、次の2種類のスコープが両方必要です。

1. ワーカーエージェント自体の操作（「AIエージェント」グループ）

   スコープ	できること
   worker_agent:read	一覧・詳細・実行履歴・ステップログ・ツールカタログ・上限の確認
   worker_agent:write	作成・更新・削除・有効化・無効化
   worker_agent:execute	手動実行・実行のキャンセル
   worker_agent:*	上記すべて

2. エージェントに許可するツールのスコープ

   エージェントはオーナーの権限で動きますが、MCP から作成・更新・実行するときは、許可ツールが使うスコープをAPIキーも持っていることが確認されます。たとえば create_private_task（プライベートタスクの作成）を許可するなら task:write、list_subordinates（部下の一覧）を許可するなら user:read が要ります。各ツールに必要なスコープは list_worker_agent_tools の required_api_scopes で確認できます。

   足りない場合は 422 になり、不足しているスコープ名がそのまま返ります。

   API error 422: 許可ツールの実行に必要な権限がこの資格情報にありません（不足: task:write, user:read）。
   Error fields: {"missing_scopes":["task:write","user:read"]}

   「書き込み系ツールの実行を許可する」（write_enabled）をオフにしたエージェントでは、書き込みツールのスコープは求められません（参照ツールのスコープは必要です）。

例: 部下の勤怠・工数を確認してプライベートタスクへ登録するエージェントなら、worker_agent:* ＋ user:read ＋ task:write が目安です。担当タスクの一覧も見せるなら task:read を加えてください。

利用できるツール

見えるのは自分がオーナーのエージェントだけです。他のユーザーのエージェントIDを指定すると 404（見つかりません）になります。

作成から実行・確認までの流れ

1. ツール名を確かめる — list_worker_agent_tools で、許可できるツールの正確な名前を取得します。推測した名前を allowed_tools に入れると 422 になります
2. 作成する — create_worker_agent に名前・指示文・許可ツール・スケジュールを渡します。作成直後は無効（is_enabled=false）です
3. 試しに実行する — run_worker_agent を呼びます。dry_run: true を付けると書き込みは行わず、「何をしようとしたか」だけを記録します
4. 完了を確認する — run_worker_agent の応答は「実行を開始した」という意味で、結果ではありません。返ってきた run_id で get_worker_agent_run を呼び、status が succeeded / failed / cancelled / skipped になるまで確認します（通常は数十秒〜数分）。完了すると summary に実行内容の要約が入ります。途中経過は get_worker_agent_run_steps で確認できます
5. 定期実行にする — 問題がなければ enable_worker_agent で有効にします

MCP から作成したエージェントは、画面の一覧でも確認でき、作成時にはオーナーへ「MCP経由で作成されました」という通知が届きます。

スケジュールの書式

schedule は次の形式で指定します。

{ "type": "weekly", "days_of_week": [1], "time_of_day": "09:00", "timezone": "Asia/Tokyo" }

• タイムゾーンは Asia/Tokyo 固定です（他の値はエラーになります）
• 時刻指定の実行は、指定時刻から最大5分遅れて始まることがあります
• 自動実行がまだ有効になっていない環境では、作成・更新・有効化の応答に schedule_notice が含まれます。その間スケジュールは保存されますが自動では動かず、run_worker_agent による手動実行だけが行われます

実行回数の上限とクレジット

現在の値と当日の使用状況は get_worker_agent_limits で確認できます。

• run_worker_agent を連続で呼ばないでください。 呼ぶたびに手動実行を1回消費します。完了を待つときは get_worker_agent_run を呼び直してください
• ドライランでも、AI が考えるためのトークン分のクレジットを消費します
• 実行中・上限到達・クレジット不足などで実行できないときは 409 になり、理由（skip_reason）と run_id が返ります

うまくいかないとき