Connection Setup

• Endpoint: https://agentaccess-mcp.{region}.api.aws/mcp (Streamable HTTP transport).
• Signing: every request is SigV4-signed with service name agentaccess-mcp.
• IAM: grant the caller the specific agentaccess-mcp actions the agent uses, scoped by the agentaccess-mcp:StackArn condition key (see IAM permissions).
• Signing region MUST match the fleet region. Signing for a different region than the fleet lives in is rejected with 400 Bad Request (cross-region mismatch). Set AWS_REGION / the MCP signing region to the fleet's region and use the matching regional endpoint.
• There is no AWS CLI/SDK command that invokes the desktop tools — interaction is MCP-only. The CLI/SDK is used only for setup (streaming URL, fleet/stack config).
• Connect mode: you can also control how the connection waits for the desktop via the X-Amzn-AgentAccess-Connect-Mode header (BLOCKING default, or POLLING), sent alongside the auth headers below — see connection-modes.md.

IAM permissions (least privilege)

The service has no resource ARN hierarchy — the only resource scoping is the agentaccess-mcp:StackArn condition key (the AppStream stack ARN, derived from the streaming URL or supplied via the SAML path). So least privilege = enumerate only the actions your agent calls and scope them by stack.

Available actions: InvokeMcp (initialize / tools/list / ping — required to connect), GetScreenshot, LeftClick, DoubleClick, TripleClick, RightClick, MiddleClick, TypeText, KeyPress, HoldKey, Scroll, MovePointer, LeftClickDrag, LeftMouseDown, LeftMouseUp, CheckConnectionStatus, CallForwardedTool. This list is illustrative — consult the current Service Authorization Reference (opens in a new tab) for the authoritative, complete set of agentaccess-mcp actions.

Add the specific actions your agent uses (e.g. other click/drag tools, HoldKey, MovePointer, CheckConnectionStatus for POLLING, CallForwardedTool for forwarding). For setup the caller also needs appstream:CreateStreamingURL (and appstream:DescribeFleets), on the setup principal.

agentaccess-mcp:* with Resource: * (as some AWS docs show) also works but is broader than necessary — prefer the enumerated, stack-scoped policy above.

Prefer an IAM role (EC2 instance profile, ECS task role, or Lambda execution role) over an IAM user with long-lived access keys for the principal that signs MCP requests and calls CreateStreamingURL.

Choose your path by fleet type

Non-domain-joined fleets (streaming URL)

1. Generate a streaming URL:

   Copy

   aws appstream create-streaming-url \
     --stack-name <stack> --fleet-name <fleet> \
     --user-id <user> --validity 3600 \
     --query StreamingURL --output text

   Sets how long the URL stays valid for initiating a connection: Validity accepts 1–604800 seconds (7 days); the API default is 60 seconds. The streaming URL is a bearer credential that grants desktop access — use the shortest validity that covers your connection window (e.g. 300 s if the agent connects immediately) to limit the exposure window. Once connected, how long the session runs is governed by the fleet’s MaxUserDurationInSeconds and disconnect/idle timeouts, not by this value (see session-lifecycle.md).

2. Pass it on every request as the X-Amzn-AgentAccess-Streaming-Session-Url header.

Treat the streaming URL as a secret. It is a bearer token — retrieve it ephemerally at connect time; do not log it, persist it to disk, or pass it through insecure channels. If your orchestrator logs MCP headers, redact X-Amzn-AgentAccess-Streaming-Session-Url.

Python (mcp-proxy-for-aws signs each request; requires Python 3.10+ — running it via uvx mcp-proxy-for-aws ... avoids system-Python version issues):

Domain-joined fleets (SAML / Domain Join)

Domain-joined streaming instances must be accessed through SAML federation; a streaming URL is not used. Certificate-Based Authentication (CBA) is required for agent sessions.

The encoded SAML assertion exceeds HTTP header size limits, so it is injected via the MCP _meta field. mcp-proxy-for-aws 1.6.1+ exposes this as the metadata parameter:

The MCP server provisions a desktop session bound to the AD user identity in the assertion. Prerequisites: an IAM SAML provider registered with your IdP certificate, an IAM role trusting that provider, and a base64 assertion from your IdP (Okta, Entra ID, Ping, etc.).

Keep federation material ephemeral and secret. The SAML assertion is sensitive — do not log or persist it. Issue short-lived assertions (e.g. 5–15 min) and scope the assumed IAM role’s MaxSessionDuration to the minimum the agent’s task needs. Store IdP signing credentials in AWS Secrets Manager.

Connection methods (transport-level)

Concurrency

Only one agent can connect to a given session at a time, and a named user (UserId) can have only one active session per fleet at a time. To run agents in parallel, give each its own session/user.