Descripción general de Conexión al servidor MCP Modos de conexión Limpieza de sesión Herramientas disponibles Reenvío de herramientas MCP Marcos compatibles Supervisión Introducción

WorkSpaces Servidor MCP de aplicaciones

El servidor WorkSpaces Applications MCP es un servicio totalmente gestionado que proporciona a los agentes de IA las herramientas del Model Context Protocol (MCP) para interactuar con las aplicaciones de escritorio durante las sesiones de streaming. Los agentes pueden hacer clic en los botones, introducir texto, desplazarse y tomar capturas de pantalla del escritorio.

Descripción general de

Cuando se habilita el acceso de los agentes en una pila, los agentes pueden conectarse al servidor MCP administrado para interactuar con las aplicaciones de escritorio. El servidor MCP gestiona la comunicación entre el agente y la sesión de streaming. Su agente envía las solicitudes de herramientas MCP y el servidor las ejecuta en el escritorio.

El servidor MCP está alojado en la nube. AWS No es necesario instalar ni mantener ningún componente del servidor. El servidor usa HTTP Streamable como protocolo de transporte.

El acceso de los agentes admite tanto las flotas que no están unidas a un dominio como las que están unidas a un dominio. El método de conexión difiere según el tipo de flota. Non-domain-joined las flotas autentican la sesión con una URL de transmisión, mientras que las flotas unidas a un dominio se autentican mediante la federación SAML. Para ver la ruta que coincide con su flota, consulte. Conexión al servidor MCP

Conexión al servidor MCP

Los agentes se conectan al servidor MCP en el siguiente punto final:


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

El servidor MCP está alojado en la AWS nube y utiliza el protocolo Streamable HTTP como protocolo de transporte. No es necesario instalar ni mantener ningún componente del servidor.

Todas las solicitudes deben SigV4-signed utilizar credenciales de IAM con el nombre agentaccess-mcp del servicio. El siguiente ejemplo de Python muestra el patrón de conexión general conmcp-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
    ...

Para otros lenguajes, escribe tu propia lógica de firma de SigV4 para las solicitudes MCP salientes o usa una biblioteca que admita la firma de SigV4. Para obtener más información al respectomcp-proxy-for-aws, consulte mcp-proxy-for-aws en. GitHub

La forma de autenticar la sesión de streaming depende del tipo de flota:

Non-domain-joined flotas: pasa una URL de streaming como encabezado. Consulte Conectarse con flotas que no estén unidas a un dominio.
Domain-joined flotas: pasa una aserción SAML firmada como metadatos. Consulte Conectarse con flotas unidas a un dominio.

nota

En un momento dado, solo un agente puede conectarse a una sesión única. Los usuarios nominales, especificados mediante el UserId parámetro, solo pueden tener una sesión activa por flota a la vez. Para ejecutar varios agentes al mismo tiempo, cada agente debe conectarse a su propia sesión única.

Conectarse con flotas que no estén unidas a un dominio

En el caso de las flotas que no están unidas a un dominio, genera una URL de streaming mediante la CreateStreamingURL API y pásala como encabezado en cada solicitud. X-Amzn-AgentAccess-Streaming-Session-Url No se requieren parámetros específicos del agente. El comportamiento de los agentes viene determinado por la configuración de acceso de los agentes de la pila.


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, _):
    ...

Para obtener más información sobre la CreateStreamingURL API, consulte la CreateStreaming URL en la referencia de la API de Amazon WorkSpaces Applications 2.0.

Conectarse con flotas unidas a un dominio

Cuando los agentes acceden a instancias de streaming unidas a un dominio, la conexión debe federarse a través de un proveedor de SAML. Este requisito se aplica tanto a las sesiones tradicionales como a las de agente. Para las sesiones de agentes, Certificate-Based Autentic es obligatorio.

