劇作家のワークスペースのリモートMCPサーバーでブラウザを自動化

劇作家のワークスペースのリモートMCPサーバーは、AIエージェントに管理型リモートブラウザと一連のブラウザ自動化ツールを提供します。 エージェントはブラウザセッションを開き、ページを移動し、要素を見つけて操作し、ブラウザの活動を確認し、スクリーンショットを撮り、セッションを閉じることができます。 エージェント環境でPlaywrightやブラウザをインストールする必要はありません。

サーバーはStreamable HTTP上の Model Context Protocol を使用しています。 Microsoft Entra ID認証およびワークスペースアクセストークンをサポートしています。 Microsoft Foundry Agent ServiceやVisual Studio CodeなどのリモートMCPクライアントと連携します。

この記事では、次の方法について説明します。

• Playwrightワークスペース用のMCPエンドポイントを構築します。
• 認証はMicrosoft Entra IDまたはワークスペースのアクセストークンで行います。
• サーバーをMicrosoft Foundry Agent ServiceまたはVisual Studio Codeに接続してください。
• 完全なエージェント型ブラウザ自動化フローを実行してください。
• 利用可能なブラウザツールを選択して安全にご利用ください。
• セッションの期限切れ、タイムアウト、その他のよくあるエラーを処理してください。

Prerequisites

開始する前に、以下の項目があることを確認します:

• アクティブなサブスクリプションを持つ Azure アカウント。
• リモートMCPプレビューにアクセスできるPlaywrightワークスペースです。
• ワークスペースの ID と Azure リージョン
• ワークスペース内でブラウザセッションを作成・使用する権限を持つアイデンティティ。
• Microsoft Foundry については、Foundry プロジェクトと、プロジェクト接続を作成し、エージェントを構成するための権限。
• Visual Studio Codeは、GitHub CopilotアクセスとMCPサポートが有効な現行バージョンのVisual Studio Codeです。

認証方法の選択

MCPクライアントがOAuthやマネージドIDをサポートしている場合、Microsoft Entra IDを使用してください。 リモートMCPサーバーはこのリソース識別子と委任されたスコープを使用します:

Resource: https://mcp.playwright.microsoft.com
Scope: https://mcp.playwright.microsoft.com/Playwright.Mcp.Tools

サーバーはOAuth保護リソースメタデータを公開します。 Visual Studio Codeを含むOAuthディスカバリーをサポートするクライアントは、ワークスペーススコープのMCPエンドポイントから認証サーバーと必要なスコープを発見できます。 サインインしたアイデンティティは、Azureロールベースアクセス制御(RBAC)を通じてPlaywrightワークスペースへのアクセス権を持つ必要があります。

互換性のためにワークスペースアクセストークンを作成しましょう

Microsoft Entra IDを使う場合はこのセクションを飛ばしてください。 もしワークスペースでまだアクセストークン認証が有効になっていなければ:

1. Azure portal にサインインする
2. Playwrightの作業スペースを開いてください。
3. 設定の中からアクセス管理を選択します。
4. Playwright Service Access Tokenを有効にしてください。
5. [Generate token](トークンの生成) を選択します。
6. 名前と有効期限を入力し、トークンを生成します。
7. トークンをすぐにコピーします。 後で価値を取り戻すことはできません。

トークンは管理された秘密ストアか、MCPクライアントが提供する安全な認証情報施設に保存してください。 露出していた可能性がある場合は取り消して交換してください。 ワークスペースアクセストークンを作成するには 「ワークスペースアクセストークン管理」をご覧ください。

リモートMCPエンドポイントを構築する

エンドポイントは1つのワークスペースとリージョンにスコープが割り当てられています:

https://<region>.mcp.playwright.microsoft.com/playwrightworkspaces/<workspace-id>/mcp

置換してください。

• ワークスペースの Azure リージョンに <region> を。
• <workspace-id>ワークスペースIDはAzureポータルに表示されます。

例えば次が挙げられます。

https://eastus.mcp.playwright.microsoft.com/playwrightworkspaces/00000000-0000-0000-0000-000000000000/mcp

