Skip to Content
MCP連携(Claude Code)ワーカーエージェントの操作

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

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

接続先

エンドポイント用途
https://mcp.tocca.systems/api/mcp/worker-agentワーカーエージェントの作成・更新・実行・実行結果の確認

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:* + attendance:read + attendance_team:read + user:read + task:write が目安です。勤怠を読むツールは、本人用の attendance:read に加えてチーム勤怠閲覧の attendance_team:read も求めます(どちらか一方だけでは 422 になります)。担当タスクの一覧も見せるなら task:read を加えてください。

利用できるツール

分類ツール
ツールカタログ・上限list_worker_agent_tools / get_worker_agent_tool / get_worker_agent_limits
エージェントlist_worker_agents / get_worker_agent / create_worker_agent / update_worker_agent / delete_worker_agent
有効・無効enable_worker_agent / disable_worker_agent
実行run_worker_agent / list_worker_agent_runs / get_worker_agent_run / get_worker_agent_run_steps / cancel_worker_agent_run

見えるのは自分がオーナーのエージェントだけです。他のユーザーのエージェント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経由で作成されました」という通知が届きます。

twp CLI から立ち上げる(定期分析エージェントの例)

twp CLI を使うと、指示文をファイルに書いてコマンド1つでエージェントを作成し、その場で1回試してから定期実行に切り替えられます。MCP クライアントを用意しなくても、同じエージェントを作れます。

ここでは例として、見積・請求の差し戻しを毎週分析し、申請前AIチェックの観点追加案を出すエージェントを立ち上げます。分析・改善系のほかの用途(勤怠の傾向確認、タスクの滞留確認など)も、指示文と許可ツールを入れ替えるだけで同じ手順で立ち上げられます。

1. 許可するツールを決める

twp worker-agent tools で、許可できるツールの正確な名前を確認します(--keyword や --category で絞り込めます)。

twp worker-agent tools --category sales

この例で使うツールは次のとおりです。

ツール種別用途
list_sales_send_backs参照直近の差し戻し記録(承認者のコメントと、差し戻し時点のAIチェックの指摘・申請者の理由)を取得する
get_sales_send_back_summary参照週ごとの差し戻し件数を取得する(件数は集計済みの値をそのまま使う)
list_sales_ai_review_criterion_proposals参照これまでに出した観点追加案と採否・採否日時を確認する
propose_sales_ai_review_criterion書き込み観点追加案を提出する(承認者が画面で採否を決めるまで、AIチェックには反映されません)
create_note書き込み週次の報告をノートに残す
get_department_tree / list_department_members参照報告先(承認者)を部署から引き当てる
send_notification_to_users書き込み承認者へ報告を通知する
  • エージェントはオーナーの権限で動きます。差し戻し記録を読むツールは、オーナーが見積・請求の一覧を全プロジェクト分閲覧できないと実行時に権限エラーになります。観点追加案の提出と一覧の参照には、販売管理の管理者権限が必要です
  • 差し戻し記録は記録を始めた時点から残ります。それより前の差し戻しは、件数・分類の対象になりません

2. 指示文をファイルに書く

指示文は --instructions-file で渡します(20,000文字まで)。「何を取得し、どう判断し、何をどこへ出すか」を順に書くと、実行のたびに同じ形の結果が得られます。

