Model Context Protocol (MCP) の統合

適切なアクセス権を持つ MCP サーバーエンドポイント。

必要に応じて、MCP サーバーの認証認証情報。詳細については、「MCP サーバーのセットアップと認証を準備する」を参照してください。

Amazon Quick Enterprise サブスクリプション。

プライベート MCP サーバーに接続する場合、MCP サーバーへのネットワークアクセスを持つアクティブな Amazon Quick VPC 接続。詳細については、「Amazon Quick Sight での VPC 接続の設定」を参照してください。

コネクタは検出を渡しますが、 で発行に失敗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 要件の詳細については、「モデルコンテキストプロトコル仕様」の「ツール」を参照してください。

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

VPC 接続が接続タイプのドロップダウンに表示されないか、選択した直後に MCP の作成が失敗する – プロビジョニングが完了する前に、VPC 接続がドロップダウンに表示されることがあります。MCP 統合を作成する前に、VPC 接続が Amazon Quick 管理ページで使用可能と表示されるまで待ちます。詳細については、「Amazon Quick Sight での VPC 接続の設定」を参照してください。

MCP サーバーのホスト名が解決できないため、MCP の作成は失敗します。Amazon Quick は MCP 統合にデフォルトの VPC DNS リゾルバーを使用しません。VPC 接続の DNS リゾルバーエンドポイントフィールドに、MCP サーバーのホスト名を解決できる Route 53 Resolver のインバウンドエンドポイント IP アドレスを入力する必要があります。この要件は、プライベートホスト名と、 AWS PrivateLink または Route 53 プライベートホストゾーンが前面にあるエンドポイントなど、VPC 内からプライベートアドレスに解決するパブリックホスト名の両方に適用されます。これらのリゾルバーエンドポイントがないと、MCP サーバーのホスト名を解決できず、統合の作成が失敗します。詳細については、「Amazon Quick Sight での VPC 接続の設定」を参照してください。

MCP サーバーが VPC 接続から到達できない – Amazon Quick から MCP サーバーへのトラフィックは、VPC 接続のセットアップ中に選択したサブネットから発信されます。ルートテーブル、ネットワーク ACLs、およびセキュリティグループが、これらのサブネットと MCP サーバーエンドポイント間のトラフィックを許可していることを確認します。一般的な VPC ネットワークガイダンスについては、「」を参照してくださいAmazon Quick Sight での VPC 接続の設定。

プライベート MCP サーバーを使用する場合、認証は失敗します – VPC 接続を介してプライベート MCP サーバーに接続する場合、MCP サーバーが使用する OAuth エンドポイントにパブリックインターネット経由でアクセスできる必要があります。これは、ユーザー認証 (認可エンドポイントとトークンエンドポイント) とサービス認証 (トークンエンドポイント) の両方に適用されます。プライベート OAuth プロバイダーはサポートされていません。MCP サーバーが保護されたリソースメタデータで返す OAuth URLs がパブリックインターネット経由で解決することを確認します。

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 つの異なるアプリ登録を作成します。この問題は、単一のアプリ登録が機能するサービス認証 (クライアント認証情報フロー) には影響しません。

MCP オペレーションのタイムアウトは 60 秒に固定されています。この制限を超えるオペレーションは、HTTP 424 エラーで自動的に失敗します。

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

カスタム HTTP ヘッダーは MCP オペレーションではサポートされていません。標準システムヘッダーのみが送信されます。

ツールリストは、初回登録後も静的なままです。サーバー側のツールの変更を取得するには、統合を削除して再作成する必要があります。

Amazon Quick Callback URI がサードパーティープロバイダーによって許可リストに登録されていない場合、コネクタの作成が失敗する可能性があります。

サーバー接続の問題により、再試行せずにすぐに障害が発生します。

ステップアップ認可はサポートされていません。MCP サーバーが最初の認可 ( を使用した HTTP 403insufficient_scope) 後に追加のスコープを必要とする場合は、接続全体を再認可する必要があります。増分アクセス許可のアップグレードは使用できません。

スコープ処理には以下の制限があります。

自動クライアント登録では、動的クライアント登録 (DCR) のみがサポートされています。クライアント ID メタデータドキュメントはサポートされていません。

よく知られている URI 検出では、サーバーのルートパスのみが使用されます。パス固有のメタデータの場所 (パス挿入検出) はサポートされていません。この制限により、パス固有の URIs でのみメタデータを提供するサーバーの検出が妨げられる可能性があります。