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

# WorkSpaces アプリケーション MCP サーバー
<a name="agent-access-mcp-server"></a>

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

## 概要
<a name="agent-access-mcp-server-overview"></a>

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

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

エージェントアクセスはnon-domain-joinedフリートとドメインに参加していないフリートの両方をサポートします。接続方法はフリートタイプによって異なります。Non-domain-joinedフリートはストリーミング URL でセッションを認証し、ドメインに参加しているフリートは SAML フェデレーションを介して認証します。フリートに一致するパスについては、「」を参照してください[MCP サーバーへの接続](#agent-access-mcp-server-endpoint)。

## MCP サーバーへの接続
<a name="agent-access-mcp-server-endpoint"></a>

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

```
https://agentaccess-mcp.{{region}}.api.aws/mcp
```

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

すべてのリクエストは、サービス名 の IAM 認証情報を使用して SigV4-signedされている必要があります`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](https://github.com/aws/mcp-proxy-for-aws)」を参照してください。

ストリーミングセッションの認証方法は、フリートタイプによって異なります。
+ **Non-domain-joinedフリート —** ストリーミング URL をヘッダーとして渡します。「[non-domain-joinedフリートとの接続](#agent-access-mcp-server-connect-ndj)」を参照してください。
+ **ドメイン結合フリート** — 署名付き SAML アサーションをメタデータとして渡します。「[ドメインに参加しているフリートとの接続](#agent-access-mcp-server-connect-dj)」を参照してください。

### non-domain-joinedフリートとの接続
<a name="agent-access-mcp-server-connect-ndj"></a>

non-domain-joinedフリートの場合、 `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](https://docs.aws.amazon.com/appstream2/latest/APIReference/API_CreateStreamingURL.html)」を参照してください。

### ドメインに参加しているフリートとの接続
<a name="agent-access-mcp-server-connect-dj"></a>

エージェントがドメインに参加しているストリーミングインスタンスにアクセスする場合、接続は 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, _):
    ...
