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.

Agent access supports both non-domain-joined and domain-joined fleets. The connection method differs by fleet type. For non-domain-joined fleets, you can connect in either of two ways. In the first, you provide the stack and user ID as two headers: x-amzn-agentaccess-workspaces-applications-stack and x-amzn-agentaccess-workspaces-applications-user-id. The MCP server then creates the streaming session for you. In the second, you generate a streaming URL yourself and pass it as a header. For 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

Replace region with your Region code. For the supported Regions and their endpoints, see WorkSpaces Applications MCP endpoints.

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.

Note

Before an agent can connect, the fleet associated with your stack must be running and have available capacity.

To connect an agent, you make two choices: how the agent authorizes its requests, and how it identifies the streaming session.

Request authorization

You can authorize requests in one of two ways: SigV4 signing or OAuth 2.1 authorization through AWS Sign-In.

SigV4 signing

To use SigV4, sign each request 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.

OAuth 2.1 authorization

As an alternative to signing requests with IAM credentials, the MCP server supports OAuth 2.1 authorization through AWS Sign-In, the same way as the AWS MCP Server. AWS Sign-In acts as the authorization server. It issues short-lived, scoped access tokens. The MCP server accepts these tokens as bearer tokens. OAuth uses your existing IAM identities, permissions, and organizational controls. When you authorize an agent, it can access the MCP server on your behalf. It does not get extra permissions. AWS still checks every request against your IAM policies.

OAuth-compatible MCP clients — such as Kiro, Claude Code, Cursor, Codex, and Gemini — can connect directly to the MCP server endpoint without local proxy software. AWS Sign-In supports two authorization models:

Interactive authorization — For agents that can open a browser. The client registers through dynamic client registration, redirects you to an AWS Sign-In page to authenticate and approve access, and AWS Sign-In then issues and refreshes the access tokens.
Non-interactive authorization — For agents that already have AWS credentials and run without a browser (sometimes called headless authorization). The agent uses the OAuth client credentials grant to exchange SigV4-signed credentials for a short-lived access token.

OAuth authorization for the MCP server works the same way as it does for the AWS MCP Server, using the MCP server endpoint (https://agentaccess-mcp.region.api.aws/mcp). For setup, required IAM permissions, and governance and monitoring options, see OAuth 2.1 authentication for AWS MCP Server in the Agent Toolkit for AWS User Guide and Sign-In with OAuth 2.0 in the AWS Sign-In User Guide.

Session identification

How you identify the streaming session depends on your fleet type.

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, you can connect in either of two ways. Provide the stack and user ID as headers, and the MCP server creates the streaming session for you. This suits MCP clients that you configure statically, because such a client can hold a fixed pair of headers but cannot generate a streaming URL or replace one when it expires. Alternatively, generate a streaming URL yourself and pass it as a header. Use this approach when you need control over session creation, such as setting the validity period.

To connect with the stack and user ID, pass the following headers on every request:

x-amzn-agentaccess-workspaces-applications-stack — the stack name or ARN.
x-amzn-agentaccess-workspaces-applications-user-id — the user ID for the session.

Note

The x-amzn-agentaccess-workspaces-applications-user-id header is optional. If you omit it, the MCP server derives the user identity from the authenticated session. It uses the AWS SourceIdentity when one is present, and the caller's IAM principal otherwise. SourceIdentity preserves a user's original corporate identity when they assume an IAM role. This holds even when roles are chained through an external identity provider (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, _):
    ...

To connect with a streaming URL instead, generate one 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. For non-domain-joined fleets, that is either the stack and user ID headers or a streaming-URL header. For domain-joined fleets, it is the SAML assertion metadata.

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. Agents use them 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.