Visão geral do Conectando-se ao servidor MCP Modos de conexão Limpeza da sessão Ferramentas disponíveis Encaminhamento de ferramentas MCP Estruturas compatíveis Monitoramento Conceitos básicos

WorkSpaces Servidor MCP de aplicativos

O servidor WorkSpaces Applications MCP é um serviço totalmente gerenciado que fornece aos agentes de IA ferramentas do Model Context Protocol (MCP) para interagir com aplicativos de desktop durante as sessões de streaming. Os agentes podem clicar em botões, inserir texto, rolar e fazer capturas de tela da área de trabalho.

Visão geral do

Quando você ativa o acesso do agente em uma pilha, os agentes podem se conectar ao servidor MCP gerenciado para interagir com os aplicativos de desktop. O servidor MCP gerencia a comunicação entre seu agente e a sessão de streaming. Seu agente envia solicitações de ferramentas MCP e o servidor as executa no desktop.

O acesso do agente oferece suporte a frotas não associadas a um domínio e a frotas associadas a um domínio. O método de conexão difere de acordo com o tipo de frota. Para frotas não associadas a um domínio, você pode se conectar de duas maneiras. No primeiro, você fornece a pilha e o ID do usuário como dois cabeçalhos: e. x-amzn-agentaccess-workspaces-applications-stack x-amzn-agentaccess-workspaces-applications-user-id Em seguida, o servidor MCP cria a sessão de streaming para você. No segundo, você mesmo gera um URL de streaming e o passa como cabeçalho. Para frotas unidas ao domínio, autentique-se por meio da federação SAML. Para o caminho que corresponde à sua frota, consulteConectando-se ao servidor MCP.

Conectando-se ao servidor MCP

Os agentes se conectam ao servidor MCP no seguinte endpoint:


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

regionSubstitua pelo código da sua região. Para as regiões suportadas e seus endpoints, consulteWorkSpaces Endpoints MCP de aplicativos.

O servidor MCP está hospedado na AWS nuvem e usa HTTP Streamable como protocolo de transporte. Você não precisa instalar nem manter nenhum componente do servidor.

nota

Antes que um agente possa se conectar, a frota associada à sua pilha deve estar funcionando e ter capacidade disponível.

Para conectar um agente, você faz duas escolhas: como o agente autoriza suas solicitações e como ele identifica a sessão de streaming.

Solicitar autorização

Você pode autorizar solicitações de duas maneiras: assinatura SigV4 ou autorização OAuth 2.1 por meio de. AWS Sign-In

Assinatura SigV4

Para usar o SigV4, assine cada solicitação usando as credenciais do IAM com o nome do serviço. agentaccess-mcp O exemplo de Python a seguir mostra o padrão geral de conexão usando: 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
    ...

Para outras linguagens, escreva sua própria lógica de assinatura SigV4 para solicitações MCP enviadas ou use uma biblioteca que suporte a assinatura SigV4. Para obter mais informações sobremcp-proxy-for-aws, consulte mcp-proxy-for-aws on. GitHub

Autorização do OAuth 2.1

Como alternativa à assinatura de solicitações com credenciais do IAM, o servidor MCP oferece suporte à autorização do OAuth 2.1 AWS Sign-In, da mesma forma que o servidor MCP. AWS AWS Sign-In atua como servidor de autorização. Ele emite tokens de acesso com escopo limitado e de curta duração. O servidor MCP aceita esses tokens como tokens portadores. O OAuth usa suas identidades, permissões e controles organizacionais existentes do IAM. Quando você autoriza um agente, ele pode acessar o servidor MCP em seu nome. Ele não recebe permissões extras. AWS ainda verifica todas as solicitações em relação às suas políticas do IAM.

OAuth-compatible Clientes MCP — como Kiro, Claude Code, Cursor, Codex e Gemini — podem se conectar diretamente ao endpoint do servidor MCP sem o software proxy local. AWS Sign-In suporta dois modelos de autorização:

Autorização interativa — Para agentes que podem abrir um navegador. O cliente se registra por meio do registro dinâmico do cliente, redireciona você para uma AWS Sign-In página para autenticar e aprovar o acesso e, em AWS Sign-In seguida, emite e atualiza os tokens de acesso.
Non-interactive autorização — Para agentes que já têm AWS credenciais e funcionam sem um navegador (às vezes chamada de autorização headless). O agente usa a concessão de credenciais do cliente OAuth para trocar SigV4-signed credenciais por um token de acesso de curta duração.

A autorização OAuth para o servidor MCP funciona da mesma forma que para o servidor AWS MCP, usando o endpoint do servidor MCP (). https://agentaccess-mcp.region.api.aws/mcp Para configuração, permissões necessárias do IAM e opções de governança e monitoramento, consulte Autenticação do OAuth 2.1 para o AWS MCP Server no Guia do usuário do Agent Toolkit for AWS Sign-Ine com o OAuth 2.0 no Guia do usuário.AWS Sign-In

Identificação da sessão

A forma como você identifica a sessão de streaming depende do tipo de sua frota.

nota

A qualquer momento, somente um agente pode se conectar a uma sessão exclusiva. Usuários nomeados, especificados por meio do UserId parâmetro, podem ter somente uma sessão ativa por frota por vez. Para executar vários agentes simultaneamente, cada agente deve se conectar à sua própria sessão exclusiva.

Conexão com frotas não associadas a um domínio

Para frotas não associadas a um domínio, você pode se conectar de duas maneiras. Forneça a pilha e o ID do usuário como cabeçalhos, e o servidor MCP cria a sessão de streaming para você. Isso é adequado para clientes MCP que você configura estaticamente, porque esse cliente pode conter um par fixo de cabeçalhos, mas não pode gerar um URL de streaming ou substituí-lo quando ele expirar. Como alternativa, gere você mesmo um URL de streaming e passe-o como cabeçalho. Use essa abordagem quando precisar controlar a criação da sessão, como definir o período de validade.