x-api-keyリクエストヘッダーの値は、<workspace-id>と同じワークスペースのために作成されたアクセストークンでなければなりません。 ワークスペースのリージョンのエンドポイントを使い、MCPクライアントに最も近いリージョンを使いません。

ブラウザセッションのライフサイクルを理解する

ブラウザ自動化フローは3つの段階から成り立っています。

1. create_browser_sessionを呼び出します。 その結果、不透明な browserSessionId が含まれ、ライブビューURLが含まれていることもあります。
2. その browserSessionId をフローで使うすべてのブラウザツールに渡してください。
3. フローが失敗した場合でも、クリーンアップ ステップで close_browser_session を呼び出してください。

MCPのHTTPトランスポートはブラウザの状態を保持しません。 browserSessionIdは、リモートブラウザを別々のツール呼び出しで識別します。 プライベートにして、作成したワークスペースとアイデンティティでのみ使用してください。

現在のプレビュー動作には以下の制約があります:

• セッションは作成者のものであり、他の主体と共有することはできません。
• 1セッションの呼び出しは順番に処理されます。 同じセッションに対して同時行動を出さないでください。
• 非アクティブなセッションは15分後にクリーンアップされます。 明示的なクリーンアップが必要です。
• 閉鎖または期限切れのセッションは再開できません。
• 接続が失われると、セッションは終了します。 新しいセッションを作成して継続してください。
• 結果には liveViewUrlが含まれることもあります。 ライブビューの利用可能状況はセッションによって異なります。

Microsoft Foundry Agent Service からの接続

Microsoft Entra Agent Identityを使って、Foundryプロジェクトの管理されたIDでエージェントを認証します。 MCPツールを接続する前に、そのIDにPlaywrightワークスペースへのアクセス権を付与してください。

プロジェクト接続を作成する

1. Microsoft Foundryポータルでプロジェクトを開いてください。
2. プロジェクトの管理体験を開き、「 接続済みリソース」を選択してください。
3. リモートMCPサーバー用の接続を作成します。
4. playwright-mcp-connectionのような記述的な接続名を入力してください。
5. 認証方法としてMicrosoft Entra Agent Identityを選択してください。
6. audience として https://mcp.playwright.microsoft.com を入力します。
7. 接続を保存します。

プロジェクトのマネージドアイデンティティは、ターゲットとなるPlaywrightワークスペース上でブラウザセッション操作を許可する役割を持つ必要があります。 あるプロジェクトのアイデンティティトークンを別のプロジェクトの共有シークレットとして使わないでください。

クライアントや環境でMicrosoft EntraエージェントIDが利用できない場合は、x-api-keyというキーとワークスペースアクセストークンを値としてカスタムキー接続を作成します。

リモートMCPツールの追加

1. Foundryポータルでエージェントを作成または開設してください。

2. リモートMCPサーバーやMCPツールを追加してください。

3. 次の設定を使用します。

   Setting	Value
   サーバーラベル	playwrightWorkspace のような一意のラベル
   サーバー アドレス	ワークスペーススコープ付きのリモートMCPエンドポイント
   プロジェクト接続	前に作成した Microsoft Entra エージェント ID 接続
   承認	統合を評価する際は、すべての通話で承認を求める
   許可済みツール	流れに必要な道具だけから始めましょう

4. エージェント構成を保存します。

5. エージェントの指示では、エージェントに1つのセッションを作成し、その browserSessionIdを再利用し、タスク終了時にセッションを終了するよう求めます。

読み取り指向のナビゲーションフローのための最小限のツール許容リストは以下の通りです:

create_browser_session
browser_navigate
browser_snapshot
browser_find
browser_take_screenshot
close_browser_session

browser_clickやbrowser_typeなどのインタラクションツールは、状況に応じてのみ追加しましょう。 デフォルトで browser_evaluate や browser_run_code を有効にしないでください。

ファウンドリーのフローのテスト

目標と清掃の必要性を明示したプロンプトを使いましょう。 例えば次が挙げられます。

