本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

WorkSpaces 应用程序 MCP 服务器

WorkSpaces 应用程序 MCP 服务器是一项完全托管的服务，它为 AI 代理提供模型上下文协议 (MCP) 工具，以便在流式传输会话期间与桌面应用程序交互。代理可以单击按钮、输入文本、滚动和截取桌面的屏幕截图。

概述

在堆栈上启用代理访问时，代理可以连接到托管 MCP 服务器以与桌面应用程序进行交互。MCP 服务器负责处理您的代理和直播会话之间的通信。您的代理发送 MCP 工具请求，服务器在桌面上执行这些请求。

MCP 服务器托管在 AWS 云中。您无需安装或维护任何服务器组件。服务器使用 Streamable HTTP 作为其传输协议。

代理访问支持未加入域的队列和加入域的队列。连接方法因舰队类型而异。 Non-domain-joined 队列使用直播 URL 对会话进行身份验证，而加入域名的队列则通过 SAML 联合进行身份验证。有关与您的舰队匹配的路径，请参阅正在连接到 MCP 服务器。

正在连接到 MCP 服务器

代理通过以下端点连接到 MCP 服务器：

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

MCP 服务器托管在 AWS 云中，并使用 Streamable HTTP 作为其传输协议。您无需安装或维护任何服务器组件。

每个请求都必须 SigV4-signed 使用带有服务名称的 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
    ...

对于其他语言，可以为传出的 MCP 请求编写自己的 Sigv4 签名逻辑，或者使用支持 Sigv4 签名的库。有关的更多信息mcp-proxy-for-aws，请参阅上的 mcp-proxy-for- aws。 GitHub

如何对直播会话进行身份验证取决于您的队列类型：

连接未加入域名的舰队

对于未加入域名的队列，请使用 CreateStreamingURL API 生成直播网址，并将其作为标头传递给每个请求。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 的更多信息，请参阅《亚马逊 WorkSpaces 应用程序 2.0 API 参考》中的 CreateStreamingURL。

与已加入域名的舰队建立联系

当代理访问加入域的流媒体实例时，必须通过 SAML 提供商联合连接。此要求适用于标准会话和代理会话。标准会话允许用户手动输入密码或使用基于证书的身份验证来获得无缝登录体验。对于代理会话，需要基于证书的身份验证。

由于加入域名的流媒体实例需要通过 SAML 进行访问，因此您的 MCP 客户端必须提供签名的 SAML 断言，而不是直播网址。编码的 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, _):
    ...

有关设置与 WorkSpaces 应用程序的 SAML 联合的更多信息，请参阅《亚马逊 WorkSpaces 应用程序管理指南》中的设置 SAML。有关更多信息和完整的工作示例，请参阅 Samples on 中的 workspaces-agent-access 存储库的示例代码。 AWS GitHub

连接模式

您可以通过在 MCP 请求上设置X-Amzn-AgentAccess-Connect-Mode标题来控制代理等待桌面会话变为可用状态的方式。

可用模式如下：

如果您希望代理在等待桌面连接时执行其他工作，或者需要对连接超时行为进行更多控制，请使用 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标头来控制代理结束连接时直播会话是否过期。以下值可用：

可用的工具

MCP 服务器提供以下工具，供代理在流式传输会话期间与桌面进行交互。所有工具名称都使用前agentaccess___缀。

鼠标工具

键盘工具

屏幕工具

MCP 工具转发

MCP 工具转发允许代理通过直接 MCP 调用而不是使用计算机使用工具与应用程序和桌面操作系统进行交互。启用工具转发后，MCP 服务器会将 WorkSpaces 应用程序会话中配置的工具转发给您的代理。

设置工具转发

要设置 MCP 工具转发，请执行以下操作：

用于工具转发的 IAM 权限

用于调用转发工具的 IAM 操作是CallForwardedTool。您可以使用StackArn条件键限制对特定堆栈的访问权限：

{
  "Action": "agentaccess-mcp:*",
  "Resource": "*",
  "Condition": {
    "ArnLike": {
      "ponte-mcp:StackArn": "arn:aws:appstream:region:account-id:stack/stack-name"
    }
  }
}

兼容框架

您可以从任何支持 Streamable HTTP 和 SigV4 签名的 MCP-compatible 代理框架连接到 WorkSpaces 应用程序 MCP 服务器。以下框架已经过测试：

监控

您可以通过以下服务监控代理活动：

开始使用

要开始使用 WorkSpaces 应用程序 MCP 服务器，请参阅开始为代理提供 WorkSpaces 应用程序访问权限。