使用 劇作家工作區 遠端 MCP 伺服器自動化瀏覽器

劇作家工作區 遠端 MCP 伺服器為 AI 代理提供可管理的遠端瀏覽器及一組瀏覽器自動化工具。 客服人員可以開啟瀏覽器會話、瀏覽頁面、尋找並互動元素、檢查瀏覽器活動、截圖，然後關閉會話。 你不需要在代理環境中安裝 Playwright 或瀏覽器。

伺服器採用可串流 HTTP 上的 模型上下文協定（Model Context Protocol ）。 它支援 Microsoft Entra ID 認證及工作區存取權杖。 它支援遠端 MCP 用戶端，包括 Microsoft Foundry Agent Service 和 Visual Studio Code。

在本文中，您將學會如何：

• 為 Playwright 工作區建立 MCP 端點。
• 請使用 Microsoft Entra ID 或工作區存取權杖進行驗證。
• 將伺服器連接到 Microsoft Foundry 代理服務或 Visual Studio Code。
• 執行完整的代理式瀏覽器自動化流程。
• 選擇並安全使用可用的瀏覽器工具。
• 處理會話過期、逾時及其他常見錯誤。

先決條件

開始之前，請確定您擁有：

• 一個有有效訂閱的 Azure 帳號。
• 一個可遠端存取 MCP 預覽的 Playwright 工作區。
• 工作區的 ID 和 Azure 區域。
• 一個有權限在工作空間中建立和使用瀏覽器會話的身份。
• 針對 Microsoft Foundry，您需要 Foundry 專案，以及建立專案連線和設定代理程式的權限。
• 對於 Visual Studio Code，需使用目前版本的 Visual Studio Code，並已啟用 GitHub Copilot 存取權和 MCP 支援。

選擇驗證方法

當您的 MCP 用戶端支援 OAuth 或受管理身份時，請使用 Microsoft Entra ID。 遠端 MCP 伺服器使用此資源識別碼及委派範圍：

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

伺服器會發布 OAuth 受保護資源的元資料。 支援 OAuth 發現的用戶端，包括 Visual Studio Code，可以從工作空間範圍內的 MCP 端點中發現授權伺服器及所需範圍。 登入的身份必須透過 Azure 角色基礎存取控制（RBAC）存取 Playwright 工作區。

建立一個工作區存取權杖以促進相容性

使用 Microsoft Entra ID 時請跳過此部分。 如果工作區尚未啟用存取權杖驗證：

1. 登入 Azure 入口網站。
2. 打開你的劇作家工作空間。
3. 在 設定中，選擇 存取管理。
4. 啟用 Playwright Service Access Token。
5. 選擇 產生代幣。
6. 輸入名稱和有效期限，然後產生代幣。
7. 立刻複製令牌。 你無法事後找回它的價值。

將憑證存放在管理的秘密儲存庫或 MCP 用戶端提供的安全憑證設施中。 如果可能有外洩，請撤銷並更換。 要建立工作區存取權杖，請參見管理工作區存取權杖。

建立遠端 MCP 端點

端點的範圍只涵蓋一個工作區和區域：

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

Replace:

• <region>與工作區的 Azure 區域相同。
• <workspace-id>與 Azure 入口網站中顯示的工作區識別碼相同。

例如：

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

請求標頭中的 x-api-key 值必須是為與 相同的工作空間 <workspace-id>所建立的存取權杖。 請使用工作區區域的端點，而非離 MCP 用戶端最近的區域。

了解瀏覽器會話生命週期

瀏覽器自動化流程包含三個階段：

1. 撥打 create_browser_session。 結果包含不透明的 browserSessionId，且可能包含即時檢視 URL。
2. 將該 browserSessionId 傳遞給流程中使用的每個瀏覽器工具。
3. 即使流程失敗，也要在清理步驟中呼叫 close_browser_session。

MCP 的 HTTP 傳輸不會保留瀏覽器狀態。 browserSessionId 可在不同的工具呼叫之間識別遠端瀏覽器。 請將其保密，並僅限與建立它的工作區和身分搭配使用。

目前的預覽行為包含以下限制：

• 會議屬於其創作者，不能與其他委託人共享。
• 同一個工作階段的呼叫會依序處理。 不要同時對同一個會議執行行動。
• 閒置的工作階段會在 15 分鐘後清除。 必須明確執行清理作業。
• 已關閉或過期的會話無法重新開啟。
• 連線中斷會導致該工作階段終止。 建立新的工作階段以繼續。
• 結果可能包含 liveViewUrl。 即時視畫面的可用性取決於會話。

從 Microsoft Foundry 代理服務連接

使用 Microsoft Entra 代理程式身分識別，以 Foundry 專案的受控識別來驗證代理程式。 在連接 MCP 工具之前，先授權該身份進入 Playwright 工作區。

建立專案連結

1. 請在 Microsoft Foundry 入口網站開啟您的專案。
2. 打開專案的管理體驗，然後選擇 「連結資源」。
3. 為遠端 MCP 伺服器建立連線。
4. 輸入描述性連接名稱，例如 playwright-mcp-connection。
5. 選擇 Microsoft Entra 代理身份作為認證方法。
6. 輸入 https://mcp.playwright.microsoft.com 作為受眾。
7. 儲存連線。

