Integration des Model Context Protocol (MCP)

Ein MCP-Serverendpunkt mit entsprechendem Zugriff.

Authentifizierungsdaten für den MCP-Server, falls erforderlich. Weitere Informationen finden Sie unter Bereiten Sie die Einrichtung und Authentifizierung des MCP-Servers vor.

Ein Amazon Quick Enterprise-Abonnement.

Wenn Sie eine Verbindung zu einem privaten MCP-Server herstellen, eine aktive Amazon Quick VPC-Verbindung, die Netzwerkzugriff auf den MCP-Server hat. Weitere Informationen finden Sie unter Konfiguration von VPC-Verbindungen in Amazon Quick Sight.

Der Connector besteht die Erkennung, schlägt aber bei der Veröffentlichung Creation failed mit fehl. Dieser Fehler bedeutet normalerweise, dass eine oder mehrere Tooldefinitionen in der tools/list Antwort Ihres MCP-Servers einen ungültigen inputSchema Wert enthalten. Amazon Quick validiert jedes Tool während der Veröffentlichungsphase inputSchema anhand von JSON Schema Draft 7 oder höher.

Die häufigste Ursache ist die veraltete Draft 3-Syntax, bei required der sich ein boolescher Wert innerhalb einer Eigenschaftsdefinition befindet (z. B.). "required": true In JSON Schema Draft 7 und höher required muss sich ein Array von Eigenschaftsnamen im Schemastamm befinden, also gleichrangig von. properties

Aktualisieren Sie Ihre Tooldefinitionen, sodass sie das richtige Format verwenden, und stellen Sie Ihren MCP-Server erneut bereit. Löschen Sie nach der erneuten Bereitstellung den ausgefallenen Connector und erstellen Sie einen neuen, um die Erkennung und Veröffentlichung erneut auszulösen.

Das folgende Beispiel zeigt die falsche Draft 3-Syntax:

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

Das folgende Beispiel zeigt die korrekte Syntax von Draft 7:

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

Einige MCP-Framework-Bibliotheken und Codegeneratoren geben standardmäßig die Draft 3-Syntax aus. Suchen Sie in Ihrer Framework-Dokumentation nach der Option, mit der die JSON-Schema-Ausgabeversion ausgewählt wird. Sie können Ihre Schemas vor der Bereitstellung auch mit einem beliebigen JSON Schema Draft 7-Validator validieren. Weitere Informationen zu den inputSchema Anforderungen finden Sie unter Tools in der Model Context Protocol-Spezifikation.

Möglicherweise stellen Sie auch fest, dass die Konnektorerstellung zwei bis fünf Minuten lang hängen bleibt, bevor sie fehlschlägt. Die verstrichene Zeit spiegelt interne Wiederholungen während der Veröffentlichungsphase wider, kein Netzwerk-Timeout. Die Lösung ist dieselbe: Überprüfen Sie Ihre inputSchema Tooldefinitionen auf Konformität mit JSON Schema Draft 7.

Die VPC-Verbindung ist nicht in der Dropdownliste Verbindungstyp aufgeführt, oder die MCP-Erstellung schlägt unmittelbar nach der Auswahl fehl. Die VPC-Verbindung wird möglicherweise in der Dropdownliste angezeigt, bevor die Bereitstellung abgeschlossen ist. Warten Sie, bis die VPC-Verbindung auf der Amazon Quick Admin-Seite als verfügbar angezeigt wird, bevor Sie eine MCP-Integration dafür erstellen. Weitere Informationen finden Sie unter Konfiguration von VPC-Verbindungen in Amazon Quick Sight.

Die MCP-Erstellung schlägt fehl, weil der MCP-Server-Hostname nicht aufgelöst werden kann — Amazon Quick verwendet nicht den Standard-VPC-DNS-Resolver für MCP-Integrationen. Sie müssen das Feld DNS-Resolver-Endpunkte auf der VPC-Verbindung mit eingehenden Route 53 Resolver-Endpunkt-IP-Adressen auffüllen, die Ihren MCP-Server-Hostnamen auflösen können. Diese Anforderung gilt sowohl für private Hostnamen als auch für öffentliche Hostnamen, die Sie innerhalb der VPC in eine private Adresse auflösen möchten, z. B. für Endgeräte, denen eine private Hosting-Zone von Route 53 gegenübersteht, AWS PrivateLink oder für eine private gehostete Route 53-Zone. Ohne diese Resolver-Endpunkte kann der Hostname des MCP-Servers nicht aufgelöst werden und die Integrationserstellung schlägt fehl. Weitere Informationen finden Sie unter Konfiguration von VPC-Verbindungen in Amazon Quick Sight.

