概觀連線至 MCP 伺服器連線模式工作階段清除可用的工具 MCP 工具轉送相容架構監控開始使用

WorkSpaces 應用程式 MCP 伺服器

WorkSpaces 應用程式 MCP 伺服器是一項全受管服務，為 AI 代理器提供模型內容協定 (MCP) 工具，以在串流工作階段期間與桌面應用程式互動。客服人員可以按一下按鈕、輸入文字、捲動和擷取桌面的螢幕擷取畫面。

概觀

當您在堆疊上啟用代理程式存取時，代理程式可以連線至受管 MCP 伺服器，以與桌面應用程式互動。MCP 伺服器會處理您的代理程式與串流工作階段之間的通訊。您的代理程式會傳送 MCP 工具請求，而伺服器會在桌面上執行這些請求。

代理程式存取支援non-domain-joined和加入網域的機群。連線方法因機群類型而異。對於non-domain-joined的機群，您可以透過兩種方式進行連線。首先，您將堆疊和使用者 ID 提供為兩個標頭： x-amzn-agentaccess-workspaces-applications-stack和 x-amzn-agentaccess-workspaces-applications-user-id。然後，MCP 伺服器會為您建立串流工作階段。在第二個部分中，您會自行產生串流 URL，並將其做為標頭傳遞。對於加入網域的機群，請透過 SAML 聯合進行身分驗證。如需符合機群的路徑，請參閱連線至 MCP 伺服器。

連線至 MCP 伺服器

代理程式會在下列端點連線至 MCP 伺服器：


https://agentaccess-mcp.region.api.aws/mcp

將 region 替換為您的區域代碼。如需支援的區域及其端點，請參閱 WorkSpaces 應用程式 MCP 端點。

MCP 伺服器託管於 AWS 雲端，並使用可串流 HTTP 做為其傳輸通訊協定。您不需要安裝或維護任何伺服器元件。

注意

在代理程式可以連線之前，與堆疊相關聯的機群必須正在執行，且具有可用的容量。

若要連接代理程式，您有兩個選擇：代理程式如何授權其請求，以及它如何識別串流工作階段。

要求授權

您可以透過兩種方式之一授權請求：SigV4 簽署或透過 AWS Sign-In 進行 OAuth 2.1 授權。

SigV4 簽署

若要使用 SigV4，請使用服務名稱為的 IAM 憑證簽署每個請求agentaccess-mcp。下列 Python 範例顯示使用的一般連線模式mcp-proxy-for-aws：


from mcp_proxy_for_aws import aws_iam_streamablehttp_client

async with aws_iam_streamablehttp_client(
    endpoint="https://agentaccess-mcp.region.api.aws/mcp",
    aws_service="agentaccess-mcp",
    aws_region="region",
    headers={
        # Fleet-type-specific headers (see the following subsections)
    },
    metadata={
        # Fleet-type-specific metadata (see the following subsections)
    },
) as (read, write, _):
    # Use read/write streams with your MCP client
    ...

對於其他語言，請撰寫您自己的 SigV4 簽署邏輯以進行傳出 MCP 請求，或使用支援 SigV4 簽署的程式庫。如需的詳細資訊mcp-proxy-for-aws，請參閱 GitHub 上的 mcp-proxy-for-aws。

OAuth 2.1 授權

作為使用 IAM 登入資料簽署請求的替代方案，MCP 伺服器支援透過 AWS Sign-In 的 OAuth 2.1 授權，方法與 AWS MCP Server. AWS Sign-In 充當授權伺服器。它發出短期、範圍的存取權杖。MCP 伺服器接受這些權杖做為承載權杖。OAuth 會使用您現有的 IAM 身分、許可和組織控制。當您授權代理程式時，代理程式可以代表您存取 MCP 伺服器。它不會獲得額外的許可。 AWS 仍會針對您的 IAM 政策檢查每個請求。

OAuth 相容 MCP 用戶端 – 例如 Kiro、Claude Code、Cursor、Codex 和 Gemini – 可以直接連接到 MCP 伺服器端點，無需本機代理軟體。 AWS 登入支援兩種授權模式：