Como las instancias de streaming unidas a un dominio requieren acceso mediante SAML, su cliente MCP debe proporcionar una aserción SAML firmada en lugar de una URL de streaming. Las aserciones SAML codificadas superan los límites de tamaño de los encabezados HTTP. Para evitarlo, usa el metadata campo en: 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, _):
    ...

nota

El metadata parámetro se añadió en la mcp-proxy-for-aws versión 1.6.1. Las versiones anteriores no podían inyectar el _meta campo sin un desarrollo adicional. Para actualizar, ejecutepip install -U mcp-proxy-for-aws.

Para obtener más información sobre la configuración de la federación de SAML con WorkSpaces aplicaciones, consulte la sección Configuración de SAML en la Guía de administración de WorkSpaces aplicaciones de Amazon. Para obtener más información y un ejemplo práctico completo, consulte el repositorio sample-code-for-workspaces-agent-access en Samples on. AWS GitHub

Modos de conexión

Puede controlar el tiempo en que su agente espera a que la sesión de escritorio esté disponible configurando el X-Amzn-AgentAccess-Connect-Mode encabezado de sus solicitudes de MCP.

nota

Los modos de conexión se aplican tanto a las flotas que no están unidas a un dominio como a las que están unidas a un dominio. Configure el X-Amzn-AgentAccess-Connect-Mode encabezado junto con el mecanismo de autenticación que utilice su tipo de flota (el encabezado Streaming-URL para las flotas que no están unidas a un dominio o los metadatos de aserción de SAML para las flotas unidas a un dominio).

Están disponibles los siguientes modos:

BLOQUEO (predeterminado): el servidor MCP espera hasta que la conexión al escritorio esté completamente establecida antes de responder. Cuando se tools/list devuelve, todas las herramientas están disponibles de inmediato.
SONDEO: el servidor MCP responde inmediatamente sin esperar a que se conecte al escritorio. Inicialmente, solo está disponible la connection_status herramienta. Su agente sondea esta herramienta hasta que se establezca la conexión, momento en el que todo el conjunto de herramientas estará disponible.

Utilice el modo POLLING cuando desee que su agente realice otras tareas mientras espera la conexión al escritorio o cuando necesite controlar mejor el comportamiento del tiempo de espera de la conexión.

El siguiente ejemplo muestra cómo usar el modo 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()

Limpieza de sesión

Puedes controlar si la sesión de streaming ha caducado cuando tu agente termina su conexión configurando el X-Amzn-AgentAccess-Expire-Streaming-Session-On-Delete encabezado de tus solicitudes de MCP. Están disponibles los siguientes valores:

verdadero: cuando el agente envía una DELETE solicitud HTTP explícita, el servidor MCP hace que finalice la sesión de streaming de las WorkSpaces aplicaciones como parte de la limpieza. Al caducar la sesión, se termina la instancia de streaming subyacente y se activa la política de escalado automático configurada por la flota. Para obtener más información, consulte Fleet Auto Scaling para WorkSpaces aplicaciones de Amazon.
false (predeterminado): la sesión de streaming continúa ejecutándose hasta que se agote el tiempo de espera de desconexión. Para obtener más información sobre el tiempo de espera de la desconexión, consulte. Cree una flota en Amazon WorkSpaces Applications

nota

De forma predeterminada, un cliente mcp-proxy-for-aws MCP gestiona automáticamente la DELETE solicitud cuando finaliza correctamente el ciclo de vida del cliente.

Herramientas disponibles

El servidor MCP proporciona las siguientes herramientas para que los agentes interactúen con el escritorio durante una sesión de streaming. Todos los nombres de las herramientas utilizan el agentaccess___ prefijo.

Herramientas de ratón

left_click

Haga clic con el botón izquierdo en las coordenadas indicadas.

Parámetros: x (obligatorio), y (obligatorio), modifiers (opcional, por ejemplo ctrl octrl+shift).

double_click

Haga doble clic en las coordenadas indicadas.