あなたは見積・請求の承認フローの差し戻しを分析し、申請前AIチェックを継続的に改善する担当です。毎週次の手順で進めてください。 ## 1. 差し戻しを集めて分類する - list_sales_send_backs で直近7日間の差し戻しを取得する(next_cursor があれば続きも取得する) - 承認者のコメントから指摘内容を読み取り、分類する(例: 明細の単位、有効期限と前提条件の不一致、備考の記載漏れ、添付ファイルの誤り、宛名・注文書番号の不一致、AIチェック指摘への理由不足) ## 2. AIチェックで指摘できていたかを突き合わせる - 分類ごとに、差し戻し時点のAIチェック(ai_review の観点・指摘文・申請者の理由)に同じ内容の指摘があったかを確認する - 指摘できていなかった分類 → propose_sales_ai_review_criterion で観点追加案を提出する - 先に list_sales_ai_review_criterion_proposals で同じ趣旨の案が既に出ていないか確認し、重複して出さない - 本文は全社共通の基準として書く。取引先名・案件名・個人名は書かない - 根拠にした差し戻し記録の id を send_back_record_ids に入れる - 指摘できていたのに差し戻された分類 → 原因(申請者の見落とし、理由の記載が不十分 等)を整理する。案は出さない - ai_review が null の記録は突き合わせできないため、分類だけ行う ## 3. 効果を確認する - get_sales_send_back_summary で直近8週の差し戻し件数の推移を取得する(件数は自分で数え直さず、返った値を使う) - list_sales_ai_review_criterion_proposals で採用済み(adopted)の案を取得し、案ごとに採用日以後の同じ分類の差し戻し件数を示す - 採用後も減っていない観点は「見直し対象」として挙げる ## 4. 報告する - create_note で「差し戻し週次分析 YYYY-MM-DD」というノートを作り、次の順で書く 1. 件数の推移(週ごと・見積/請求別) 2. 今週の分類と件数 3. 提出した観点追加案(分類・根拠件数) 4. 指摘できていたのに差し戻された分類と原因 5. 見直し対象の観点 - get_department_tree で「<承認者の部署名>」の部署IDを調べ、list_department_members でメンバーを取得してから、send_notification_to_users で承認者へ通知する - ノートはこのエージェントのオーナーしか開けないため、通知の本文だけで内容が分かるように書く(提出した観点追加案の分類・根拠件数、件数の推移の要点) - 観点追加案を提出した週は、採否をお願いする旨と採否画面の場所(「取引 > AIチェック理由」タブ下部の「差し戻し由来の観点追加案」)を書き、url に propose_sales_ai_review_criterion が返す review_url(/v1/sales/ai-review-reasons#criterion-proposals)を指定する。通知から採否画面へ直接移動できる - 差し戻しが0件の週は、件数の推移だけをノートに残し、通知は送らない

3. 作成して1回試す

twp worker-agent create \ --name "差し戻し週次分析" \ --instructions-file instructions.md \ --tool list_sales_send_backs,get_sales_send_back_summary,list_sales_ai_review_criterion_proposals \ --tool propose_sales_ai_review_criterion,create_note,get_department_tree,list_department_members,send_notification_to_users \ --schedule weekly:mon@09:00 \ --write-enabled --yes # 書き込みはせず「何をしようとしたか」だけを記録して試す(AI のクレジットは消費します) twp worker-agent run start "差し戻し週次分析" --simulate --wait --yes # 内容に問題がなければ実際に1回実行する twp worker-agent run start "差し戻し週次分析" --wait --yes
  • 作成直後は無効です。run start による手動実行だけが行われます
  • --wait は実行が終わるまで待ち、最終要約を先頭にした実行記録を表示します(終了コード 0=成功・3=失敗または取消・4=待ち時間の上限に達したが実行は継続中)
  • 途中の判断を確かめたいときは twp worker-agent run steps "差し戻し週次分析" <実行ID> でステップログを確認します

4. 定期実行に切り替える

twp worker-agent enable "差し戻し週次分析" twp worker-agent get "差し戻し週次分析" # スケジュールと次回実行予定を確認する

指示文やツールを変えるときは twp worker-agent update で、変えたい項目だけを指定します。止めるときは twp worker-agent disable です。

スケジュールの書式

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

{ "type": "weekly", "days_of_week": [1], "time_of_day": "09:00", "timezone": "Asia/Tokyo" }
type必須の項目制約
interval(一定間隔)interval_minutes15〜1440分・5の倍数のみ(00:00 起点で揃えます)
daily(毎日)time_of_day(HH:mm)—
weekly(毎週)time_of_day・days_of_week曜日は ISO 番号(1=月曜 … 7=日曜)
monthly(毎月)time_of_day・days_of_month または last_day_of_month存在しない日(2月31日など)はその月は実行しません
  • タイムゾーンは Asia/Tokyo 固定です(他の値はエラーになります)
  • 時刻指定の実行は、指定時刻から最大5分遅れて始まることがあります
  • 自動実行がまだ有効になっていない環境では、作成・更新・有効化の応答に schedule_notice が含まれます。その間スケジュールは保存されますが自動では動かず、run_worker_agent による手動実行だけが行われます

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

上限値
手動実行1エージェントあたり 1日20回
有効にできるエージェント1ユーザー3件・1テナント20件
1エージェントの許可ツール64個まで

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

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

うまくいかないとき

症状確認すること
422 で missing_scopes が返るAPIキーに不足スコープを追加する(上の「必要なスコープ」)か、そのツールを許可ツールから外す
422 で allowed_tools のエラーになるlist_worker_agent_tools が返す名前をそのまま使う
404 になる自分がオーナーのエージェントか、agent_id が正しいかを確認する
設定した時刻に動かない応答に schedule_notice が含まれていないか、エージェントが有効(is_enabled=true)かを確認する
Last updated on