互動式授權 — 適用於可以開啟瀏覽器的客服人員。用戶端會透過動態用戶端註冊進行註冊、將您重新導向至 AWS 登入頁面以驗證和核准存取權，然後 AWS 登入會發出和重新整理存取權杖。
非互動式授權 — 適用於已有 AWS 登入資料且在沒有瀏覽器的情況下執行的客服人員（有時稱為無周邊授權）。代理程式使用 OAuth 用戶端登入資料授權來交換 SigV4-signed登入資料做為短期存取字符。

MCP 伺服器的 OAuth 授權的運作方式與使用 MCP 伺服器端點 () 的 AWS MCP 伺服器相同https://agentaccess-mcp.region.api.aws/mcp。如需設定、必要的 IAM 許可，以及控管和監控選項，請參閱《AWS 代理工具組使用者指南》中的 AWS MCP 伺服器的 OAuth 2.OAuth 1 身分驗證，以及《登入使用者指南》中的使用 OAuth 2.0 登入。 AWS

工作階段識別

如何識別串流工作階段取決於您的機群類型。

注意

在任何指定時間，只有一個代理程式可以連線到唯一的工作階段。透過 UserId 參數指定的具名使用者一次只能有一個作用中工作階段。若要同時執行多個代理程式，每個代理程式必須連接到自己的唯一工作階段。

與non-domain-joined的機群連線

對於non-domain-joined的機群，您可以透過兩種方式進行連線。提供堆疊和使用者 ID 做為標頭，MCP 伺服器會為您建立串流工作階段。這適合您靜態設定的 MCP 用戶端，因為這類用戶端可以保留固定的標頭對，但無法產生串流 URL 或在過期時取代。或者，自行產生串流 URL，並將其做為標頭傳遞。當您需要控制工作階段建立，例如設定有效期間時，請使用此方法。

若要與堆疊和使用者 ID 連線，請在每個請求上傳遞下列標頭：

x-amzn-agentaccess-workspaces-applications-stack — 堆疊名稱或 ARN。
x-amzn-agentaccess-workspaces-applications-user-id — 工作階段的使用者 ID。

注意

x-amzn-agentaccess-workspaces-applications-user-id 標頭是選用的。如果您省略它，MCP 伺服器會從已驗證的工作階段衍生使用者身分。當存在時， AWS SourceIdentity它會使用，否則呼叫者的 IAM 主體。當使用者擔任 IAM 角色時，會SourceIdentity保留使用者的原始公司身分。即使角色透過外部身分提供者 (IdP) 鏈結，這仍會保留。


from mcp_proxy_for_aws import aws_iam_streamablehttp_client

# Connect to the MCP server with the stack and user ID
async with aws_iam_streamablehttp_client(
    endpoint="https://agentaccess-mcp.region.api.aws/mcp",
    aws_service="agentaccess-mcp",
    aws_region="region",
    headers={
        "x-amzn-agentaccess-workspaces-applications-stack": "stack-name-or-arn",
        "x-amzn-agentaccess-workspaces-applications-user-id": "user-id",
    },
) as (read, write, _):
    ...

若要改為與串流 URL 連線，請使用 CreateStreamingURL API 產生一個 URL，並將其做為每個請求上的x-amzn-agentaccess-streaming-session-url標頭傳遞。不需要代理程式特定的參數。代理程式行為取決於堆疊的代理程式存取組態。


import boto3
from mcp_proxy_for_aws import aws_iam_streamablehttp_client

# Generate streaming URL
appstream = boto3.client("appstream", region_name="region")
response = appstream.create_streaming_url(
    StackName="stack-name",
    FleetName="fleet-name",
    UserId="user-id",
)
streaming_url = response["StreamingURL"]

# Connect to MCP server
async with aws_iam_streamablehttp_client(
    endpoint="https://agentaccess-mcp.region.api.aws/mcp",
    aws_service="agentaccess-mcp",
    aws_region="region",
    headers={
        "x-amzn-agentaccess-streaming-session-url": streaming_url,
    },
) as (read, write, _):
    ...

如需 CreateStreamingURL API 的詳細資訊，請參閱《Amazon WorkSpaces 應用程式 2.0 API 參考》中的 CreateStreamingURL。

與加入網域的機群連線

當客服人員存取加入網域的串流執行個體時，必須透過 SAML 供應商聯合連線。此要求同時適用於傳統和代理程式工作階段。對於客服人員工作階段，憑證型身分驗證為必要項目。

