Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

WorkSpaces Serveur MCP pour applications

Le serveur WorkSpaces Applications MCP est un service entièrement géré qui fournit aux agents d'intelligence artificielle des outils MCP (Model Context Protocol) pour interagir avec les applications de bureau pendant les sessions de streaming. Les agents peuvent cliquer sur des boutons, saisir du texte, faire défiler l'écran et prendre des captures d'écran du bureau.

Vue d’ensemble

Lorsque vous activez l'accès des agents sur une pile, les agents peuvent se connecter au serveur MCP géré pour interagir avec les applications de bureau. Le serveur MCP gère la communication entre votre agent et la session de streaming. Votre agent envoie des demandes d'outil MCP et le serveur les exécute sur le poste de travail.

L'accès aux agents prend en charge à la fois les flottes non jointes à un domaine et les flottes jointes à un domaine. La méthode de connexion varie selon le type de flotte. Pour les flottes n'appartenant pas à un domaine, vous pouvez vous connecter de deux manières différentes. Dans le premier cas, vous fournissez la pile et l'ID utilisateur sous forme de deux en-têtes : x-amzn-agentaccess-workspaces-applications-stack etx-amzn-agentaccess-workspaces-applications-user-id. Le serveur MCP crée ensuite la session de streaming pour vous. Dans le second cas, vous générez vous-même une URL de streaming et vous la transmettez comme en-tête. Pour les flottes jointes à un domaine, authentifiez-vous via la fédération SAML. Pour le trajet correspondant à votre flotte, voirConnexion au serveur MCP.

Connexion au serveur MCP

Les agents se connectent au serveur MCP au point de terminaison suivant :

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

regionRemplacez-le par votre code de région. Pour les régions prises en charge et leurs points de terminaison, voirWorkSpaces Points de terminaison MCP pour applications.

Le serveur MCP est hébergé dans le AWS cloud et utilise Streamable HTTP comme protocole de transport. Il n'est pas nécessaire d'installer ou de gérer les composants du serveur.

Pour connecter un agent, vous avez deux choix : la manière dont l'agent autorise ses demandes et la manière dont il identifie la session de streaming.

Demande d’autorisation

Vous pouvez autoriser les demandes de deux manières : signature Sigv4 ou autorisation OAuth 2.1 via. AWS Sign-In

Signature SigV4

Pour utiliser SigV4, signez chaque demande à l'aide des informations d'identification IAM avec le nom du service. agentaccess-mcp L'exemple Python suivant montre le modèle de connexion général en utilisant 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
    ...

Pour les autres langages, écrivez votre propre logique de signature Sigv4 pour les requêtes MCP sortantes ou utilisez une bibliothèque qui prend en charge la signature Sigv4. Pour plus d'informations surmcp-proxy-for-aws, consultez mcp-proxy-for-aws sur. GitHub

Autorisation OAuth 2.1

Au lieu de signer des demandes avec des informations d'identification IAM, le serveur MCP prend en charge l'autorisation OAuth 2.1 AWS Sign-In, de la même manière que le serveur MCP. AWS AWS Sign-In fait office de serveur d'autorisation. Il émet des jetons d'accès limités et de courte durée. Le serveur MCP accepte ces jetons en tant que jetons porteurs. OAuth utilise vos identités IAM, vos autorisations et vos contrôles organisationnels existants. Lorsque vous autorisez un agent, celui-ci peut accéder au serveur MCP en votre nom. Il n'obtient pas d'autorisations supplémentaires. AWS vérifie toujours chaque demande par rapport à vos politiques IAM.

OAuth-compatible Les clients MCP, tels que Kiro, Claude Code, Cursor, Codex et Gemini, peuvent se connecter directement au point de terminaison du serveur MCP sans logiciel proxy local. AWS Sign-In prend en charge deux modèles d'autorisation :

L'autorisation OAuth pour le serveur MCP fonctionne de la même manière que pour le serveur MCP, en utilisant le AWS point de terminaison du serveur MCP (). https://agentaccess-mcp.region.api.aws/mcp Pour la configuration, les autorisations IAM requises et les options de gouvernance et de surveillance, consultez la section Authentification OAuth 2.1 pour le serveur AWS MCP dans le guide de l'utilisateur de l'agent Toolkit pour AWS et Sign-Inavec OAuth 2.0 dans le guide de l'utilisateur.AWS Sign-In

Identification de session

La façon dont vous identifiez la session de streaming dépend de votre type de flotte.

Connexion avec des flottes n'appartenant pas à un domaine

Pour les flottes n'appartenant pas à un domaine, vous pouvez vous connecter de deux manières différentes. Entrez la pile et l'ID utilisateur sous forme d'en-têtes, et le serveur MCP crée la session de streaming pour vous. Cela convient aux clients MCP que vous configurez de manière statique, car un tel client peut contenir une paire fixe d'en-têtes mais ne peut pas générer d'URL de streaming ou en remplacer une lorsqu'elle expire. Vous pouvez également générer vous-même une URL de streaming et la transmettre en tant qu'en-tête. Utilisez cette approche lorsque vous avez besoin de contrôler la création de sessions, par exemple en définissant la période de validité.