Create a browser session, open https://example.com, inspect the page snapshot,
report the main heading and destination URL, and close the browser session.
Always close the session, including when a browser step fails.

エージェントが承認を求める場合:

1. サーバーラベルが設定されたPlaywrightサーバーであることを確認してください。
2. ツール名とすべての引数、特にURL、セレクター、テキスト、アップロードされたデータ、コードを確認しましょう。
3. 期待される作戦のみを承認する。
4. 最終回答がページ結果に基づいているか確認してください。
5. close_browser_sessionという名前のフローであることを確認してください。

現在の Foundry の接続フィールド、承認の処理、SDK の例、およびクライアントの制限については、「Connect agents to MCP server endpoints」を参照してください。

Visual Studio Code から接続する

Visual Studio CodeはリモートサーバーのOAuth設定を検出し、Microsoft Entra IDでサインインできます。 構成にはワークスペーススコープのエンドポイントのみが必要です。

1. Visual Studio CodeでコマンドパレットからMCP: Open User Configurationを実行します。
2. 以下の構成を追加し、エンドポイントのプレースホルダーを置き換えます。

{
  "servers": {
    "playwrightWorkspace": {
      "type": "http",
      "url": "https://<region>.mcp.playwright.microsoft.com/playwrightworkspaces/<workspace-id>/mcp"
    }
  }
}

3. 設定エディタからサーバーを起動するか、 MCP: List Serversを実行します。
4. 促されたら、PlaywrightワークスペースにアクセスできるMicrosoft Entraアカウントでサインインしてください。
5. テナントで同意が必要な場合は、要求された Playwright.Mcp.Tools アクセス許可を承認してください。
6. サーバーのURLと設定を確認し、そのサーバーを信頼しているか確認してください。
7. チャットを開き、「 ツールの設定」を選択してください。 作業に必要な劇作家ツールのみを有効にしてください。
8. 前のFoundryセクションの例示プロンプトを実行してください。
9. ツールの確認を確認し、セッション終了時に終了したことを確認します。

個人接続の場合はユーザー設定を使いましょう。 エンドポイントのみを含むワークスペース構成は共有可能です。 Visual Studio CodeはOAuth認証情報を安全にキャッシュし、再接続時に再利用できます。

クライアント環境で Microsoft Entra 認証を利用できない場合は、x-api-keyで説明されているように、保護された入力を使用して ヘッダーを構成してください。 ワークスペースのアクセストークン値を直接 mcp.jsonに入れないでください。

構成場所、秘密入力、サーバー信頼、診断について、Visual Studio CodeのMCPサーバーの追加と管理およびMCP設定参照を参照してください。

エージェント型自動化フローの設計

ページ状態を確認せずに長いシーケンスを実行するようエージェントに求めるのではなく、観察・行動・検証ループを使いましょう。

1. 作成:create_browser_sessionを呼び、その browserSessionId を保持しましょう。
2. ナビゲーション: 明確で承認されたURLを browser_navigate に電話してください。
3. 注: 絞り込んだ検索には browser_find、より広範なアクセシビリティ表示には browser_snapshot を使用します。
4. 行動: スナップショット参照または一意セレクターとインタラクションツールを組み合わせて使用します。
5. 待ってください: 期待されるテキスト、消えるテキスト、または有制限の遅延のために browser_wait_for に電話してください。
6. 確認: 別のスナップショットをキャプチャするか、コンソールやネットワークの活動を点検してください。
7. 分岐の処理: ダイアログの処理、タブの切り替え、ページの状態が必要な場合のみファイルのアップロード。
8. 証拠の収集: 視覚的な結果が役立つ場合は browser_take_screenshot に連絡してください。 アクションターゲットを選ぶ際にスクリーンショットは使わないでください。
9. クリーンアップ: finally スタイルのクリーンアップ パスで close_browser_session を呼び出します。

安定した行動標的を選ぶ

browser_snapshotまたはbrowser_findからの推薦状を優先してください。 これらはアクセス可能なページ要素を記述し、実装固有のマークアップへの依存を減らします。 安定したスナップショット参照がない場合は、ユニークなセレクターを使いましょう。

