概述连接到 MCP 服务器连接模式会话清理可用的工具 MCP 工具转发兼容框架监控开始使用

WorkSpaces 应用程序 MCP 服务器

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

概述

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

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

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

连接到 MCP 服务器

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


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

MCP 服务器托管在 AWS 云中，使用可流式 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更多信息，请参阅 m cp-proxy-for- aws 上的。 GitHub

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

Non-domain-joined 舰队 -将直播网址作为标题传递。请参阅与未加入域的舰队连接。
Domain-joined 舰队 -将签名的 SAML 断言作为元数据传递。请参阅与加入域的舰队连接。

注意

在任何给定时间，只有一个代理可以连接到一个独特的会话。通过UserId参数指定的指定用户，每个队列一次只能有一个活跃会话。要同时运行多个代理，每个代理必须连接到自己的唯一会话。

与未加入域的舰队连接

对于未加入域名的队列，使用 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 参考中的CreateStreaming网址。

与加入域的舰队连接

当代理访问加入域的流式传输实例时，必须通过 SAML 提供商联合连接。此要求适用于传统会话和代理会话。对于代理会话，Certificate-Based 身份验证为必填项。

由于加入域的流式传输实例需要通过 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参数是在mcp-proxy-for-aws版本 1.6.1 中添加的。如果不进行额外开发，早期版本无法注入该_meta字段。要升级，请运行pip install -U mcp-proxy-for-aws。

有关使用应用程序设置 SAML 联合的更多信息，请参阅《亚马逊 WorkSpaces WorkSpaces 应用程序管理指南》中的设置 SAML。有关更多信息和完整的工作示例，请参阅上示例中的工作空间代理访问存储库的示例代码。 AWS GitHub

连接模式

通过在 MCP 请求上设置X-Amzn-AgentAccess-Connect-Mode标题，您可以控制代理如何等待桌面会话变为可用。

注意

连接模式适用于未加入域和加入域的队列。将X-Amzn-AgentAccess-Connect-Mode标头设置为您的队列类型使用的任何身份验证机制（未加入域的队列的流媒体网址标头或加入域的队列的 SAML 断言元数据）。

可用模式如下：

阻止（默认）— MCP 服务器等待桌面连接完全建立后再响应。tools/list退货后，所有工具立即可用。
轮询 — MCP 服务器无需等待桌面连接即可立即响应。最初，只有该connection_status工具可用。您的代理会轮询此工具，直到建立连接，此时完整的工具集才可用。

当您希望代理在等待桌面连接的同时执行其他工作时，或者需要对连接超时行为进行更多控制时，请使用轮询模式。

以下示例显示如何使用轮询模式：


# 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 应用程序流式传输会话过期。会话到期会终止底层流媒体实例并触发队列配置的自动缩放策略。有关更多信息，请参阅适用于亚马逊 WorkSpaces 应用程序的 Fleet Auto Scaling。
false（默认）— 直播会话继续运行，直到达到断开连接超时为止。有关断开连接超时的更多信息，请参阅在亚马逊 WorkSpaces 应用程序中创建队列。

注意

默认情况下，当您正确结束客户端生命周期时，mcp-proxy-for-awsMCP 客户端会自动处理DELETE请求。

可用的工具

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

鼠标工具

left_click

在给定的坐标处左键单击。

参数：x（必填）、y（必填）、modifiers（可选，例如ctrl或ctrl+shift）。

double_click

在给定的坐标处双击。