Pour vous connecter à la pile et à l'ID utilisateur, transmettez les en-têtes suivants à chaque demande :

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

Pour vous connecter à une URL de streaming à la place, générez-en une à l'aide de l'CreateStreamingURLAPI et transmettez-la comme x-amzn-agentaccess-streaming-session-url en-tête de chaque demande. Aucun paramètre spécifique à l'agent n'est requis. Le comportement de l'agent est déterminé par la configuration d'accès aux agents de la pile.

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

Pour plus d'informations sur l'CreateStreamingURLAPI, consultez CreateStreamingl'URL dans le manuel Amazon WorkSpaces Applications 2.0 API Reference.

Connexion avec des flottes jointes à un domaine

Lorsque les agents accèdent à des instances de streaming jointes à un domaine, la connexion doit être fédérée via un fournisseur SAML. Cette exigence s'applique à la fois aux sessions traditionnelles et aux sessions d'agent. Pour les sessions d'agent, Certificate-Based Authentification c'est obligatoire.

Étant donné que les instances de streaming jointes à un domaine nécessitent un accès via SAML, votre client MCP doit fournir une assertion SAML signée au lieu d'une URL de streaming. Les assertions SAML codées dépassent les limites de taille des en-têtes HTTP. Pour éviter cela, utilisez le metadata champ dans 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, _):
    ...

Pour plus d'informations sur la configuration de la fédération SAML avec WorkSpaces les applications, consultez la section Configuration de SAML dans le guide d'administration d'Amazon WorkSpaces Applications. Pour plus d'informations et un exemple de fonctionnement complet, consultez le référentiel sample-code-for-workspaces-agent-access dans Samples on. AWS GitHub

Modes de connexion

Vous pouvez contrôler la façon dont votre agent attend que la session de bureau soit disponible en définissant l'x-amzn-agentaccess-connect-modeen-tête de vos demandes MCP.

Les modes suivants sont disponibles :

Utilisez le mode POLLING lorsque vous souhaitez que votre agent effectue d'autres tâches en attendant la connexion au poste de travail ou lorsque vous avez besoin de mieux contrôler le comportement en cas d'expiration de la connexion.

L'exemple suivant montre comment utiliser le mode 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()

Nettoyage de session

Vous pouvez contrôler si la session de streaming expire lorsque votre agent met fin à sa connexion en définissant l'x-amzn-agentaccess-expire-streaming-session-on-deleteen-tête de vos demandes MCP. Les valeurs disponibles sont les suivantes :

Outils disponibles

Le serveur MCP fournit les outils suivants. Les agents les utilisent pour interagir avec le poste de travail lors d'une session de streaming. Tous les noms d'outils utilisent le agentaccess___ préfixe.

Outils pour souris

Outils de clavier

Outils d'écran

Outils d’application

Outils de session

Transfert d'outils MCP

Grâce au transfert d'outils MCP, les agents peuvent travailler directement avec les applications et le système d'exploitation. Ils passent des appels MCP directs au lieu d'utiliser des outils informatiques. Lorsque vous activez le transfert d'outils, le serveur MCP envoie à votre agent les outils configurés lors de la session WorkSpaces d'application.

Configuration du transfert d'outils

Pour configurer le transfert d'outils MCP :

Considérations relatives au transfert d'outils MCP

Tenez compte des considérations suivantes lorsque vous configurez le transfert d'outils MCP :

Comment les outils transférés apparaissent à l'agent

Pour éviter les collisions entre les serveurs, le serveur MCP renomme chaque outil transféré dans la liste d'outils de l'agent selon le modèle suivant :

forwarded___server-name___original-tool-name

server-nameIl s'agit de la clé de votre fichier de configuration. Par exemple, un get_forecast outil du weather serveur est répertorié sous le nomforwarded___weather___get_forecast. Lorsque l'agent appelle le nom transféré, le serveur MCP achemine la demande vers l'outil d'origine sur le serveur propriétaire. Le code d'agent correspondant aux noms d'outils doit comporter ce préfixe.

Autorisations IAM pour le transfert d'outils

L'action IAM pour appeler les outils transférés estCallForwardedTool. Pour limiter l'accès à des piles spécifiques, utilisez la clé de StackArn condition :

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

Frameworks compatibles

Vous pouvez vous connecter au serveur WorkSpaces Applications MCP à partir de n'importe quel framework d' MCP-compatible agents prenant en charge la signature HTTP et SigV4 streamable. Les frameworks suivants ont été testés :

Contrôle

Vous pouvez surveiller l'activité des agents par le biais des services suivants :

Prise en main

Pour commencer à utiliser le serveur WorkSpaces Applications MCP, consultezCommencez à fournir aux agents un accès aux WorkSpaces applications.