由於加入網域的串流執行個體需要透過 SAML 存取，因此您的 MCP 用戶端必須提供已簽署的 SAML 聲明，而不是串流 URL。編碼的 SAML 聲明超過 HTTP 標頭大小限制。若要避免這種情況，請使用中的 metadata 欄位mcp-proxy-for-aws：


from mcp_proxy_for_aws import aws_iam_streamablehttp_client

# saml_response: your signed, base64-encoded SAML assertion
# stack_arn: the ARN of the AppStream stack for the AD user

async with aws_iam_streamablehttp_client(
    endpoint="https://agentaccess-mcp.region.api.aws/mcp",
    aws_service="agentaccess-mcp",
    aws_region="region",
    metadata={
        "saml_response": saml_response,
        "stack_arn": stack_arn,
    },
) as (read, write, _):
    ...

注意

metadata 參數已新增至 1.6.1 mcp-proxy-for-aws版。如果沒有其他開發，舊版無法注入 _meta 欄位。若要升級，請執行 pip install -U mcp-proxy-for-aws。

如需使用 WorkSpaces 應用程式設定 SAML 聯合的詳細資訊，請參閱《Amazon WorkSpaces 應用程式管理指南》中的設定 SAML。如需詳細資訊和完整的工作範例，請參閱 GitHub 上範例中的 sample-code-for-workspaces-agent-access 儲存庫。 AWS

連線模式

您可以在 MCP 請求上設定 x-amzn-agentaccess-connect-mode標頭，以控制代理程式等待桌面工作階段變成可用的方式。

注意

連線模式適用於non-domain-joined和加入網域的機群。將 x-amzn-agentaccess-connect-mode 標頭與機群類型使用的任何身分驗證機制一起設定。對於non-domain-joined的機群，即堆疊和使用者 ID 標頭或串流 URL 標頭。對於加入網域的機群，它是 SAML 聲明中繼資料。

下列模式可供使用：

BLOCKING （預設） — MCP 伺服器會等到桌面連線完全建立後再回應。tools/list 傳回時，所有工具都會立即可用。
輪詢 — MCP 伺服器會立即回應，無需等待桌面連線。一開始，只有 connection_status工具可用。您的代理程式會輪詢此工具，直到建立連線為止，此時即可使用完整工具集。

當您希望代理程式在等待桌面連線時執行其他工作，或需要更多控制連線逾時行為時，請使用 POLLING 模式。

下列範例示範如何使用 POLLING 模式：


# Pass the header when creating the MCP connection
headers = {
    "x-amzn-agentaccess-streaming-session-url": streaming_url,  # non-domain-joined fleets
    "x-amzn-agentaccess-connect-mode": "POLLING",
}

# After initialize, tools/list returns immediately with connection_status
tools = await session.list_tools()
# tools = [connection_status]

# Poll connection_status until the desktop is ready
while True:
    result = await session.call_tool("connection_status", {})
    status = json.loads(result.content[0].text)
    if status["state"] == "CONNECTED":
        break
    time.sleep(2)

# Now tools/list returns the full set (screenshot, left_click, type_text, etc.)
tools = await session.list_tools()

工作階段清除

當您的代理程式在 MCP 請求上設定 x-amzn-agentaccess-expire-streaming-session-on-delete標頭，即可控制串流工作階段是否過期。下列值可供使用：

true — 當您的代理程式傳送明確的 HTTP DELETE請求時，MCP 伺服器會在清除期間過期 WorkSpaces 應用程式串流工作階段。工作階段過期會終止基礎串流執行個體，並觸發機群設定的自動調整規模政策。如需詳細資訊，請參閱Amazon WorkSpaces 應用程式的機群 Auto Scaling。
false （預設） — 串流工作階段會繼續執行，直到達到中斷連線逾時為止。如需中斷連線逾時的詳細資訊，請參閱在 Amazon WorkSpaces 應用程式中建立機群。

注意

根據預設，當您正確結束用戶端生命週期時，mcp-proxy-for-awsMCP 用戶端會自動處理DELETE請求。

可用的工具

MCP 伺服器提供下列工具。代理程式會在串流工作階段期間使用它們與桌面互動。所有工具名稱都使用 agentaccess___字首。

滑鼠工具

left_click

在指定的座標執行左鍵按一下。

參數： x（必要）、 y （必要）、 modifiers（選用，例如 ctrl或 ctrl+shift)。

double_click

在指定的座標上執行按兩下。