Integrazione con Model Context Protocol (MCP)

Un endpoint server MCP con accesso appropriato.

Credenziali di autenticazione per il server MCP, se richieste. Per ulteriori informazioni, consulta Preparare la configurazione e l'autenticazione del server MCP.

Un abbonamento Amazon Quick Enterprise.

Se ti connetti a un server MCP privato, una connessione Amazon Quick VPC attiva con accesso di rete al server MCP. Per ulteriori informazioni, consulta Configurazione delle connessioni VPC in Amazon Quick Sight.

Il connettore viene rilevato ma non riesce a pubblicare con Creation failed: questo errore in genere indica che una o più definizioni di strumenti nella tools/list risposta del server MCP contengono un messaggio non inputSchema valido. Amazon Quick convalida ogni strumento inputSchema rispetto a JSON Schema Draft 7 o successivo durante la fase di pubblicazione.

La causa più comune è la sintassi obsoleta di Draft 3, in cui required è presente un valore booleano all'interno di una definizione di proprietà (ad esempio,). "required": true In JSON Schema Draft 7 e versioni successive, required deve esserci una matrice di nomi di proprietà nella radice dello schema, come fratello di. properties

Aggiorna le definizioni degli strumenti per utilizzare il formato corretto e ridistribuisci il server MCP. Dopo la ridistribuzione, eliminate il connettore guasto e createne uno nuovo per riattivare l'individuazione e la pubblicazione.

L'esempio seguente mostra la sintassi errata di Draft 3:

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

L'esempio seguente mostra la sintassi corretta di Draft 7:

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

Alcune librerie di framework MCP e generatori di codice emettono la sintassi Draft 3 per impostazione predefinita. Consulta la documentazione del tuo framework per l'opzione che seleziona la versione di output dello schema JSON. Puoi anche convalidare i tuoi schemi con qualsiasi validatore JSON Schema Draft 7 prima della distribuzione. Per ulteriori informazioni sui inputSchema requisiti, consulta Tools nella specifica Model Context Protocol.

È inoltre possibile notare che la creazione del connettore si blocca da due a cinque minuti prima di fallire. Il tempo trascorso riflette i tentativi interni durante la fase di pubblicazione, non un timeout di rete. La soluzione è la stessa: controllate le inputSchema definizioni degli strumenti per la conformità a JSON Schema Draft 7.

La connessione VPC non è elencata nel menu a discesa Tipo di connessione oppure la creazione dell'MCP non riesce immediatamente dopo averla selezionata: la connessione VPC potrebbe apparire nel menu a discesa prima del completamento del provisioning. Attendi che la connessione VPC risulti disponibile nella pagina di amministrazione di Amazon Quick prima di creare un'integrazione MCP con essa. Per ulteriori informazioni, consulta Configurazione delle connessioni VPC in Amazon Quick Sight.

La creazione di MCP non riesce perché il nome host del server MCP non può essere risolto: Amazon Quick non utilizza il resolver DNS VPC predefinito per le integrazioni MCP. È necessario compilare il campo endpoint DNS resolver sulla connessione VPC con gli indirizzi IP degli endpoint in ingresso di Route 53 Resolver in grado di risolvere il nome host del server MCP. Questo requisito si applica sia ai nomi host privati che ai nomi host pubblici che si desidera risolvere in un indirizzo privato dall'interno del VPC, ad esempio gli endpoint fronted by o una zona ospitata privata AWS PrivateLink Route 53. Senza questi endpoint resolver, il nome host del server MCP non può essere risolto e la creazione dell'integrazione non riesce. Per ulteriori informazioni, consulta Configurazione delle connessioni VPC in Amazon Quick Sight.

Il server MCP non è raggiungibile dalla connessione VPC: il traffico da Amazon Quick al tuo server MCP proviene dalle sottoreti selezionate durante la configurazione della connessione VPC. Verifica che le tabelle di routing, gli ACL di rete e i gruppi di sicurezza consentano il traffico tra tali sottoreti e l'endpoint del server MCP. Per indicazioni generali sulle reti VPC, vedere. Configurazione delle connessioni VPC in Amazon Quick Sight

L'autenticazione non riesce quando si utilizza un server MCP privato: quando ci si connette a un server MCP privato tramite una connessione VPC, gli endpoint OAuth utilizzati dal server MCP devono essere ancora raggiungibili sulla rete Internet pubblica. Ciò vale sia per l'autenticazione degli utenti (endpoint di autorizzazione e token) che per l'autenticazione dei servizi (endpoint con token). I provider OAuth privati non sono supportati. Verifica che gli URL OAuth restituiti dal server MCP nei metadati delle risorse protette vengano risolti sulla rete Internet pubblica.

AADSTS9010010— l'endpoint v2.0 rifiuta il parametro resource — Amazon Quick invia un resource parametro sulle richieste OAuth come richiesto dalla specifica MCP (RFC 8707). L'endpoint Entra ID v2.0 rifiuta le richieste che includono sia un parametro che dei valori. resource scope Per risolvere questo errore, configurate la registrazione dell'app in modo che utilizzi gli endpoint Entra ID v1.0 OAuth e impostatela nel manifesto dell'app. accessTokenAcceptedVersion 2

AADSTS90009— l'applicazione richiede un token per sé — Quando si utilizza l'autenticazione utente (flusso del codice di autorizzazione) e il client OAuth e la risorsa MCP si risolvono nella stessa applicazione Entra ID, Entra ID blocca la richiesta. Crea due registrazioni di app separate: un'app client per Amazon Quick e un'app di risorse per il server MCP. Questo problema non influisce sull'autenticazione del servizio (flusso delle credenziali del client), in cui funziona la registrazione di una singola app.

Le operazioni MCP hanno un timeout fisso di 60 secondi. Le operazioni che superano questo limite falliscono automaticamente con un errore HTTP 424.

Per i server MCP raggiungibili tramite una connessione VPC, gli endpoint OAuth utilizzati dal server MCP devono essere raggiungibili tramite la rete Internet pubblica. Questo vale sia per l'autenticazione degli utenti che per l'autenticazione dei servizi. I provider OAuth privati non sono supportati.

Le intestazioni HTTP personalizzate non sono supportate nelle operazioni MCP. Vengono trasmesse solo le intestazioni di sistema standard.

Gli elenchi degli strumenti rimangono statici dopo la registrazione iniziale. Per rilevare le modifiche apportate agli strumenti sul lato server, è necessario eliminare l'integrazione e ricrearla.

La creazione del connettore potrebbe non riuscire se l'URI di callback di Amazon Quick non è consentito da provider di terze parti.

I problemi di connettività del server provocano un errore immediato senza tentativi di riprova.

Step-up l'autorizzazione non è supportata. Se un server MCP richiede ambiti aggiuntivi dopo l'autorizzazione iniziale (HTTP 403 coninsufficient_scope), è necessario autorizzare nuovamente l'intera connessione. Gli aggiornamenti incrementali delle autorizzazioni non sono disponibili.

La gestione dell'ambito presenta le seguenti limitazioni:

Per la registrazione automatica dei client è supportata solo la registrazione dinamica del client (DCR). I documenti con metadati Client ID non sono supportati.

Well-known L'URI discovery utilizza solo il percorso principale del server. Path-specific le posizioni dei metadati (path-insertion discovery) non sono supportate. Questa limitazione potrebbe impedire l'individuazione di server che forniscono metadati solo su URI specifici del percorso.