ナビゲーション後やページ変更の後、スナップショットをリフレッシュしてください。 以前に返されたターゲットは、ページが再レンダリングされると無効になることがあります。

会話を安全に処理する

アクションはすでにページの状態を変更した後に、 dialog-opened 結果を返すこともあります。 この結果は通常のアクション失敗ではありません。

1. 元の行動を繰り返さないでください。
2. false を accept または browser_handle_dialog に設定して、true を呼び出します。
3. プロンプトダイアログの場合は、 promptText を受け入れる時のみ含めてください。
4. 続ける前にもう一度ページをよく見てください。

曖昧な故障の処理

タイムアウトや通話切断が行動に効果がなかった証拠にはなりません。 クリック、フォーム送信、アップロード、コード実行などの冪等ではない操作を再試す前に:

1. セッションがまだ空けていれば、 browser_snapshot、 browser_find、または他の観察ツールに連絡してください。
2. 期待される状態の変化が発生したかどうかを判断します。
3. 繰り返しても安全な場合だけ再挑戦してください。
4. セッションが終了した場合は、新しいセッションを作成し、既知のアプリケーション状態から再起動します。

ツール リファレンス

すべてのブラウザスコープツールは browserSessionIdが必要です。 ここに示されている文字列およびコレクションの境界は現在のプレビュー制限です。

セッションツール

ナビゲーションおよび観測ツール

対話ツール

タブ、ファイル、コードツール

各自動化ワークフローの実行後、アクティブなclose_browser_sessionを使ってbrowserSessionIdを呼び出してください。

フォームフィールドの形状

各 browser_fill_form 場は次の形状をしています:

{
  "target": "<snapshot-reference-or-selector>",
  "value": "<string-or-boolean>",
  "name": "<optional-display-name>",
  "type": "<optional-field-type>"
}

フィールドの文字列値は最大100 KiBの文字を含めます。 name 最大1,024文字まで、 type 最大128文字まで収録可能です。

ファイルアップロード形状

各 browser_file_upload ファイルは以下の形状を使用しています:

{
  "name": "example.txt",
  "data": "SGVsbG8sIHdvcmxkIQ==",
  "mimeType": "text/plain"
}

mimeType は省略可能であり、既定値は application/octet-stream です。

ファイルアップロードの制限

• 1つのツールコールで1〜20ファイル。
• 各ファイルあたり最大10 MiBのデコードサイズ。
• 最大50 MiBの合計復号サイズ。
• 最大4,096文字のファイル名。
• 最大1,024文字のMIMEタイプ。
• 有効なbase64データが必要です。

JavaScriptツール形状

browser_evaluateに対して、関数式を渡します:

() => document.title

targetを提供すると、関数はマッチング要素を受け取ります:

element => element.textContent

browser_run_codeの場合、pageパラメータがPlaywrightページである非同期関数の本体を形成する文をパスします。 JSONで直列化可能なデータのみを返し、インライン応答の制限内に収めてください。

限界と現在の挙動

回答はインラインで返されます。 このプレビューでは、MCPリソースや大規模なスナップショット、スクリーンショット、ダウンロードのための永続的なアーティファクトストレージを公開しません。 ブラウザ、オペレーティングシステム、ビューポート、ロケール、ユーザーエージェントのオーバーライドはセッション作成パラメータとして公開されません。

エラー処理

ツールエラーには、安定したエラーコード、顧客安全メッセージ、 retryable 値、相関情報が含まれます。 返された retryable 値を主信号として使い、手術の副作用も含めて使用します。

一般的な問題のトラブルシューティング

MCPクライアントが「Unauthorized 」を報告します

• ワークスペースでアクセストークン認証が有効になっているか確認してください。
• トークンが期限切れや取り消しになっていないか確認してください。
• x-api-key値として生のトークン価値を使います。 Bearerプレフィックスは付けないでください。
• トークンとエンドポイントが同じワークスペースに属しているか確認してください。
• もし秘密を誤ってコピーした場合は、ポータルから既存の値を取得できないので新しいトークンを作成してください。

MCPのクライアントは禁止されていると報告しています

