AWS appstream2: MCP server page split into topic subpages; content moved out
Summary
The WorkSpaces Applications MCP server page was converted from a single long page into a short landing page with a Topics list linking to new subpages (Overview, Prerequisites, Session behavior, Connecting to the MCP server, Connection modes, Session cleanup, Available tools, MCP tool forwarding, Monitoring). The detailed body content — including SigV4/OAuth 2.1 authorization, session identification headers, connection modes, session cleanup, tool listings, tool forwarding, IAM permissions, and monitoring — was removed from this file and relocated to the linked pages. A new 'Best practices for computer-use agents' link was added.
Security assessment
This is a documentation restructuring: the security-relevant material that was removed (e.g. the removed line '-The IAM action for calling forwarded tools is `CallForwardedTool`. To limit access to specific stacks, use the `StackArn` condition key:') is not deleted from the docs but moved to the newly linked subpages, and the added lines are navigation links such as the Monitoring topic. No vulnerability, credential, or exposure change is introduced by this edit.
Evidence
+ * [Monitoring](./agent-access-mcp-server-monitoring.html)
Diff
diff --git a/appstream2/latest/developerguide/agent-access-mcp-server.md b/appstream2/latest/developerguide/agent-access-mcp-server.md index 3b94713..0a45b31 100644 --- a//appstream2/latest/developerguide/agent-access-mcp-server.md +++ b//appstream2/latest/developerguide/agent-access-mcp-server.md @@ -7 +7 @@ -OverviewConnecting to the MCP serverConnection modesSession cleanupAvailable toolsMCP tool forwardingCompatible frameworksMonitoringGet started +# Access the MCP server @@ -9 +9 @@ OverviewConnecting to the MCP serverConnection modesSession cleanupAvailable too -# 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 operate desktop applications during streaming sessions. Agents can click buttons, enter text, scroll, and take screenshots of the desktop. @@ -11 +11 @@ OverviewConnecting to the MCP serverConnection modesSession cleanupAvailable too -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. +###### Topics @@ -13 +13 @@ The WorkSpaces Applications MCP server is a fully managed service that provides -## Overview + * [Overview](./agent-access-mcp-server-overview.html) @@ -15 +15 @@ The WorkSpaces Applications MCP server is a fully managed service that provides -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. + * [Prerequisites](./agent-access-mcp-prerequisites.html) @@ -17 +17 @@ When you enable agent access on a stack, agents can connect to the managed MCP s -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. + * [Session behavior](./agent-access-mcp-session-behavior.html) @@ -19 +19 @@ Agent access supports both non-domain-joined and domain-joined fleets. The conne -## Connecting to the MCP server + * [Connecting to the MCP server](./agent-access-mcp-server-endpoint.html) @@ -21 +21 @@ Agent access supports both non-domain-joined and domain-joined fleets. The conne -Agents connect to the MCP server at the following endpoint: + * [Connection modes](./agent-access-mcp-server-connect-mode.html) @@ -22,0 +23 @@ Agents connect to the MCP server at the following endpoint: + * [Session cleanup](./agent-access-mcp-server-session-cleanup.html) @@ -24 +25 @@ Agents connect to the MCP server at the following endpoint: - https://agentaccess-mcp.region.api.aws/mcp + * [Available tools](./agent-access-mcp-server-tools.html) @@ -26 +27 @@ Agents connect to the MCP server at the following endpoint: -Replace `region` with your Region code. For the supported Regions and their endpoints, see [WorkSpaces Applications MCP endpoints](./allowed-domains.html#allowed-domains-mcp-endpoints). + * [MCP tool forwarding](./agent-access-mcp-tool-forwarding-details.html) @@ -28 +29 @@ Replace `region` with your Region code. For the supported Regions and their endp -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. + * [Monitoring](./agent-access-mcp-server-monitoring.html) @@ -30 +30,0 @@ The MCP server is hosted in the AWS cloud and uses Streamable HTTP as its transp -###### Note @@ -32 +31,0 @@ The MCP server is hosted in the AWS cloud and uses Streamable HTTP as its transp -Before an agent can connect, the fleet associated with your stack must be running and have available capacity. @@ -34,475 +32,0 @@ Before an agent can connect, the fleet associated with your stack must be runnin -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](https://github.com/aws/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](https://docs.aws.amazon.com/agent-toolkit/latest/userguide/oauth-authentication.html) in the _Agent Toolkit for AWS User Guide_ and [Sign-In with OAuth 2.0](https://docs.aws.amazon.com/signin/latest/userguide/oauth-sign-in-overview.html) 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](https://docs.aws.amazon.com/appstream2/latest/APIReference/API_CreateStreamingURL.html) 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](./certificate-based-authentication.html) 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](https://docs.aws.amazon.com/appstream2/latest/developerguide/active-directory-overview.html) in the _Amazon WorkSpaces Applications Administration Guide_. For more information and a complete working example, see the [sample-code-for-workspaces-agent-access](https://github.com/aws-samples/sample-code-for-workspaces-agent-access/tree/main) 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. - -