翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

WorkSpaces アプリケーション MCP サーバー

WorkSpaces アプリケーション MCP サーバーは、ストリーミングセッション中にデスクトップアプリケーションとやり取りするためのモデルコンテキストプロトコル (MCP) ツールを AI エージェントに提供するフルマネージドサービスです。エージェントは、ボタンのクリック、テキストの入力、スクロール、デスクトップのスクリーンショットの撮影を行うことができます。

概要

スタックでエージェントアクセスを有効にすると、エージェントはマネージド MCP サーバーに接続してデスクトップアプリケーションとやり取りできます。MCP サーバーは、エージェントとストリーミングセッション間の通信を処理します。エージェントは MCP ツールリクエストを送信し、サーバーはそれらをデスクトップで実行します。

エージェントアクセスはnon-domain-joinedフリートとドメインに参加していないフリートの両方をサポートします。接続方法はフリートタイプによって異なります。non-domain-joinedフリートの場合、2 つの方法のいずれかで接続できます。最初に、スタックとユーザー ID を x-amzn-agentaccess-workspaces-applications-stackと の 2 つのヘッダーとして指定しますx-amzn-agentaccess-workspaces-applications-user-id。次に、MCP サーバーがストリーミングセッションを作成します。2 番目には、自分でストリーミング URL を生成し、ヘッダーとして渡します。ドメインに参加しているフリートの場合は、SAML フェデレーションを使用して認証します。フリートに一致するパスについては、「」を参照してくださいMCP サーバーへの接続。

MCP サーバーへの接続

エージェントは、次のエンドポイントで MCP サーバーに接続します。

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

region を、リージョンコードに置き換えます。サポートされているリージョンとそのエンドポイントについては、「」を参照してくださいWorkSpaces アプリケーション MCP エンドポイント。

MCP サーバーは AWS クラウドでホストされ、Streamable HTTP をトランスポートプロトコルとして使用します。サーバーコンポーネントをインストールまたは保守する必要はありません。

エージェントを接続するには、エージェントがリクエストを承認する方法とストリーミングセッションを識別する方法の 2 つの選択を行います。

承認を要求する

SigV4 署名または AWS サインインによる OAuth 2.1 認可の 2 つの方法のいずれかでリクエストを承認できます。

SigV4 署名

SigV4 を使用するには、サービス名 の IAM 認証情報を使用して各リクエストに署名しますagentaccess-mcp。次の Python の例は、 を使用した一般的な接続パターンを示しています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
    ...

他の言語の場合は、送信 MCP リクエスト用に独自の SigV4 署名ロジックを記述するか、SigV4 署名をサポートするライブラリを使用します。の詳細についてはmcp-proxy-for-aws、GitHub のmcp-proxy-for-aws」を参照してください。

OAuth 2.1 認可

IAM 認証情報を使用してリクエストに署名する代わりに、MCP サーバーは MCP AWS サーバーと同じ方法で、 AWS サインインによる OAuth 2.1 認可をサポートします。 AWS サインインは認可サーバーとして機能します。短期間のスコープ付きアクセストークンを発行します。MCP サーバーは、これらのトークンをベアラートークンとして受け入れます。OAuth は、既存の IAM ID、アクセス許可、および組織コントロールを使用します。エージェントを承認すると、ユーザーに代わって MCP サーバーにアクセスできます。追加のアクセス許可は取得されません。 AWS は、すべてのリクエストを IAM ポリシーと照合します。

Kiro、Claude Code、Cursor、Codex、Gemini などの OAuth 互換 MCP クライアントは、ローカルプロキシソフトウェアを使用せずに MCP サーバーエンドポイントに直接接続できます。 AWS Sign-In は 2 つの認可モデルをサポートしています。

MCP サーバーの OAuth 認可は、MCP サーバーエンドポイント () を使用して、 AWS MCP サーバーの場合と同じように機能しますhttps://agentaccess-mcp.region.api.aws/mcp。セットアップ、必要な IAM アクセス許可、ガバナンスとモニタリングのオプションについては、OAuth 用エージェントツールキットユーザーガイド」の「AWS MCP サーバーの OAuth 2.1 認証」および「サインインユーザーガイド」のOAuth 2.0 でAWS サインイン」を参照してください。

セッション識別

ストリーミングセッションの識別方法は、フリートタイプによって異なります。

non-domain-joinedフリートとの接続

non-domain-joinedフリートの場合、2 つの方法のいずれかで接続できます。スタックとユーザー ID をヘッダーとして指定すると、MCP サーバーがストリーミングセッションを作成します。これは、静的に設定する MCP クライアントに適しています。このようなクライアントは固定ヘッダーペアを保持できますが、ストリーミング URL を生成したり、有効期限が切れたときに置き換えたりできないためです。または、ストリーミング URL を自分で生成し、ヘッダーとして渡します。このアプローチは、有効期間の設定など、セッションの作成を制御する必要がある場合に使用します。