專案的管理身份必須有一個角色，允許在目標 Playwright 工作區上進行瀏覽器會話操作。 不要把一個專案的身份憑證當作另一個專案的共享秘密。

如果 Microsoft Entra Agent Identity 無法提供給客戶端或環境，請建立一個自訂金鑰連線，並以金鑰命名x-api-key，並以工作區存取權杖作為其值。

新增遠端 MCP 工具

1. 在 Foundry 入口中創建或開啟代理人。

2. 新增遠端 MCP 伺服器或 MCP 工具。

3. 使用下列設定：

   Setting	Value
   伺服器標籤	唯一的標籤，例如 playwrightWorkspace
   伺服器網址	工作區範圍的遠端 MCP 端點
   專案連結	先前建立的 Microsoft Entra 代理身份連線
   Approval	在評估整合時，要求每通電話都獲得批准
   允許的工具	從流程所需的工具開始

4. 儲存代理設定。

5. 在代理指令中，要求代理建立一個會話，重用其 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. 檢查工具名稱及所有參數，特別是網址、選擇器、文字、上傳資料和程式碼。
3. 只批准預期中的行動。
4. 確認最終回覆是否基於頁面結果。
5. 確認名為close_browser_session的流程。

關於目前 Foundry 連線欄位、審核處理、SDK 範例及用戶端限制，請參見 「連接代理至MCP伺服器端點」。

從 Visual Studio Code 連接

Visual Studio Code 可以偵測遠端伺服器的 OAuth 設定，並以 Microsoft Entra ID 登入你。 設定僅需工作區範圍的端點。

1. 在 Visual Studio Code 中，從指令面板執行 MCP：開啟使用者設定。
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. 檢查伺服器的網址和設定，然後確認你信任這台伺服器。
7. 打開聊天室並選擇 「設定工具」。 只啟用完成任務所需的劇作家工具。
8. 執行前面 Foundry 章節的範例提示。
9. 檢閱工具確認，並驗證工作階段已於結束時關閉。

當連線是私人時，使用使用者設定。 僅包含端點的工作區配置可以被共享。 Visual Studio Code 會安全地快取 OAuth 憑證，並在重新連線時可重複使用。

如果客戶端環境無法使用 Microsoft Entra 驗證，請依照 MCP 組態輸入 中的說明，設定含有受保護輸入的 x-api-key 標頭。 切勿將工作區存取權杖值直接放入 mcp.json。

關於設定位置、秘密輸入、伺服器信任與診斷，請參閱 Visual Studio Code 中的新增與管理 MCP 伺服器及 MCP 設定參考。

設計代理自動化流程

使用觀察-行動-驗證迴圈，而非要求代理執行一段長序列而不檢查頁面狀態。

1. 創建： 呼叫 create_browser_session 並保留其 browserSessionId。
2. 導航： 請使用明確且核准的網址來電 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. 呼叫 browser_handle_dialog 時設定 accept 為 true 或 false。
3. 對於提示對話方塊，請僅在接受該對話方塊時包含 promptText。
4. 繼續前請再仔細觀察該頁面。

處理不明確的失敗情況

暫停或通話中斷並不代表某個動作沒有效果。 在重試非冪等元操作（如點擊、表單提交、上傳或程式碼執行）前：

1. 如果工作階段仍可使用，請呼叫 browser_snapshot、browser_find 或其他觀測工具。
2. 判斷預期狀態變化是否發生。
3. 只有在重複動作安全時才重試。
4. 若會話已過期，請建立新會話並從已知應用程式狀態重新啟動。

工具參考

所有瀏覽器導域工具都要求 browserSessionId。 此處顯示的字串與集合界限為目前預覽限制。

會話工具

導航與觀測工具

互動工具

標籤、檔案與程式碼工具

每次自動化工作流程完成後，使用目前作用中的 browserSessionId 呼叫 close_browser_session。

表單欄位形狀

每個 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 到 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 用戶端顯示未經授權

• 確認工作區已啟用存取權杖認證。
• 確認該代幣沒有過期或被撤銷。
• 用原始代幣價值作為價值 x-api-key 。 不要加 Bearer 前綴。
• 確認令牌和端點屬於同一個工作區。
• 如果你複製密碼時不對，請重新建立一個標記，因為你無法從入口網站取得現有的數值。

MCP 用戶端回報 Forbidden

• 確認與令牌相關的使用者仍有建立瀏覽器會話的權限。
• 在同一個瀏覽器會議中，使用同一個專案連線或令牌來呼叫所有通話。
• 不要在使用者、使用不同憑證的代理程式或工作區之間傳送 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 片段中使用存取權杖。
• 使用短命代幣，定期輪換，並撤銷未使用的連線。
• 為每個信任邊界使用專用的工作區與最小權限身分。
• 記錄核准和工具名稱以便稽核，但不要記錄憑證、上傳內容或敏感頁面資料。

區域可用性

劇作家工作區 可在以下 Azure 區域使用：

相關內容

• 管理工作區存取權杖
• 管理Playwright工作區的存取權限
• 將 Microsoft Foundry 代理程式連接到 MCP 伺服器端點
• 在 Visual Studio Code 中新增及管理 MCP 伺服器
• 模型內容通訊協議檔