Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

WorkSpaces Aplicaciones: servidor MCP

El servidor MCP de WorkSpaces Applications es un servicio totalmente gestionado que proporciona a los agentes de IA 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

Al habilitar 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 acceso del agente admite flotas no unidas a un dominio o unidas a un dominio. El método de conexión varía según el tipo de flota. En el caso de las flotas que no están unidas a un dominio, puede conectarse de dos maneras. En la primera, proporciona la pila y el ID de usuario como dos encabezados: y. x-amzn-agentaccess-workspaces-applications-stack x-amzn-agentaccess-workspaces-applications-user-id A continuación, el servidor MCP crea la sesión de streaming por usted. En la segunda, generas tú mismo una URL de streaming y la pasas como encabezado. En el caso de las flotas unidas a un dominio, autentícate mediante la federación SAML. Para ver la ruta que coincida 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

regionSustitúyalo por el código de su región. Para conocer las regiones compatibles y sus puntos de conexión, consulteWorkSpaces Aplicaciones: puntos de conexión MCP.

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

Para conectar a un agente, debes elegir entre dos opciones: cómo el agente autoriza sus solicitudes y cómo identifica la sesión de streaming.

Solicitar autorización

Puedes autorizar las solicitudes de dos maneras: mediante la firma de SigV4 o mediante la autorización mediante OAuth 2.1. AWS Sign-In

Firma SigV4

Para usar SigV4, firme cada solicitud con las credenciales de IAM con el nombre del servicio. agentaccess-mcp El siguiente ejemplo de Python muestra el patrón de conexión general mediantemcp-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, escriba su propia lógica de firma de SigV4 para las solicitudes MCP salientes o utilice 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

autorización de OAuth 2.1

Como alternativa a firmar las solicitudes con credenciales de IAM, el servidor MCP admite la autorización directa de OAuth 2.1 AWS Sign-In, de la misma manera que el servidor MCP. AWS AWS Sign-In actúa como servidor de autorizaciones. Emite tokens de acceso limitado y de corta duración. El servidor MCP acepta estos tokens como símbolos portadores. OAuth usa tus identidades, permisos y controles organizativos de IAM existentes. Cuando autorizas a un agente, este puede acceder al servidor MCP en tu nombre. No obtiene permisos adicionales. AWS sigue comparando todas las solicitudes con sus políticas de IAM.

OAuth-compatible Los clientes MCP, como Kiro, Claude Code, Cursor, Codex y Gemini, pueden conectarse directamente al punto final del servidor MCP sin necesidad de un software proxy local. AWS Sign-In admite dos modelos de autorización:

La autorización OAuth para el servidor MCP funciona de la misma manera que para el servidor MCP, utilizando el punto final del servidor AWS MCP (). https://agentaccess-mcp.region.api.aws/mcp Para obtener información sobre la configuración, los permisos de IAM necesarios y las opciones de control y supervisión, consulte Autenticación con OAuth 2.1 para el servidor MCP de AWS en la Guía del usuario del kit de herramientas de agentes para AWS y Sign-Incon OAuth 2.0 en la Guía del usuario.AWS Sign-In

Identificación de la sesión

La forma de identificar la sesión de streaming depende del tipo de flota.

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, puede conectarse de dos maneras. Proporcione la pila y el ID de usuario como encabezados y el servidor MCP creará la sesión de streaming automáticamente. Esto es adecuado para los clientes MCP que se configuran de forma estática, ya que dichos clientes pueden contener un par fijo de encabezados, pero no pueden generar una URL de transmisión ni reemplazar una cuando caduque. Como alternativa, puedes generar tú mismo una URL de streaming y pasarla como encabezado. Utilice este enfoque cuando necesite controlar la creación de la sesión, por ejemplo, cuando establezca el período de validez.

Para conectarte con la pila y el ID de usuario, pasa los siguientes encabezados en cada solicitud:

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

Si prefieres conectarte con una URL de streaming, genera una mediante la CreateStreamingURL API y pásala como x-amzn-agentaccess-streaming-session-url encabezado en cada solicitud. No se requieren parámetros específicos del agente. El comportamiento de los agentes viene determinado por la configuración de acceso a 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 CreateStreamingURL 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 estar federada a través de un proveedor de SAML. Este requisito se aplica tanto a las sesiones tradicionales como a las de los agentes. Para las sesiones de agentes, Certificate-Based Autentic es obligatorio.

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

Para obtener más información sobre cómo configurar la federación de SAML con WorkSpaces aplicaciones, consulte 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 modo 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.

Están disponibles los siguientes modos:

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

El siguiente ejemplo muestra cómo utilizar 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 sesiones

Puedes controlar si la sesión de streaming caduca cuando tu agente finaliza 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:

Herramientas disponibles

El servidor MCP proporciona las siguientes herramientas. Los agentes las utilizan para interactuar con el escritorio durante una sesión de streaming. Todos los nombres de las herramientas usan el agentaccess___ prefijo.

Herramientas de ratón

Herramientas de teclado

Herramientas de pantalla

Herramientas de aplicaciones

Herramientas de sesión

Reenvío de herramientas MCP

Con el reenvío de herramientas MCP, los agentes pueden trabajar directamente con las aplicaciones y el sistema operativo. Hacen llamadas MCP directas en lugar de utilizar herramientas informáticas. Al activar el reenvío de herramientas, el servidor MCP envía al agente las herramientas configuradas en la sesión de la WorkSpaces aplicación.

Configurar el reenvío de herramientas

Para configurar el reenvío de herramientas MCP:

Consideraciones sobre el reenvío de herramientas MCP

Tenga en cuenta las siguientes consideraciones al configurar el reenvío de herramientas MCP:

Cómo ve el agente las herramientas reenviadas

Para evitar colisiones entre servidores, el servidor MCP cambia el nombre de cada herramienta reenviada de la lista de herramientas del agente siguiendo el siguiente patrón:

forwarded___server-name___original-tool-name

server-nameEs la clave del archivo de configuración. Por ejemplo, una get_forecast herramienta del weather servidor aparece comoforwarded___weather___get_forecast. Cuando el agente llama al nombre reenviado, el servidor MCP enruta la solicitud a la herramienta original del servidor propietario. El código de agente que coincida con los nombres de las herramientas debe incluir este prefijo.

Permisos de IAM para el reenvío de herramientas

La acción de IAM para las herramientas de reenvío de llamadas es. CallForwardedTool Para limitar el acceso a pilas específicas, usa la clave de StackArn condición:

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

Marcos compatibles

Puede conectarse al servidor MCP de WorkSpaces aplicaciones desde cualquier marco de MCP-compatible agente que admita la firma HTTP y SigV4 de Streamable. Se han probado los siguientes marcos:

Supervisión

Puede supervisar la actividad de los agentes mediante los siguientes servicios:

Introducción

Para empezar a utilizar el servidor MCP de WorkSpaces aplicaciones, consulte. Comience a proporcionar a los agentes acceso a las aplicaciones WorkSpaces