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

# Model Context Protocol (MCP) の統合
<a name="mcp-integration"></a>

Model Context Protocol (MCP) は、AI アプリケーションが外部ツールやデータソースと通信する方法を定義するオープンスタンダードです。MCP はクライアント/サーバーアーキテクチャを使用します。AI アプリケーションは、MCP サーバーに接続するクライアントとして機能します。各 MCP サーバーは、一連のツールを公開します。これらのツールは、AI アプリケーションがデータベースのクエリ、APIs の呼び出し、サードパーティーのサービスとのやり取りなどのタスクを実行するために呼び出すことができる構造化されたオペレーションです。

Amazon Quick の MCP 統合を使用すると、リモート MCP サーバーに接続して、AI アシスタントがそれらのサーバーが提供するツールを使用できるようにします。たとえば、プロジェクト管理システムへのアクセスを提供する MCP サーバーに接続できます。この接続により、アシスタントは会話の一部としてチケットの作成、問題の検索、ステータスの更新を行うことができます。MCP はオープンスタンダードであるため、ツールごとにカスタム統合を構築せずに、互換性のある任意のサーバーに接続できます。

パブリックインターネット経由で到達可能な MCP サーバーに接続できます。Amazon Quick VPC 接続を使用して、 AWS アカウントの Virtual Private Cloud (VPC) から到達可能なプライベート MCP サーバーに接続することもできます。MCP サーバーは、VPC 内、ピアリングまたはトランジットゲートウェイを介して到達可能な別の VPC、または AWS Direct Connect または VPN を介してオンプレミスで到達可能な VPC 内に配置できます。Amazon Quick で VPC 接続を作成する方法については、「」を参照してください[Amazon Quick Sight での VPC 接続の設定](working-with-aws-vpc.md)。

**重要**  
VPC 接続を介してプライベート MCP サーバーに接続する場合、MCP サーバーで使用される OAuth エンドポイントはパブリックインターネット経由で到達可能である必要があります。これは、ユーザー認証 (認可エンドポイントとトークンエンドポイント) とサービス認証 (トークンエンドポイント) の両方に適用されます。プライベート OAuth プロバイダーはサポートされていません。認証を必要としない MCP サーバーもサポートされています。

## サポートされる機能
<a name="mcp-integration-capabilities"></a>

MCP 統合は、MCP サーバーツールを Amazon Quick のアクションとして登録します。

**アクションコネクタ**  
MCP サーバーが公開する各ツールは、AI アシスタントが会話中に呼び出すことができるアクションとして登録します。この統合は、S256 チャレンジメソッドとリソースインジケータ (RFC 8707) でコード交換の証明キー (PKCE) を使用してアクセストークンを特定の MCP サーバーにバインドすることで、これらの接続を保護します。

## [開始する前に]
<a name="mcp-integration-prerequisites"></a>