Para se conectar à pilha e ao ID do usuário, passe os seguintes cabeçalhos em cada solicitação:

x-amzn-agentaccess-workspaces-applications-stack— o nome da pilha ou ARN.
x-amzn-agentaccess-workspaces-applications-user-id— o ID do usuário da sessão.

nota

O x-amzn-agentaccess-workspaces-applications-user-id cabeçalho é opcional. Se você omitir, o servidor MCP derivará a identidade do usuário da sessão autenticada. Ele usa AWS SourceIdentity quando um está presente e, caso contrário, o principal do IAM do chamador. SourceIdentitypreserva a identidade corporativa original do usuário quando ele assume uma função do IAM. Isso vale mesmo quando as funções são encadeadas por meio de um provedor de identidade externo (IdP).


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

Em vez disso, para se conectar a um URL de streaming, gere um usando a CreateStreamingURL API e passe-o como x-amzn-agentaccess-streaming-session-url cabeçalho em cada solicitação. Nenhum parâmetro específico do agente é necessário. O comportamento do agente é determinado pela configuração de acesso do agente da pilha.


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 obter mais informações sobre a CreateStreamingURL API, consulte o CreateStreamingURL na Referência de API do Amazon WorkSpaces Applications 2.0.

Conectando-se com frotas unidas a um domínio

Quando os agentes acessam instâncias de streaming associadas ao domínio, a conexão deve ser federada por meio de um provedor SAML. Esse requisito se aplica tanto às sessões tradicionais quanto às de agentes. Para sessões com agentes, Certificate-Based Autentificação é obrigatório.

Como as instâncias de streaming associadas ao domínio exigem acesso por meio do SAML, seu cliente MCP deve fornecer uma declaração SAML assinada em vez de uma URL de streaming. As asserções SAML codificadas excedem os limites de tamanho do cabeçalho HTTP. Para evitar isso, use o metadata campo emmcp-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

O metadata parâmetro foi adicionado na mcp-proxy-for-aws versão 1.6.1. As versões anteriores não podem injetar o _meta campo sem desenvolvimento adicional. Para atualizar, executepip install -U mcp-proxy-for-aws.

Para obter mais informações sobre como configurar a federação SAML com WorkSpaces aplicativos, consulte Configurando o SAML no Guia de administração de WorkSpaces aplicativos da Amazon. Para obter mais informações e um exemplo prático completo, consulte o repositório sample-code-for-workspaces-agent-access em Samples on. AWS GitHub

Modos de conexão

Você pode controlar como seu agente espera que a sessão de desktop fique disponível definindo o x-amzn-agentaccess-connect-mode cabeçalho em suas solicitações de MCP.

nota

Os modos de conexão se aplicam tanto a frotas não associadas a um domínio quanto a frotas associadas a um domínio. Defina o x-amzn-agentaccess-connect-mode cabeçalho ao lado de qualquer mecanismo de autenticação que seu tipo de frota usa. Para frotas não associadas a um domínio, esses são os cabeçalhos de pilha e ID de usuário ou um cabeçalho de URL de streaming. Para frotas unidas ao domínio, são os metadados de declaração do SAML.

Os seguintes modos estão disponíveis:

BLOQUEIO (padrão) — O servidor MCP espera até que a conexão de desktop esteja totalmente estabelecida antes de responder. Quando tools/list devolvidas, todas as ferramentas estão imediatamente disponíveis.
SONDAGEM — O servidor MCP responde imediatamente sem esperar pela conexão com o desktop. Inicialmente, somente a connection_status ferramenta está disponível. Seu agente pesquisa essa ferramenta até que a conexão seja estabelecida, momento em que o conjunto completo de ferramentas fica disponível.

Use o modo POLLING quando quiser que seu agente realize outro trabalho enquanto aguarda a conexão com o desktop ou quando precisar de mais controle sobre o comportamento do tempo limite da conexão.

O exemplo a seguir mostra como usar o 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()

Limpeza da sessão

Você pode controlar se a sessão de streaming expira quando seu agente encerra a conexão definindo o x-amzn-agentaccess-expire-streaming-session-on-delete cabeçalho em suas solicitações de MCP. Os seguintes valores estão disponíveis:

true — Quando seu agente envia uma DELETE solicitação HTTP explícita, o servidor MCP expira a sessão de streaming de WorkSpaces aplicativos como parte da limpeza. A expiração da sessão encerra a instância de streaming subjacente e aciona a política de escalonamento automático configurada da frota. Para obter mais informações, consulte Fleet Auto Scaling para aplicativos da Amazon WorkSpaces.
false (padrão) — A sessão de streaming continua em execução até que o tempo limite de desconexão seja atingido. Para obter mais informações sobre o tempo limite de desconexão, consulte. Crie uma frota nos WorkSpaces aplicativos da Amazon

nota

Por padrão, um cliente mcp-proxy-for-aws MCP processa automaticamente a DELETE solicitação quando você encerra adequadamente o ciclo de vida do cliente.

Ferramentas disponíveis

O servidor MCP fornece as seguintes ferramentas. Os agentes os usam para interagir com o desktop durante uma sessão de streaming. Todos os nomes de ferramentas usam o agentaccess___ prefixo.

Ferramentas de mouse

left_click

Clique com o botão esquerdo nas coordenadas fornecidas.

Parâmetros: x (obrigatório), y (obrigatório), modifiers (opcional, por exemplo ctrl ouctrl+shift).

double_click

Clique duas vezes nas coordenadas fornecidas.