Overview Connecting to the MCP server Connection modes Session cleanup Available tools MCP tool forwarding Compatible frameworks Monitoring Get started

WorkSpaces Applications MCP server

The WorkSpaces Applications MCP server is a fully managed service that provides AI agents with Model Context Protocol (MCP) tools to interact with desktop applications during streaming sessions. Agents can click buttons, enter text, scroll, and take screenshots of the desktop.

Overview

When you enable agent access on a stack, agents can connect to the managed MCP server to interact with desktop applications. The MCP server handles the communication between your agent and the streaming session. Your agent sends MCP tool requests, and the server executes them on the desktop.

The MCP server is hosted in the AWS cloud. You don't need to install or maintain any server components. The server uses Streamable HTTP as its transport protocol.

Agent access supports both non-domain-joined and domain-joined fleets. The connection method differs by fleet type. Non-domain-joined fleets authenticate the session with a streaming URL, while domain-joined fleets authenticate through SAML federation. For the path that matches your fleet, see Connecting to the MCP server.

Connecting to the MCP server

Agents connect to the MCP server at the following endpoint:


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

The MCP server is hosted in the AWS cloud and uses Streamable HTTP as its transport protocol. You don't need to install or maintain any server components.

Every request must be SigV4-signed using IAM credentials with the service name agentaccess-mcp. The following Python example shows the general connection pattern using 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
    ...

For other languages, write your own SigV4 signing logic for outgoing MCP requests or use a library that supports SigV4 signing. For more information about mcp-proxy-for-aws, see mcp-proxy-for-aws on GitHub.

How you authenticate the streaming session depends on your fleet type:

Non-domain-joined fleets — Pass a streaming URL as a header. See Connecting with non-domain-joined fleets.
Domain-joined fleets — Pass a signed SAML assertion as metadata. See Connecting with domain-joined fleets.

Note

At any given time, only one agent can connect to a unique session. Named users, specified through the UserId parameter, can have only one active session per fleet at a time. To run multiple agents concurrently, each agent must connect to its own unique session.

Connecting with non-domain-joined fleets

For non-domain-joined fleets, generate a streaming URL using the CreateStreamingURL API and pass it as the X-Amzn-AgentAccess-Streaming-Session-Url header on every request. No agent-specific parameters are required. The agent behavior is determined by the stack's agent access configuration.


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

For more information about the CreateStreamingURL API, see CreateStreamingURL in the Amazon WorkSpaces Applications 2.0 API Reference.

Connecting with domain-joined fleets

When agents access domain-joined streaming instances, the connection must be federated through a SAML provider. This requirement applies to both traditional and agent sessions. For agent sessions, Certificate-Based Authentication is required.

Because domain-joined streaming instances require access through SAML, your MCP client must provide a signed SAML assertion instead of a streaming URL. Encoded SAML assertions exceed HTTP header size limits. To avoid this, use the metadata field in 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, _):
    ...

Note

The metadata parameter was added in mcp-proxy-for-aws version 1.6.1. Earlier versions cannot inject the _meta field without additional development. To upgrade, run pip install -U mcp-proxy-for-aws.

For more information about setting up SAML federation with WorkSpaces Applications, see Setting up SAML in the Amazon WorkSpaces Applications Administration Guide. For more information and a complete working example, see the sample-code-for-workspaces-agent-access repository in AWS Samples on GitHub.

Connection modes

You can control how your agent waits for the desktop session to become available by setting the X-Amzn-AgentAccess-Connect-Mode header on your MCP requests.

Note

Connection modes apply to both non-domain-joined and domain-joined fleets. Set the X-Amzn-AgentAccess-Connect-Mode header alongside whichever authentication mechanism your fleet type uses (the streaming-URL header for non-domain-joined fleets, or the SAML assertion metadata for domain-joined fleets).

The following modes are available:

BLOCKING (default) — The MCP server waits until the desktop connection is fully established before responding. When tools/list returns, all tools are immediately available.
POLLING — The MCP server responds immediately without waiting for the desktop connection. Initially, only the connection_status tool is available. Your agent polls this tool until the connection is established, at which point the full tool set becomes available.

Use POLLING mode when you want your agent to perform other work while waiting for the desktop connection, or when you need more control over connection timeout behavior.

The following example shows how to use POLLING mode:


# 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()

Session cleanup

You can control whether the streaming session is expired when your agent ends its connection by setting the X-Amzn-AgentAccess-Expire-Streaming-Session-On-Delete header on your MCP requests. The following values are available:

true — When your agent sends an explicit HTTP DELETE request, the MCP server expires the WorkSpaces Applications streaming session as part of cleanup. Expiring the session terminates the underlying streaming instance and triggers the fleet's configured autoscaling policy. For more information, see Fleet Auto Scaling for Amazon WorkSpaces Applications.
false (default) — The streaming session continues running until the disconnect timeout is reached. For more information about the disconnect timeout, see Create a Fleet in Amazon WorkSpaces Applications.

Note

By default, an mcp-proxy-for-aws MCP client automatically handles the DELETE request when you properly end the client lifecycle.

Available tools

The MCP server provides the following tools for agents to interact with the desktop during a streaming session. All tool names use the agentaccess___ prefix.

Mouse tools

left_click

Perform a left click at the given coordinates.

Parameters: x (required), y (required), modifiers (optional, for example ctrl or ctrl+shift).

double_click

Perform a double click at the given coordinates.