Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

WorkSpaces Applicazioni (server MCP)

Il server WorkSpaces Applications MCP è un servizio completamente gestito che fornisce agli agenti AI strumenti MCP (Model Context Protocol) per interagire con le applicazioni desktop durante le sessioni di streaming. Gli agenti possono fare clic sui pulsanti, inserire testo, scorrere e acquisire schermate del desktop.

Panoramica di

Quando si abilita l'accesso degli agenti su uno stack, gli agenti possono connettersi al server MCP gestito per interagire con le applicazioni desktop. Il server MCP gestisce la comunicazione tra l'agente e la sessione di streaming. L'agente invia le richieste di strumenti MCP e il server le esegue sul desktop.

L'accesso all'agente supporta sia flotte non aggiunte a un dominio che aggiunte al dominio. Il metodo di connessione varia in base al tipo di parco veicoli. Per le flotte non aggiunte a un dominio, puoi connetterti in due modi. Nel primo, fornisci lo stack e l'ID utente come due intestazioni: e. x-amzn-agentaccess-workspaces-applications-stack x-amzn-agentaccess-workspaces-applications-user-id Il server MCP crea quindi la sessione di streaming per te. Nel secondo, generi tu stesso un URL di streaming e lo passi come intestazione. Per le flotte aggiunte a un dominio, esegui l'autenticazione tramite la federazione SAML. Per il percorso che corrisponde alla tua flotta, consulta. Connessione al server MCP

Connessione al server MCP

Gli agenti si connettono al server MCP sul seguente dispositivo:

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

Sostituisci region con il tuo codice regionale. Per le regioni supportate e i relativi endpoint, consultaWorkSpaces Applicazioni: endpoint MCP.

Il server MCP è ospitato nel AWS cloud e utilizza Streamable HTTP come protocollo di trasporto. Non è necessario installare o mantenere alcun componente del server.

Per connettere un agente, devi fare due scelte: come l'agente autorizza le sue richieste e come identifica la sessione di streaming.

Autorizzazione di una richiesta

Puoi autorizzare le richieste in due modi: firmando SigV4 o autorizzando tramite OAuth 2.1. AWS Sign-In

Firma SigV4

Per utilizzare SigV4, firma ogni richiesta utilizzando le credenziali IAM con il nome del servizio. agentaccess-mcp Il seguente esempio di Python mostra lo schema di connessione generale utilizzando: 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
    ...

Per altri linguaggi, scrivete la vostra logica di firma SigV4 per le richieste MCP in uscita o utilizzate una libreria che supporti la firma SigV4. Per ulteriori informazioni su, consulta mcp-proxy-for-aws on. mcp-proxy-for-aws GitHub

Autorizzazione OAuth 2.1

In alternativa alla firma delle richieste con credenziali IAM, il server MCP supporta l'autorizzazione OAuth 2.1 tramite AWS Sign-In, allo stesso modo del server MCP. AWS AWS Sign-In funge da server di autorizzazione. Emette token di accesso di breve durata e con ambito. Il server MCP accetta questi token come token portatori. OAuth utilizza le identità, le autorizzazioni e i controlli organizzativi IAM esistenti. Quando autorizzi un agente, questo può accedere al server MCP per tuo conto. Non ottiene autorizzazioni aggiuntive. AWS verifica comunque ogni richiesta rispetto alle tue politiche IAM.

OAuth-compatible I client MCP, come Kiro, Claude Code, Cursor, Codex e Gemini, possono connettersi direttamente all'endpoint del server MCP senza software proxy locale. AWS Sign-In supporta due modelli di autorizzazione:

L'autorizzazione OAuth per il server MCP funziona allo stesso modo in cui funziona per il server MCP, utilizzando l'endpoint del server AWS MCP (). https://agentaccess-mcp.region.api.aws/mcp Per la configurazione, le autorizzazioni IAM richieste e le opzioni di governance e monitoraggio, consulta l'autenticazione OAuth 2.1 per AWS MCP Server nella Agent Toolkit for AWS User Guide e Sign-Incon OAuth 2.0 nella Guida per l'utente.AWS Sign-In

Identificazione della sessione

Il modo in cui identifichi la sessione di streaming dipende dal tipo di flotta.

Connessione con flotte non aggiunte a un dominio

Per le flotte non aggiunte a un dominio, puoi connetterti in due modi. Fornisci lo stack e l'ID utente come intestazioni e il server MCP creerà la sessione di streaming per te. Ciò è adatto ai client MCP configurati staticamente, poiché un client di questo tipo può contenere un paio di intestazioni fisse ma non può generare un URL di streaming o sostituirne uno alla scadenza. In alternativa, potete generare voi stessi un URL di streaming e passarlo come header. Utilizzate questo approccio quando avete bisogno di controllare la creazione della sessione, ad esempio impostando il periodo di validità.