Der MCP-Server ist über die VPC-Verbindung nicht erreichbar — Der Datenverkehr von Amazon Quick zu Ihrem MCP-Server stammt aus den Subnetzen, die Sie bei der Einrichtung der VPC-Verbindung ausgewählt haben. Vergewissern Sie sich, dass Routing-Tabellen, Netzwerk-ACLs und Sicherheitsgruppen den Datenverkehr zwischen diesen Subnetzen und dem MCP-Serverendpunkt zulassen. Allgemeine Hinweise zu VPC-Netzwerken finden Sie unterKonfiguration von VPC-Verbindungen in Amazon Quick Sight.

Die Authentifizierung schlägt fehl, wenn Sie einen privaten MCP-Server verwenden — Wenn Sie über eine VPC-Verbindung eine Verbindung zu einem privaten MCP-Server herstellen, müssen die vom MCP-Server verwendeten OAuth-Endpunkte weiterhin über das öffentliche Internet erreichbar sein. Dies gilt sowohl für die Benutzerauthentifizierung (Autorisierung und Token-Endpunkte) als auch für die Dienstauthentifizierung (Token-Endpunkte). Private OAuth-Anbieter werden nicht unterstützt. Vergewissern Sie sich, dass die OAuth-URLs, die Ihr MCP-Server in seinen geschützten Ressourcenmetadaten zurückgibt, über das öffentliche Internet aufgelöst werden.

AADSTS9010010— Der v2.0-Endpunkt lehnt den Ressourcenparameter ab — Amazon Quick sendet einen resource Parameter für OAuth-Anfragen, wie es die MCP-Spezifikation (RFC 8707) vorschreibt. Der Entra ID v2.0-Endpunkt lehnt Anfragen ab, die sowohl einen Parameter als auch Werte enthalten. resource scope Um diesen Fehler zu beheben, konfigurieren Sie Ihre App-Registrierung so, dass sie die Entra ID v1.0 OAuth-Endpunkte verwendet, und legen Sie im App-Manifest den Wert auf fest. accessTokenAcceptedVersion 2

AADSTS90009— Die Anwendung fordert ein Token für sich selbst an — Wenn Sie die Benutzerauthentifizierung (Autorisierungscodefluss) verwenden und der OAuth-Client und die MCP-Ressource zu derselben Entra-ID-Anwendung aufgelöst werden, blockiert Entra ID die Anfrage. Erstellen Sie zwei separate App-Registrierungen: eine Client-App für Amazon Quick und eine Ressourcen-App für den MCP-Server. Dieses Problem hat keine Auswirkungen auf die Serviceauthentifizierung (Fluss der Kundenanmeldedaten), bei der eine einzige App-Registrierung funktioniert.

MCP-Operationen haben ein festes Zeitlimit von 60 Sekunden. Operationen, die dieses Limit überschreiten, schlagen automatisch mit einem HTTP 424-Fehler fehl.

Für MCP-Server, die Sie über eine VPC-Verbindung erreichen, müssen die vom MCP-Server verwendeten OAuth-Endpunkte über das öffentliche Internet erreichbar sein. Dies gilt sowohl für die Benutzerauthentifizierung als auch für die Dienstauthentifizierung. Private OAuth-Anbieter werden nicht unterstützt.

Benutzerdefinierte HTTP-Header werden in MCP-Vorgängen nicht unterstützt. Es werden nur Standard-System-Header übertragen.

Die Werkzeuglisten bleiben nach der ersten Registrierung statisch. Um serverseitige Tool-Änderungen zu übernehmen, müssen Sie die Integration löschen und neu erstellen.

Die Connector-Erstellung schlägt möglicherweise fehl, wenn der Amazon Quick Callback-URI von Drittanbietern nicht zugelassen ist.

Probleme mit der Serverkonnektivität führen zu einem sofortigen Ausfall ohne erneute Versuche.

Step-up Die Autorisierung wird nicht unterstützt. Wenn ein MCP-Server nach der ersten Autorisierung (HTTP 403 mitinsufficient_scope) weitere Bereiche benötigt, müssen Sie die gesamte Verbindung erneut autorisieren. Inkrementelle Berechtigungsupgrades sind nicht verfügbar.

Für die Verarbeitung von Bereichen gelten die folgenden Einschränkungen:

Für die automatische Clientregistrierung wird nur Dynamic Client Registration (DCR) unterstützt. Client-ID-Metadatendokumente werden nicht unterstützt.

Well-known Die URI-Erkennung verwendet nur den Stammverzeichnispfad des Servers. Path-specific Speicherorte von Metadaten (Erkennung durch Einfügen von Pfaden) werden nicht unterstützt. Diese Einschränkung kann die Erkennung von Servern verhindern, die Metadaten nur über pfadspezifische URIs bereitstellen.