MCP 統合を設定する前に、以下があることを確認してください。
+ 適切なアクセス権を持つ MCP サーバーエンドポイント。
+ 必要に応じて、MCP サーバーの認証認証情報。詳細については、「[MCP サーバーのセットアップと認証を準備する](#mcp-integration-authentication)」を参照してください。
+ Amazon Quick Enterprise サブスクリプション。
+ プライベート MCP サーバーに接続する場合、MCP サーバーへのネットワークアクセスを持つアクティブな Amazon Quick VPC 接続。詳細については、「[Amazon Quick Sight での VPC 接続の設定](working-with-aws-vpc.md)」を参照してください。

**注記**  
MCP 統合はリモートサーバーのみをサポートします。HTTP ストリーミングは、サーバー送信イベント (SSE) よりも優先されます。ローカル stdio 接続はサポートされていません。

## MCP サーバーのセットアップと認証を準備する
<a name="mcp-integration-authentication"></a>

MCP サーバーに接続すると、Amazon Quick は OAuth 2.0 Protected Resource Metadata (RFC 9728) を使用して認可サーバー情報を自動的に検出します。クライアントは、認証されていない最初のリクエストを MCP サーバーに送信します。サーバーが `resource_metadata` URL を含む`WWW-Authenticate`ヘッダーを含む 401 ステータスで応答した場合、Amazon Quick はその URL を使用してメタデータドキュメントを取得します。ヘッダーが存在しない場合、Amazon Quick はサーバールートの既知の URI にフォールバックします。

認可サーバーが動的クライアント登録 (DCR) をサポートしている場合、Amazon Quick は認可サーバーメタデータ`registration_endpoint`から検出された を使用して自動的に登録します。手動の認証情報設定は必要ありません。Amazon Quick は、機密クライアントフローとパブリッククライアントフローの両方をサポートしています。DCR は、選択した認証方法に関係なく適用されます。

認可サーバーが DCR をサポートしていない場合は、認証情報を手動で指定する必要があります。MCP サーバーの要件に一致する認証方法を選択します。

**ユーザー認証 (OAuth)**  
MCP サーバー設定から次の情報を収集します。  
+ **クライアント ID** – OAuth クライアント ID。
+ **パブリック OAuth クライアント** (オプション) – OAuth アプリケーションがパブリッククライアント設定 (クライアントシークレットなし) を使用している場合は、このチェックボックスをオンにします。
+ **クライアントシークレット** – OAuth クライアントシークレット。
+ **トークン URL** – OAuth トークンエンドポイント。
+ **認可 URL** – OAuth 認可エンドポイント。
+ **リダイレクト URL** – OAuth リダイレクト URI。
MCP **サーバーの OAuth アプリケーションがクライアントシークレットを使用しない場合は、パブリック** OAuth クライアントを選択します。これは、セキュリティのために PKCE のみに依存するパブリッククライアントに一般的です。このオプションを選択すると、**クライアントシークレット**フィールドは必要ありません。

**サービス認証 (Service-to-Service)**  
MCP サーバー設定から次の情報を収集します。  
+ **クライアント ID** – サービスクライアント ID。
+ **クライアントシークレット** – サービスクライアントシークレット。
+ **トークン URL** – サービストークンエンドポイント。

**認証なし**  
MCP サーバーが認証を必要としない場合、認証情報は必要ありません。認証されていないアクセスを許可する MCP サーバーの場合は、このオプションを選択します。

## MCP 統合をセットアップする
<a name="mcp-integration-setup"></a>

MCP サーバー設定と認証情報を準備したら、MCP 統合を作成します。

1. Amazon Quick コンソールで、**コネクタ**を選択します。

1. **チームの作成**タブを選択します。

1. **モデルコンテキストプロトコル (MCP) **を検索して選択します。

1. **統合の作成**ページで、統合の詳細を入力します。
   + **名前** – MCP 統合のわかりやすい名前。
   + **説明** (オプション) – 統合の目的。
   + **MCP サーバーエンドポイント** – MCP サーバーの URL。
   + **接続タイプ** – Amazon Quick が MCP サーバーに接続する方法を選択します。
     + **パブリックネットワーク** – このオプションは、パブリックインターネット経由で到達可能な MCP サーバーに使用します。
     + 名前付き VPC 接続 – このオプションをプライベート MCP サーバーに使用します。ドロップダウンには、Amazon Quick アカウントに設定されている VPC 接続が一覧表示されます。MCP サーバーへのネットワークアクセスを持つ接続を選択します。リストに VPC 接続が表示されない場合は、完全にプロビジョニングされ、アクティブであることを確認します。詳細については、「[Amazon Quick Sight での VPC 接続の設定](working-with-aws-vpc.md)」を参照してください。

1. **[Next]** (次へ) を選択します。

1. 認証方法 (ユーザー、サービス、または認証なし) を選択します。

1. 適切な設定の詳細を入力します。

1. [**作成して続ける]** を選択します。

1. 統合の詳細を確認します。

1. [**次へ**] を選択します。

1. 必要に応じて、他のユーザーと統合を共有します。

MCP 統合を作成すると、Amazon Quick は使用可能なツールを検出し、アクションとして登録します。

## 統合を確認する
<a name="mcp-integration-review"></a>

認証を設定したら、MCP 統合機能を確認します。

1. システムは MCP サーバーに接続し、使用可能な機能を検出します。

1. MCP サーバーが提供する利用可能なアクションとタスクのリストを確認します。

1. 統合設定と機能を確認します。

### 機能検出
<a name="mcp-integration-capabilities-discovery"></a>

で説明されている接続プロセス中に[MCP サーバーのセットアップと認証を準備する](#mcp-integration-authentication)、Amazon Quick は MCP サーバーが提供するツールも検出して登録します。検出が完了すると、各ツールは確認して有効にできるアクションとして一覧表示されます。

## MCP 統合の管理
<a name="mcp-integration-management"></a>

統合を編集、共有、または削除するには、「」を参照してください[既存の統合の管理](integration-workflows.md#managing-existing-integrations)。

## トラブルシューティング
<a name="mcp-integration-troubleshooting"></a>

次のガイダンスを使用して、Amazon Quick で MCP 統合を作成または使用する場合の一般的な問題を診断して解決します。

### コネクタ作成の問題
<a name="mcp-integration-troubleshooting-creation"></a>
+ **コネクタは検出を渡しますが、 で発行に失敗`Creation failed`**します。このエラーは通常、MCP サーバーの`tools/list`レスポンスの 1 つ以上のツール定義に無効な が含まれていることを意味します`inputSchema`。Amazon Quick は、公開フェーズ中に各ツールの を JSON Schema Draft 7 以降`inputSchema`と照合します。

  最も一般的な原因は、廃止された Draft 3 構文です。 `required`はプロパティ定義内のブール値です (例: `"required": true`)。JSON Schema Draft 7 以降では、 は の兄弟として、スキーマルートのプロパティ名の配列`required`である必要があります`properties`。

  ツール定義を更新して正しい形式を使用し、MCP サーバーを再デプロイします。再デプロイしたら、失敗したコネクタを削除し、検出と公開をトリガーする新しいコネクタを作成します。

  次の例は、誤ったドラフト 3 構文を示しています。

  ```
  {
    "type": "object",
    "properties": {
      "logNumber": {
        "type": "string",
        "description": "The permit log number",
        "required": true
      }
    }
  }
  ```

  次の例は、正しいドラフト 7 構文を示しています。

  ```
  {
    "type": "object",
    "properties": {
      "logNumber": {
        "type": "string",
        "description": "The permit log number"
      }
    },
    "required": ["logNumber"]
  }
  ```

  一部の MCP フレームワークライブラリとコードジェネレーターは、デフォルトでドラフト 3 構文を出力します。JSON スキーマ出力バージョンを選択するオプションについては、フレームワークのドキュメントを参照してください。デプロイする前に、任意の JSON Schema Draft 7 検証ツールを使用してスキーマを検証することもできます。`inputSchema` 要件の詳細については、「モデルコンテキストプロトコル仕様」の[「ツール](https://modelcontextprotocol.io/specification/latest/server/tools)」を参照してください。

  また、コネクタの作成が失敗する前に 2～5 分間ハングしていることにも気付くかもしれません。経過時間は、ネットワークタイムアウトではなく、公開フェーズ中の内部再試行を反映します。修正は同じです。JSON Schema Draft 7 のコンプライアンスに関するツール`inputSchema`定義を確認してください。

### VPC 接続の問題
<a name="mcp-integration-troubleshooting-vpc"></a>
+ **VPC 接続が**接続タイプの**ドロップダウンに表示されないか、選択した直後に MCP の作成が失敗する** – プロビジョニングが完了する前に、VPC 接続がドロップダウンに表示されることがあります。MCP 統合を作成する前に、VPC 接続が Amazon Quick 管理ページで使用可能な状態になるまで待ちます。詳細については、「[Amazon Quick Sight での VPC 接続の設定](working-with-aws-vpc.md)」を参照してください。
+ **MCP サーバーのホスト名が解決できないため、MCP の作成は失敗**します。Amazon Quick は MCP 統合にデフォルトの VPC DNS リゾルバーを使用しません。VPC 接続の **DNS リゾルバーエンドポイント**フィールドに、MCP サーバーのホスト名を解決できる Route 53 Resolver のインバウンドエンドポイント IP アドレスを入力する必要があります。この要件は、プライベートホスト名と、 AWS PrivateLink または Route 53 プライベートホストゾーンでフロントされるエンドポイントなど、VPC 内からプライベートアドレスに解決するパブリックホスト名の両方に適用されます。これらのリゾルバーエンドポイントがないと、MCP サーバーのホスト名を解決できず、統合の作成が失敗します。詳細については、「[Amazon Quick Sight での VPC 接続の設定](working-with-aws-vpc.md)」を参照してください。
+ **MCP サーバーが VPC 接続から到達できない** – Amazon Quick から MCP サーバーへのトラフィックは、VPC 接続のセットアップ中に選択したサブネットから発信されます。ルートテーブル、ネットワーク ACLs、およびセキュリティグループが、これらのサブネットと MCP サーバーエンドポイント間のトラフィックを許可していることを確認します。一般的な VPC ネットワークガイダンスについては、「」を参照してください[Amazon Quick Sight での VPC 接続の設定](working-with-aws-vpc.md)。
+ **プライベート MCP サーバーを使用する場合、認証は失敗**します – VPC 接続を介してプライベート MCP サーバーに接続する場合、MCP サーバーで使用される OAuth エンドポイントにパブリックインターネット経由で到達できる必要があります。これは、ユーザー認証 (認可エンドポイントとトークンエンドポイント) とサービス認証 (トークンエンドポイント) の両方に適用されます。プライベート OAuth プロバイダーはサポートされていません。MCP サーバーが保護されたリソースメタデータで返す OAuth URLs がパブリックインターネット経由で解決することを確認します。

### Microsoft Entra ID の問題
<a name="mcp-integration-troubleshooting-entra"></a>

MCP サーバーが認可サーバーとして Microsoft Entra ID を使用している場合、コネクタのセットアップ中に次のエラーがよく発生します。これらの問題は、VPC 接続を介して到達するパブリックネットワーク接続とプライベート MCP サーバーの両方に適用されます。
+ **`AADSTS9010010` – v2.0 エンドポイントはリソースパラメータを拒否します** – Amazon Quick は、MCP 仕様 (RFC 8707) の要求に従って OAuth リクエストに`resource`パラメータを送信します。Entra ID v2.0 エンドポイントは、`resource`パラメータと`scope`値の両方を含むリクエストを拒否します。このエラーを解決するには、Entra ID v1.0 OAuth エンドポイントを使用するようにアプリ登録を設定し、アプリマニフェスト`2`で `accessTokenAcceptedVersion`を に設定します。
+ **`AADSTS90009` – アプリケーションがそれ自体のトークンをリクエスト**する – ユーザー認証 (認可コードフロー) を使用し、OAuth クライアントと MCP リソースが同じ Entra ID アプリケーションに解決されると、Entra ID はリクエストをブロックします。Amazon Quick 用のクライアントアプリと MCP サーバー用のリソースアプリの 2 つの異なるアプリ登録を作成します。この問題は、単一のアプリ登録が機能するサービス認証 (クライアント認証情報フロー) には影響しません。

前のセクションで説明されていない問題が発生した場合は、Amazon Quick コンソールまたは AWS サポートセンターから AWS サポートにお問い合わせください。

## 制限事項
<a name="mcp-integration-limitations"></a>

Amazon Quick で MCP 統合を使用する場合は、次の制限に注意してください。
+ MCP オペレーションのタイムアウトは 60 秒に固定されています。この制限を超えるオペレーションは、HTTP 424 エラーで自動的に失敗します。
+ VPC 接続を介して到達する MCP サーバーの場合、MCP サーバーで使用される OAuth エンドポイントは、パブリックインターネット経由で到達可能である必要があります。これは、ユーザー認証とサービス認証の両方に適用されます。プライベート OAuth プロバイダーはサポートされていません。
+ カスタム HTTP ヘッダーは MCP オペレーションではサポートされていません。標準システムヘッダーのみが送信されます。
+ ツールリストは、初回登録後も静的なままです。サーバー側のツールの変更を取得するには、統合を削除して再作成する必要があります。
+ Amazon Quick は、MCP サーバー接続ごとに最大 100 個のツールをサポートします。MCP サーバーが 100 個を超えるツールを公開する場合、最初の 100 個のみが登録されます。
+ Amazon Quick コールバック URI がサードパーティープロバイダーによって許可リストに登録されていない場合、コネクタの作成が失敗する可能性があります。
+ サーバー接続の問題により、再試行せずにすぐに障害が発生します。
+ ステップアップ認可はサポートされていません。MCP サーバーが最初の認可 ( を使用した HTTP 403`insufficient_scope`) 後に追加のスコープを必要とする場合は、接続全体を再認可する必要があります。増分アクセス許可のアップグレードは使用できません。
+ スコープ処理には以下の制限があります。
  + Amazon Quick は、サーバーの最初の 401 `WWW-Authenticate`チャレンジから `scope`パラメータを抽出しません。Amazon Quick は、代わりに保護されたリソースメタデータドキュメントからスコープを決定します。
  + メタデータでサポートされているスコープが指定されていない場合、Amazon Quick はデフォルトのスコープを省略するのではなく適用します。この動作により、デフォルトのスコープを認識しないサーバーで認証が失敗する可能性があります。
+ 自動クライアント登録では、動的クライアント登録 (DCR) のみがサポートされています。クライアント ID メタデータドキュメントはサポートされていません。
+ よく知られている URI 検出では、サーバーのルートパスのみが使用されます。パス固有のメタデータの場所 (パス挿入検出) はサポートされていません。この制限により、パス固有の URIs でのみメタデータを提供するサーバーの検出が妨げられる可能性があります。