症状：最初から大量のMCPツールを接続すると、誤操作、権限過多、原因不明の再試行が起きます。
最短解決策：まず読み取りツールと低リスク操作を少数だけ登録し、Tool Useの往復を観測できてから厳格な入力とStructured Outputsを追加します。
この記事は、初めてClaude Sonnet 5 APIを使うバックエンド開発者、既存のClaude Tool Use実装を見直したいチーム、そしてAgentを遠隔Mac上で継続運用したいエンジニア向けです。MCPを先に増やすのではなく、実行権限、タイムアウト、冪等性、人工的な承認経路まで含めて本番投入の順番を確認します。
※最終更新：2026年8月18日。Claude Sonnet 5の提供状況、対応モデル、プレビュー機能は、公式モデルページ、公式発表、APIのリリースノートを基に確認してください。
最初にツールの境界を固定する
Claude Sonnet 5 APIへ接続する前に、Agentが「何を判断し、何を実行してよいか」を分離します。最初の構成は、データを読むだけのツールと、失敗しても取り消しやすい低リスク操作に絞ります。たとえば検索結果の取得と、一時ファイルの作成は候補になりますが、メール送信、課金変更、公開リポジトリへの反映は承認付きの別経路に置きます。
ツール名は動詞と対象を含め、説明文には利用条件、返却値、失敗時の意味を書きます。入力Schemaには必須項目、列挙値、文字列の長さ制限を定義し、未指定なら実行できない形にします。説明が曖昧なツールは、モデルの推論能力ではなく設計上の欠陥を隠しているだけです。
Claude Sonnet 5 APIで外部ツールを呼び出すには、どこから始めますか。
APIリクエストのtoolsに、名前、説明、入力Schemaを登録します。ただし、モデルに実行権限を渡すわけではありません。モデルが返すtool_useブロックをアプリケーションが検証し、許可された実行器だけが処理します。公式のTool Use概要でも、ツールの実行主体はアプリケーション側として説明されています。
第二段階：最初のTool Use往復を記録する
最小の閉ループは、次の順番です。
- ユーザー要求と
tools定義を含むリクエストを送ります。 - Claudeが通常の文章、または
type: "tool_use"のブロックを返します。 - アプリケーションが名前と入力Schemaを検証します。
- 実行器がツールを呼び出し、
tool_use_idと結果を保存します。 type: "tool_result"を含む次のメッセージを送り、最終回答を受け取ります。
ここで重要なのは、結果を文字列だけで返さないことです。成功、対象なし、入力不正、権限拒否、外部サービス障害を区別できる形式にし、監査用の呼び出しID、開始時刻、終了時刻、実行主体を同じログへ残します。公式のTool Use結果処理ガイドにあるメッセージ順序とブロック形式を、実装の基準にしてください。
Claudeのツール呼び出し後は、どのように結果を返しますか。
モデルが返したtool_use_idを変更せず、対応するtool_resultへ結果を格納します。結果が空でも成功扱いにせず、statusやエラー分類を付けてください。これを省くと、Agentは「実行された」のか「空の結果だった」のかを判断できず、同じ操作を繰り返す可能性があります。
シナリオ：検索Agentで先に確認すること
検索ツールが「記事を探す」とだけ説明されていると、対象期間、言語、取得件数、権限範囲が毎回変わります。そこでquery、locale、date_rangeなどを入力項目として明示し、検索結果には取得元識別子と取得時刻を含めます。検索は読み取り専用でも、個人情報や社内文書を返す場合は、ツールの説明だけでなく実行器側でもアクセス制御が必要です。
第三段階：strictな入力と最終出力を分ける
ClaudeのstrictなTool Useは、ツールへ渡す入力をSchemaに従わせるための仕組みです。一方、Structured Outputsは、Agentが最終的に返す回答全体の構造を安定させるために使います。同じ「JSONを安定させる機能」と考えると、ツール入力は正しいのに最終回答が崩れる、または回答は整っているのに実行引数が不正という問題が残ります。
| 構成 | 主な対象 | 防げる問題 | 先に確認する条件 |
|---|---|---|---|
| 通常のTool Use | ツール選択と入力 | 自然言語だけの曖昧な引数 | ツール名、説明、Schema |
| strictなTool Use | 実行器へ渡す入力 | 必須項目欠落、型違い、許可外の値 | 実行前のSchema検証 |
| Structured Outputs | 最終レスポンス | JSON項目欠落、後処理不能な形式 | 必須項目と拒否時の形式 |
| MCP接続 | 共有ツールの発見と再利用 | クライアントごとの個別実装 | 接続先、認可、ツール一覧 |
Structured Outputsを使う場合でも、拒否、出力長による中断、Schemaが複雑すぎる場合の例外経路を残します。Structured Outputsの公式仕様に記載された対応モデルと制限は変更される可能性があるため、デプロイ時点のリリースノートと照合してください。
厳格なTool Useは、どのように設定すべきですか。
「厳格にする」だけでなく、入力Schemaを小さく保ち、実行前にサーバー側で再検証します。自由記述を引数にして内部で解釈する設計は、Schemaを置いても安全境界になりません。拒否や検証失敗をモデルへ返す場合も、秘密情報、内部スタックトレース、認証情報を含めないでください。
注意：入力がSchemaに適合していても、操作の意味まで安全とは限りません。送信先、金額、対象ファイルなどの業務条件は、モデルの外側にあるポリシー判定と人工的な承認で止められる構成にしてください。
第四段階：タイムアウト、再試行、冪等性を実行器へ置く
ネットワーク障害や外部APIの一時的な失敗を理由に、モデルへ無制限の再試行をさせてはいけません。ツールごとにタイムアウト、再試行可能なエラー、再試行不可のエラーを定義し、呼び出し回数の上限と全体の期限をアプリケーション側で管理します。
書き込み操作には冪等キーを付け、同じキーの処理済み記録を保存します。たとえば請求書の登録で応答だけが失われた場合、再試行前に処理状態を照会できなければ二重登録が起きます。削除、送信、公開のような不可逆操作は、ツールを分けたうえで人工的な承認を必須にするほうが、プロンプトだけで制御するより明確です。
利点は、失敗を分類しやすく、監査とロールバックの設計を実行器に集約できることです。欠点は、Schema、認可、状態保存、承認画面まで必要になり、単純なチャット連携より初期実装が重くなることです。それでも本番Agentでは、便利さより「誰が、何を、何度実行したか」を追えることが優先されます。
第五段階：MCPは共有が必要になってから追加する
Claude APIとMCPは、最初から一緒に使うべきですか。
単一のAgentが少数の専用ツールを使うだけなら、まず直接Tool Useを実装してください。複数のクライアントが同じツールを発見・再利用し、認可や更新を共通化する必要が出た時点でMCPを追加するのが安全です。
MCPを導入する際は、接続先の認証、通信経路、利用可能なツール一覧、一覧変更時の差分確認、第三者データの取り扱いを検査します。MCP Connectorの利用条件と対応範囲は、公式MCP Connector資料で確認できます。外部サーバーが返すツール説明を、そのまま高権限の実行許可へ変換しないことも重要です。
MCPの長所は共有性と発見性です。反対に、接続障害、ツール一覧の変更、認可の境界、第三者サービスへのデータ流出という新しい失敗点が増えます。直接接続で観測可能な閉ループを作ってから、同じ監査項目をMCP層へ移植してください。
最終段階：遠隔Mac環境を本番前に受け入れる
遠隔MacでAgentを動かす場合、APIが成功するだけでは受け入れ完了になりません。次の順で確認します。
- Agentプロセスを守るデーモンやサービス管理を設定し、異常終了後の再起動方針を決めます。
- APIキー、MCP認証情報、署名用秘密鍵を環境変数または秘密管理機構から読み込み、ソースコードへ書き込みません。
- 外向き通信、名前解決、必要ポート、プロキシ、ファイアウォールを実際の実行ユーザーで確認します。
- リクエストID、
tool_use_id、ツール名、入力の要約、結果分類、終了理由、承認者をログへ記録します。 - 秘密情報をマスキングし、ログの保存期間と閲覧権限を決めます。
- キーのローテーション、ツールSchemaの変更、MCP一覧の変更、前版へのロールバックを手順化します。
- 成功だけでなく、拒否、タイムアウト、重複要求、空結果、外部サービス停止を含む実タスクで記録を残します。
実行環境をMacstripeで用意する場合も、まず小規模な実タスクでプロセス再起動、ログ取得、環境変数の反映、ネットワーク経路を確認してください。利用期間や構成はタスクの検証期間に合わせて選び、長期の高負荷運用、物理インターフェース依存、常時稼働の厳格な要件がある場合は、自社設備との比較が必要です。注文前に利用開始までの設定手順を確認し、運用上の不明点はヘルプセンターで確認できます。
手元の開発機だけで試す構成は、初期費用を抑えやすい一方、電源断、スリープ、個人環境の認証、ログの散在、共有できない物理環境が障害になります。一般的なクラウド実行環境は管理しやすくても、macOS固有の自動化やXcode関連の確認、GUIを伴う処理では別の制約が出ます。運用期間が短く、Mac上での実タスク検証が目的なら、Macstripeのレンタル環境を使って切り分けるほうが、購入前に不確実な固定費を抱えずに済む場合があります。反対に、長期の安定した重負荷処理や物理ポート必須の案件では、専用の自社Macを選ぶほうが適切です。