```

**注記**  
`metadata` パラメータが`mcp-proxy-for-aws`バージョン 1.6.1 で追加されました。以前のバージョンでは、追加の開発なしで `_meta`フィールドを挿入することはできません。アップグレードするには、 を実行します`pip install -U mcp-proxy-for-aws`。

WorkSpaces アプリケーションを使用した SAML フェデレーションの設定の詳細については、「Amazon WorkSpaces アプリケーション管理ガイド」の[「SAML の設定](https://docs.aws.amazon.com/appstream2/latest/developerguide/active-directory-overview.html)」を参照してください。 *Amazon WorkSpaces * 詳細と完全な実例については、GitHub の Samples の [sample-code-for-workspaces-agent-access](https://github.com/aws-samples/sample-code-for-workspaces-agent-access/tree/main) AWS リポジトリを参照してください。

## 接続モード
<a name="agent-access-mcp-server-connect-mode"></a>

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

**注記**  
接続モードは、non-domain-joinedトとドメイン結合フリートの両方に適用されます。フリートタイプが使用する認証メカニズム (non-domain-joinedフリートの場合は streaming-URL ヘッダー、ドメイン結合フリートの場合は SAML アサーションメタデータ) とともに `X-Amzn-AgentAccess-Connect-Mode`ヘッダーを設定します。

次の方法を使用できます。
+ **BLOCKING** (デフォルト) — MCP サーバーは、応答する前にデスクトップ接続が完全に確立されるまで待機します。が `tools/list`を返すと、すべてのツールがすぐに使用できます。
+ **POLLING** — MCP サーバーはデスクトップ接続を待たずにすぐに応答します。最初は、 `connection_status` ツールのみを使用できます。エージェントは、接続が確立されるまでこのツールをポーリングし、その時点で完全なツールセットが利用可能になります。

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

## セッションのクリーンアップ
<a name="agent-access-mcp-server-session-cleanup"></a>

MCP リクエストで `X-Amzn-AgentAccess-Expire-Streaming-Session-On-Delete`ヘッダーを設定することで、エージェントが接続を終了したときにストリーミングセッションの有効期限が切れるかどうかを制御できます。次の値を使用できます。
+ **true** — エージェントが明示的な HTTP `DELETE`リクエストを送信すると、MCP サーバーはクリーンアップの一環として WorkSpaces アプリケーションストリーミングセッションを期限切れにします。セッションの有効期限が切れると、基盤となるストリーミングインスタンスが終了し、フリートの設定済み自動スケーリングポリシーがトリガーされます。詳細については、「[Amazon WorkSpaces アプリケーションのフリートAuto Scaling](autoscaling.md)」を参照してください。
+ **false** (デフォルト) — ストリーミングセッションは、切断タイムアウトに達するまで実行され続けます。切断タイムアウトの詳細については、「」を参照してください[Amazon WorkSpaces アプリケーションでフリートを作成する](set-up-stacks-fleets-create.md)。

**注記**  
デフォルトでは、クライアントライフサイクルを適切に終了すると`mcp-proxy-for-aws`、MCP クライアントが自動的に`DELETE`リクエストを処理します。

## 使用可能なツール
<a name="agent-access-mcp-server-tools"></a>

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

### マウスツール
<a name="agent-access-mcp-tools-mouse"></a>

`left_click`  
指定された座標で左クリックを実行します。  
パラメータ: `x` (必須)`y`、 (必須）、 `modifiers` (オプション、例: `ctrl`または `ctrl+shift`)。

`double_click`  
指定された座標でダブルクリックを実行します。  
パラメータ: `x` (必須）、 `y` (必須）、 `modifiers` (オプション）。

`triple_click`  
指定された座標でトリプルクリックを実行します。  
パラメータ: `x` (必須）、 `y` (必須）、 `modifiers` (オプション）。

`right_click`  
指定された座標で右クリックを実行します。  
パラメータ: `x` (必須）、 `y` (必須）、 `modifiers` (オプション）。

`middle_click`  
指定された座標でミドルクリックを実行します。  
パラメータ: `x` (必須）、 `y` (必須）、 `modifiers` (オプション）。

`left_click_drag`  
開始座標から終了座標への左クリックドラッグを実行します。  
パラメータ: `start_x` (必須)`start_y`、 (必須）、 `end_x` (必須）、 `end_y` (必須）。

`left_mouse_down`  
指定された座標で左マウスボタンを長押しします。  
パラメータ: `x` (必須）、 `y` (必須）、 `modifiers` (オプション）。

`left_mouse_up`  
指定された座標で左マウスボタンを離します。  
パラメータ: `x` (必須）、 `y` (必須）、 `modifiers` (オプション）。

`move_pointer`  
ポインタを指定された座標に移動します。  
パラメータ: `x` (必須）、 `y` (必須）。

`scroll`  
指定された座標でマウスホイールをスクロールします。  
パラメータ: `x` (必須)`y`、 (必須 — `scroll_direction` `Up`、`Down`、、または `Right`)`Left`、 `scroll_amount` (必須 — ティックで、120 ティックは 1 ホイールノッチに相当）、 `modifiers` (オプション）。

### キーボードツール
<a name="agent-access-mcp-tools-keyboard"></a>

`type_text`  
文字ごとにキーボードイベントをシミュレートしてテキストを入力します。  
パラメータ: `text` (必須 — 最大 10,000 文字）。

`key`  
キーまたはキーの組み合わせを押します。  
パラメータ: `keys` (必須 — 、`a``ctrl+c`、 など`+`、 によって結合された単一のキーまたは組み合わせ`ctrl+shift+s`)。

`hold_key`  
指定された期間、キーまたはキーの組み合わせを保持します。  
パラメータ: `keys` (必須）、 `duration` (必須 — 1～30 秒）。

### 画面ツール
<a name="agent-access-mcp-tools-screen"></a>

`screenshot`  
デスクトップのスクリーンショットをキャプチャします。返される画像ディメンションは、すべてのマウスツールの座標空間を定義します。  
パラメータ: `include_cursor` (オプション — デフォルトは )`false`。

## MCP ツールの転送
<a name="agent-access-mcp-tool-forwarding-details"></a>

MCP ツール転送を使用すると、エージェントはコンピュータ使用ツールを使用するのではなく、直接 MCP 呼び出しを通じてアプリケーションやデスクトップオペレーティングシステムとやり取りできます。ツール転送を有効にすると、MCP サーバーは WorkSpaces アプリケーションセッションで設定されたツールをエージェントに転送します。

### ツール転送の設定
<a name="agent-access-tool-forwarding-setup"></a>

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

1. **ツール転送を有効にする** — API またはコンソール設定を使用して`FORWARD_MCP_TOOLS`エージェントアクションを有効にします。

1. **WorkSpace で MCP サーバーを設定する** — サービスは、次のパスで設定ファイルを検索します。

   ```
   C:\ProgramData\NICE\dcv\mcp_server_redirection_config.json
   ```

1. **ツールの可用性**の検証 — 設定ファイルが存在する場合、サービスは ファイルで設定された MCP サーバーに接続し、ツールを転送します。転送されたツールは、エージェントが使用可能なツールを一覧表示したときに表示されます。

**注記**  
ツール転送が機能するには、IAM アクセスとサービス設定の両方を有効にする必要があります。IAM アクセス許可は、サービス設定を上書きしません。

### ツール転送の IAM アクセス許可
<a name="agent-access-tool-forwarding-iam"></a>

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

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

## 互換性のあるフレームワーク
<a name="agent-access-mcp-server-frameworks"></a>

Streamable HTTP および SigV4 署名をサポートする任意の MCP 互換エージェントフレームワークから WorkSpaces アプリケーション MCP サーバーに接続できます。以下のフレームワークがテストされています。
+ [Strands Agents SDK](https://strandsagents.com/docs/user-guide/concepts/tools/mcp-tools/) — ネイティブ MCP クライアントサポートを提供します。
+ [mcp-proxy-for-aws](https://github.com/aws/mcp-proxy-for-aws) — Python での MCP リクエストの SigV4 署名を処理する軽量トランスポート。

## モニタリング
<a name="agent-access-mcp-server-monitoring"></a>

次のサービスを使用して、エージェントのアクティビティをモニタリングできます。
+ **AWS CloudTrail** — エージェントセッションイベントは CloudTrail に記録されます。エージェントが接続するタイミング、使用するツール、セッションが終了するタイミングを表示できます。ツール呼び出しはデータイベントであり、データイベントをログに記録する証跡を設定する必要があります。詳細については、*CloudTrail ユーザーガイド*」の[「データイベントのログ記録](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html)」を参照してください。
+ **CloudWatch** — エージェントセッションの運用メトリクスは CloudWatch で利用できます。
+ **Amazon S3** — スクリーンショットストレージを設定すると、エージェントセッション中にキャプチャされたスクリーンショットは、指定した Amazon S3 バケットで使用できます。スクリーンショットは、次のキー形式で保存されます。

  ```
  agentaccess/screenshots/year={{YYYY}}/month={{MM}}/day={{DD}}/{{session-id}}/{{timestamp}}.png
  ```

  パスの UUID は WorkSpaces アプリケーションストリーミングセッション ID です。

## はじめに
<a name="agent-access-mcp-server-get-started"></a>

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