スタックとユーザー ID を使用して接続するには、すべてのリクエストで次のヘッダーを渡します。

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

代わりにストリーミング URL で接続するには、 CreateStreamingURL API を使用してストリーミング URL を生成し、すべてのリクエストでx-amzn-agentaccess-streaming-session-urlヘッダーとして渡します。エージェント固有のパラメータは必要ありません。エージェントの動作は、スタックのエージェントアクセス設定によって決まります。

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

CreateStreamingURL API の詳細については、Amazon WorkSpaces Applications 2.0 API Reference」の「CreateStreamingURL」を参照してください。

ドメインに参加しているフリートとの接続

エージェントがドメインに参加しているストリーミングインスタンスにアクセスする場合、接続は SAML プロバイダーを介してフェデレーションされる必要があります。この要件は、従来のセッションとエージェントセッションの両方に適用されます。エージェントセッションの場合は、 証明書ベースの認証 が必要です。

ドメイン結合ストリーミングインスタンスは SAML 経由でアクセスする必要があるため、MCP クライアントはストリーミング URL の代わりに署名付き SAML アサーションを提供する必要があります。エンコードされた SAML アサーションが HTTP ヘッダーのサイズ制限を超えています。これを回避するには、 の metadataフィールドを使用します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, _):
    ...

WorkSpaces アプリケーションを使用した SAML フェデレーションの設定の詳細については、「Amazon WorkSpaces アプリケーション管理ガイド」の「SAML の設定」を参照してください。 Amazon WorkSpaces 詳細と完全な実例については、 AWS GitHub の Samples の sample-code-for-workspaces-agent-access リポジトリを参照してください。

接続モード

MCP リクエストで x-amzn-agentaccess-connect-modeヘッダーを設定することで、エージェントがデスクトップセッションが利用可能になるまでの待機方法を制御できます。

次の方法を使用できます。

デスクトップ接続を待っている間にエージェントが他の作業を実行できるようにする場合、または接続タイムアウト動作をより詳細に制御する必要がある場合は、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()

セッションのクリーンアップ

MCP リクエストで x-amzn-agentaccess-expire-streaming-session-on-deleteヘッダーを設定することで、エージェントが接続を終了したときにストリーミングセッションの有効期限が切れるかどうかを制御できます。次の値を使用できます。

使用可能なツール

MCP サーバーには以下のツールが用意されています。エージェントはそれらを使用して、ストリーミングセッション中にデスクトップとやり取りします。すべてのツール名は agentaccess___ プレフィックスを使用します。

マウスツール

キーボードツール

画面ツール

アプリケーションツール

セッションツール

MCP ツールの転送

MCP ツール転送を使用すると、エージェントはアプリケーションとオペレーティングシステムを直接操作できます。コンピュータ使用ツールを使用する代わりに、直接 MCP 呼び出しを行います。ツール転送を有効にすると、MCP サーバーは WorkSpaces アプリケーションセッションで設定されたツールをエージェントに送信します。

ツール転送の設定

MCP ツールの転送を設定するには:

MCP ツールの転送に関する考慮事項

MCP ツール転送を設定するときは、次の考慮事項に注意してください。

転送されたツールがエージェントに表示される方法

サーバー間の衝突を防ぐために、MCP サーバーは次のパターンを使用してエージェントのツールリスト内の転送された各ツールの名前を変更します。

forwarded___server-name___original-tool-name

server-name は、設定ファイルのキーです。たとえば、weatherサーバーのget_forecastツールが として一覧表示されますforwarded___weather___get_forecast。エージェントが転送された名前を呼び出すと、MCP サーバーは所有サーバー上の元のツールにリクエストをルーティングします。ツール名に一致するエージェントコードには、このプレフィックスが必要です。

ツール転送の IAM アクセス許可

転送されたツールを呼び出すための IAM アクションは ですCallForwardedTool。特定のスタックへのアクセスを制限するには、 StackArn条件キーを使用します。

{
  "Action": "agentaccess-mcp:*",
  "Resource": "*",
  "Condition": {
    "ArnLike": {
      "agentaccess-mcp:StackArn": "arn:aws:appstream:region:account-id:stack/stack-name"
    }
  }
}

互換性のあるフレームワーク

Streamable HTTP および SigV4 署名をサポートする任意の MCP 互換エージェントフレームワークから WorkSpaces アプリケーション MCP サーバーに接続できます。以下のフレームワークがテストされています。

モニタリング

エージェントのアクティビティは、次のサービスを通じてモニタリングできます。

はじめに

WorkSpaces アプリケーション MCP サーバーの使用を開始するには、「」を参照してくださいWorkSpaces アプリケーションへのアクセス権をエージェントに付与する。