TypeScriptでAnthropic Agent SDKを使う：アーキテクチャとMCPセキュリティ

Anthropicのツールを中心に構築する安全なTypeScriptエージェントでは、MCPサーバーとツールの結果を別々の信頼ドメインとして扱う必要があります。認証情報をプロンプトに入れず、許可リストに登録したサーバーとツールだけを使い、すべての引数を検証し、影響の大きい書き込みには承認を求め、事後条件を確認してください。正確なSDK APIやパッケージのバージョンは変わる可能性があるため、実装の詳細は最新の公式ドキュメントで確認します。

コードを書く前に実行環境を把握する

まずコンポーネントを描きます。ユーザーインターフェース、エージェントの実行環境、モデルプロバイダー、MCPクライアント、MCPサーバー、ローカルまたはリモートのツール、データストア、承認サービスです。どこでIDを確立するか、どこにシークレットがあるか、どのコンポーネントが外部作用を起こせるかを示してください。この脅威モデルは、最初から大量のツール一覧を作るよりも役に立ちます。

TypeScriptでは、リクエスト、ツール入力、結果、エラー、承認記録のドメイン型を定義します。それでも実行時検証は必要です。静的型はプロセス境界を越えると消えるからです。JSON Schemaや検証ライブラリを使い、ツールを実行する前に未知のフィールド、無効な列挙値、大きすぎる値、想定外のURLを拒否します。

MCPの境界とサーバーの信頼性

MCPはコンテキスト交換を標準化しますが、プロトコル接続が安全性を保証するわけではありません。各サーバーについて、所有者、トランスポート、バージョン、利用可能なツール、必要なデータアクセスを一覧化します。自動検出より明示的な設定を優先してください。依存関係を固定し、ツール説明の変更をレビューします。説明はモデルの選択に影響するためです。

最小権限を使います。リポジトリを読むだけの処理にシェルアクセスは不要ですし、チケットの要約処理にチケット編集権限は不要です。可能であれば読み取りサーバーと書き込みサーバーを分離します。リモートトランスポートでは、最新の公式ガイダンスに基づいて認証、TLS、オーディエンス、テナント境界を確認してください。ローカルトランスポートでは、実行ファイルのパス、環境変数、作業ディレクトリを保護します。

ツールスキーマ、承認、トランザクション

ツール名は1つのアクションを表すべきです。入力には自由形式のコマンドではなく、限定された列挙値と長さに上限のある文字列を使います。リソース識別子は信頼できるコードで解決します。モデルに任意のファイルパス、SQL、シェル断片、コールバックURLを組み立てさせないでください。書き込みではプレビューを返し、ユーザーが正確な対象とペイロードを確認できるようにします。

そのプレビューに、nonce、有効期限、実行主体、ハッシュを結び付けて承認します。ペイロードが変われば承認は無効です。冪等性キーを使い、書き込み後に読み戻して検証します。ネットワークタイムアウトで結果が不明になったら、再試行する前に現在の状態を問い合わせます。これにより、コメント、注文、デプロイ、削除の重複を防げます。

シークレット、コンテキスト、プロンプトインジェクション

シークレットはシークレットマネージャーまたは保護されたプロセス環境に置き、必要とするツールだけに注入します。APIキーをモデルのコンテキストやログに入れてはいけません。テレメトリーに送る前に、ヘッダー、トークン、ユーザーデータ、ツール結果をマスキングします。ツールごとに外向き通信のルールを適用し、侵害されたサーバーが任意の宛先へデータを送れないようにします。

MCPから提供されたすべてのテキストを信頼できないものとして扱います。文書がエージェントに指示を無視させたり、別のツールを呼び出させたりする可能性があります。ソースのラベルと引用の境界を保持してください。システムポリシー、ユーザーの承認、ツール認可は、取得したコンテンツより優先されなければなりません。文書が自称する権威を受け入れるのではなく、機密性の高い判断には根拠を求めます。

可観測性と安全な失敗

構造化トレースを記録します。リクエストID、モデルの判断、選択したツール、検証済みパラメーター、ポリシーの結果、承認参照、ツールの受領記録、事後条件です。ログは不要なプロンプト内容を保持せずにインシデント調査を支えられるようにします。セキュリティイベントとアプリケーションのデバッグを分け、機密性に応じて保持期間を定めます。

IDがない、承認が期限切れ、スキーマが一致しない、未知のサーバーである、事後条件が曖昧である場合は、フェイルクローズします。再試行するのは分類済みの一時的エラーだけにします。ユーザーとツールごとにレートを制限し、ループのステップ数に上限を設け、停止スイッチを用意します。完了を証明できないエージェントは、成功したと主張せず不確実性を報告すべきです。

制御プレーンをテストする

モデルとは独立して、バリデーターと認可をユニットテストします。スキーマの不備、注入された指示、大きすぎるペイロード、遅い応答、偽の成功を返すモックMCPサーバーとの統合テストも追加します。テナントをまたぐ識別子や、古い承認の再利用をテストしてください。ツールの説明と返却コンテンツの両方をレッドチームで検証します。

リリース前に、Anthropic Agent SDKとMCPの最新ドキュメント、パッケージのバージョン、トランスポート要件、セキュリティ推奨事項を確認します。このガイドはアーキテクチャパターンを定義するもので、特定のSDKバージョンがすべての制御を自動的に強制するとは主張しません。

実装ワークシート

本番データを接続する前に、最小限のテストハーネスを作ります。読み取り専用のMCPサーバーを1つ登録し、実行時に入力を検証し、サニタイズしたトレースを取得します。準備、承認、コミット、検証が別々の操作として表現されてから、書き込みツールを追加します。その後、未知のサーバー、変更されたツールスキーマ、期限切れトークン、注入された文書テキスト、重複リクエスト、不確実なタイムアウトをテストします。パッケージ名、API、トランスポートの指針は変わり得るため、実装中も最新の公式SDK・プロトコル文書を確認してください。