• トークンに関連付けられたユーザーがまだブラウザセッションを作成する権限を持っているか確認してください。
• 同じプロジェクト接続やトークンで、1つのブラウザセッション内のすべての通話に使います。
• ユーザー間、異なる認証情報を使うエージェント間、ワークスペース間で browserSessionId を渡さないでください。

道具は発見されません

• /playwrightworkspaces/<workspace-id>/mcpを含む全エンドポイントを確認してください。
• エンドポイントリージョンがワークスペースリージョンと一致しているか確認してください。
• クライアントがHTTP MCPトランスポートを使用し、ディスカバリーやツール呼び出し時に x-api-key を送信していることを確認しましょう。
• Visual Studio CodeでMCP: List Serversを実行し、サーバーを選択してから「出力表示」を選択します。
• エンドポイントを変更した後は、MCP接続を再起動するかキャッシュツールをリセットしてください。

担当者はブラウザツールを呼びかけません

• エージェントに明確に設定済みのPlaywright MCPサーバーを使うよう伝えてください。
• 必要なツールがクライアントの有効または許可ツールリストに表示されているかを確認してください。
• エージェント命令に「作成-使用-閉じ」ライフサイクルを含めること。
• 最初のタスクは集中し、ナビゲーション目標と期待される結果を一つに設定しましょう。

ターゲットは動作しなくなりました

ページがナビゲートされたり、再レンダリングされたりしたのかもしれません。 再度 browser_snapshot か browser_find に電話して、現在の参考文献を使ってください。 生成されたクラスに紐づくセレクタやドキュメント構造の変更は避けましょう。

ツールがタイムアウトしました

状態を変えずにアクションが失敗したと決めつけないでください。 セッションがアクティブであれば、再試行前に現在のページを確認してください。 セッションが期限切れの場合は、新しいセッションを作成し、アプリケーションを既知の状態に戻します。

スクリーンショットは大きすぎます

type: "jpeg"を使うか、ビューポートのみをキャプチャするか、要素レベルのスクリーンショットのターゲットを用意してください。 視覚的証拠を保存するのではなく、要素を特定することが目的の場合に browser_snapshot を活用しましょう。

フロー中にセッションが終了しました

新しいブラウザセッションを作成します。 ブラウザ接続の喪失、サービスオーナーの喪失、明示的な終了、またはアイドルクリーンアップの後はセッションが再接続されません。 既知のURLとアプリケーション状態から再スタートできるようフローを設計してください。

セキュリティに関する推奨事項

• エージェントのタスクに必要なツールだけを許可してください。
• 状態変更、ファイル、コードの各ツールでは、人間の承認を必須にしてください。
• ページコンテンツ、アクセシビリティスナップショット、コンソール出力、ネットワーク出力は信頼できないものとして扱いましょう。 ページにはプロンプトインジェクション命令を含めることができます。
• システム命令とページ由来のテキストは分けて保管してください。 ページの内容がセキュリティポリシーや承認ルールを変えないようにしましょう。
• 機密アプリケーションの自動化時に、受信先URLを許可リストと照らして検証してください。
• ツールコールを承認する前に、テキスト、セレクター、ファイルの内容、コードを必ず確認してください。
• プロンプト、ソースファイル、スクリーンショット、アップロード済みファイル、JavaScriptのスニペットでアクセストークンを使わないでください。
• 短命なトークンを使い、定期的にローテーションし、未使用の接続は取り消しましょう。
• 各トラスト境界に専用のワークスペースと最小権限IDを使いましょう。
• 承認やツール名を監査用に記録しつつ、認証情報、アップロードされたコンテンツ、機密ページデータは記録しないでください。

地域ごとの提供状況

劇作家のワークスペースは以下のAzureリージョンで利用可能です:

関連するコンテンツ

• ワークスペースアクセストークンの管理
• Playwrightワークスペースへのアクセス管理
• Microsoft FoundryエージェントをMCPサーバーエンドポイントに接続する
• Visual Studio CodeでMCPサーバーを追加・管理
• モデル コンテキスト プロトコルのドキュメント