Per connetterti allo stack e all'ID utente, inserisci le seguenti intestazioni per ogni richiesta:

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

Per connetterti invece con un URL di streaming, generane uno utilizzando l'CreateStreamingURLAPI e passalo come x-amzn-agentaccess-streaming-session-url intestazione a ogni richiesta. Non sono richiesti parametri specifici per l'agente. Il comportamento dell'agente è determinato dalla configurazione di accesso dell'agente dello stack.

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

Per ulteriori informazioni sull'CreateStreamingURLAPI, consulta CreateStreamingl'URL nell'Amazon WorkSpaces Applications 2.0 API Reference.

Connessione con flotte aggiunte a un dominio

Quando gli agenti accedono a istanze di streaming aggiunte al dominio, la connessione deve essere federata tramite un provider SAML. Questo requisito si applica sia alle sessioni tradizionali che a quelle con agenti. Per le sessioni con gli agenti, Certificate-Based Autenticazione è obbligatorio.

Poiché le istanze di streaming aggiunte al dominio richiedono l'accesso tramite SAML, il client MCP deve fornire un'asserzione SAML firmata anziché un URL di streaming. Le asserzioni SAML codificate superano i limiti di dimensione dell'intestazione HTTP. Per evitare ciò, usa il campo in: 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, _):
    ...

Per ulteriori informazioni sulla configurazione della federazione SAML con WorkSpaces Applications, consulta Configurazione SAML nella Amazon WorkSpaces Applications Administration Guide. Per ulteriori informazioni e un esempio di funzionamento completo, consulta il repository sample-code-for-workspaces-agent-access in Samples on. AWS GitHub

Modalità di connessione

Puoi controllare il modo in cui l'agente attende che la sessione desktop diventi disponibile impostando l'x-amzn-agentaccess-connect-modeintestazione sulle tue richieste MCP.

Sono disponibili le seguenti modalità:

Usa la modalità POLLING quando desideri che il tuo agente esegua altre operazioni in attesa della connessione al desktop o quando hai bisogno di un maggiore controllo sul comportamento di timeout della connessione.

L'esempio seguente mostra come utilizzare la modalità 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()

Pulizia della sessione

Puoi controllare se la sessione di streaming è scaduta quando l'agente termina la connessione impostando l'x-amzn-agentaccess-expire-streaming-session-on-deleteintestazione sulle tue richieste MCP. Sono disponibili i seguenti valori:

Strumenti disponibili

Il server MCP fornisce i seguenti strumenti. Gli agenti li utilizzano per interagire con il desktop durante una sessione di streaming. Tutti i nomi degli strumenti utilizzano il agentaccess___ prefisso.

Strumenti del mouse

Strumenti da tastiera

Strumenti dello schermo

strumenti applicativi

Strumenti di sessione

Inoltro di strumenti MCP

Con l'inoltro degli strumenti MCP, gli agenti possono lavorare direttamente con le applicazioni e il sistema operativo. Effettuano chiamate MCP dirette invece di utilizzare strumenti informatici. Quando attivate l'inoltro degli strumenti, il server MCP invia all'agente gli strumenti configurati nella sessione dell'applicazione. WorkSpaces

Configurazione dell'inoltro degli strumenti

Per configurare l'inoltro degli strumenti MCP:

Considerazioni sull'inoltro degli strumenti MCP

Tieni presenti le seguenti considerazioni quando configuri l'inoltro degli strumenti MCP:

Come appaiono gli strumenti inoltrati all'agente

Per evitare collisioni tra i server, il server MCP rinomina ogni strumento inoltrato nell'elenco degli strumenti dell'agente utilizzando lo schema seguente:

forwarded___server-name___original-tool-name

server-nameQuesta è la chiave del file di configurazione. Ad esempio, uno get_forecast strumento del weather server è elencato comeforwarded___weather___get_forecast. Quando l'agente chiama il nome inoltrato, il server MCP indirizza la richiesta allo strumento originale sul server proprietario. Il codice dell'agente che corrisponde ai nomi degli strumenti deve prevedere questo prefisso.

Autorizzazioni IAM per l'inoltro degli strumenti

L'azione IAM per richiamare gli strumenti inoltrati è. CallForwardedTool Per limitare l'accesso a stack specifici, usa la StackArn chiave condition:

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

Framework compatibili

È possibile connettersi al server MCP delle WorkSpaces applicazioni da qualsiasi framework di MCP-compatible agenti che supporti la firma Streamable HTTP e SigV4. Sono stati testati i seguenti framework:

Monitoraggio

È possibile monitorare l'attività degli agenti tramite i seguenti servizi:

Nozioni di base

Per iniziare a usare il server MCP delle WorkSpaces applicazioni, consulta. Inizia a fornire agli agenti l'accesso alle applicazioni WorkSpaces