Panoramica di Connessione al server MCP Modalità di connessione Pulizia della sessione Strumenti disponibili Inoltro degli strumenti MCP Framework compatibili Monitoraggio Nozioni di base

WorkSpaces Applicazioni: server MCP

Il server WorkSpaces Applications MCP è un servizio completamente gestito che fornisce agli agenti di intelligenza artificiale strumenti Model Context Protocol (MCP) 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 degli strumenti MCP e il server le esegue sul desktop.

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

L'accesso degli agenti supporta sia flotte non aggiunte a un dominio che unite a un dominio. Il metodo di connessione varia in base al tipo di parco veicoli. Non-domain-joined le flotte autenticano la sessione con un URL di streaming, mentre le flotte aggiunte a un dominio si autenticano 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 al seguente endpoint:


https://agentaccess-mcp.region.api.aws/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.

Ogni richiesta deve SigV4-signed utilizzare le credenziali IAM con il nome agentaccess-mcp del servizio. Il seguente esempio in 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, scrivi la tua logica di firma SIGv4 per le richieste MCP in uscita o usa una libreria che supporti la firma SIGv4. Per ulteriori informazioni, consulta mcp-proxy-for-aws on. mcp-proxy-for-aws https://github.com/aws/mcp-proxy-for-aws GitHub

Il modo in cui autentichi la sessione di streaming dipende dal tipo di parco veicoli:

Non-domain-joined flotte: inserisci un URL di streaming come intestazione. Per informazioni, consulta Connessione con flotte non appartenenti a un dominio.
Domain-joined flotte: passa un'asserzione SAML firmata come metadata. Per informazioni, consulta Connessione con flotte appartenenti a un dominio.

Nota

In qualsiasi momento, solo un agente può connettersi a una sessione unica. Gli utenti nominativi, specificati tramite il UserId parametro, possono avere una sola sessione attiva per flotta alla volta. Per eseguire più agenti contemporaneamente, ogni agente deve connettersi alla propria sessione univoca.

Connessione con flotte non appartenenti a un dominio

Per le flotte non appartenenti a un dominio, genera un URL di streaming utilizzando l'CreateStreamingURLAPI e passalo come intestazione a ogni richiesta. X-Amzn-AgentAccess-Streaming-Session-Url Non sono richiesti parametri specifici dell'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 CreateStreaming l'URL nell'API Reference di Amazon WorkSpaces Applications 2.0.

Connessione con flotte appartenenti a un dominio

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

Poiché le istanze di streaming aggiunte a un 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ò, utilizza 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, _):
    ...

Nota

Il metadata parametro è stato aggiunto nella mcp-proxy-for-aws versione 1.6.1. Le versioni precedenti non possono inserire il _meta campo senza uno sviluppo aggiuntivo. Per eseguire l'aggiornamento, eseguipip install -U mcp-proxy-for-aws.

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

Modalità di connessione

Puoi controllare il modo in cui il tuo agente attende che la sessione desktop diventi disponibile impostando l'X-Amzn-AgentAccess-Connect-Modeintestazione delle tue richieste MCP.

Nota

Le modalità di connessione si applicano sia alle flotte non appartenenti a un dominio che a quelle aggiunte a un dominio. Imposta l'X-Amzn-AgentAccess-Connect-Modeintestazione insieme al meccanismo di autenticazione utilizzato dal tuo tipo di flotta (l'intestazione Streaming-URL per le flotte non appartenenti a un dominio o i metadati dell'asserzione SAML per le flotte aggiunte a un dominio).

Sono disponibili le seguenti modalità:

BLOCCO (impostazione predefinita): il server MCP attende che la connessione desktop sia completamente stabilita prima di rispondere. Al tools/list ritorno, tutti gli strumenti sono immediatamente disponibili.
POLLING: il server MCP risponde immediatamente senza attendere la connessione al desktop. Inizialmente, è disponibile solo lo connection_status strumento. L'agente esegue il polling di questo strumento fino a quando non viene stabilita la connessione, dopodiché diventa disponibile il set completo di strumenti.

Utilizzate la modalità POLLING quando desiderate che il vostro agente esegua altre operazioni in attesa della connessione al desktop o quando avete 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 richieste MCP. Sono disponibili i seguenti valori:

true: quando l'agente invia una DELETE richiesta HTTP esplicita, il server MCP fa scadere la sessione di streaming delle WorkSpaces Applicazioni come parte della pulizia. La scadenza della sessione interrompe l'istanza di streaming sottostante e attiva la politica di scalabilità automatica configurata della flotta. Per ulteriori informazioni, consulta Auto Scaling della flotta per applicazioni Amazon WorkSpaces.
false (impostazione predefinita): la sessione di streaming continua a funzionare fino al raggiungimento del timeout di disconnessione. Per ulteriori informazioni sul timeout di disconnessione, vedere. Crea una flotta in Amazon WorkSpaces Applications

Nota

Per impostazione predefinita, un client mcp-proxy-for-aws MCP gestisce automaticamente la DELETE richiesta quando si termina correttamente il ciclo di vita del client.

Strumenti disponibili

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

Strumenti del mouse

left_click

Fai clic con il pulsante sinistro del mouse sulle coordinate indicate.

Parametri: x (obbligatorio), y (obbligatorio), modifiers (opzionale, ad esempio ctrl octrl+shift).

double_click

Fai un doppio clic sulle coordinate indicate.