Questa pagina si applica ad Apigee e ad Apigee hybrid.
Visualizza la documentazione di
Apigee Edge.
Questa pagina descrive come risolvere i problemi relativi al deployment dei proxy di rilevamento MCP. Puoi utilizzare questa pagina per comprendere il ciclo di vita del provisioning asincrono dei deployment MCP, risolvere i codici di errore e verificare la connettività di runtime.
Informazioni sul deployment di MCP
Il deployment di un proxy di rilevamento MCP è un processo asincrono in più passaggi che garantisce che la configurazione venga propagata completamente nell'infrastruttura Apigee e Google Cloud prima del completamento del deployment del proxy.
Durante l'esecuzione di questi passaggi di provisioning downstream, l'interfaccia utente mostra il proxy in stato di Provisioning. Al termine del processo, lo stato cambia in Deployment eseguito. Questo stato conferma che è stato eseguito il provisioning completo di tutti i componenti downstream e che il proxy è pronto per gestire il traffico.
Risoluzione dei problemi
Le sezioni seguenti descrivono gli errori e i problemi noti che potresti riscontrare durante l'utilizzo di MCP in Apigee.
Il backend non riceve un argomento dello strumento nella posizione prevista
Problema: un backend legge un argomento dello strumento da una posizione della richiesta, ovvero la stringa di query, un'intestazione o un cookie, ma la specifica OpenAPI dichiara il parametro in in una posizione diversa, quindi l'argomento arriva in un'altra posizione nella richiesta del backend. La chiamata non va a buon fine o si comporta come se l'argomento non fosse presente.
Sintomi: la richiesta tools/call va a buon fine a livello di MCP e il client MCP fornisce l'argomento, ma il backend risponde come se il valore non fosse presente, ad esempio un 400 per un valore obbligatorio o un valore predefinito applicato al posto del valore inviato.
Causa: il parametro è dichiarato in: header o in: cookie nella specifica OpenAPI, quindi Apigee invia il suo valore come intestazione della richiesta o nell'intestazione Cookie anziché nella stringa di query. Un backend che legge il valore solo dalla stringa di query non lo vede. Consulta
Posizionamento
degli argomenti dello strumento nella richiesta di backend.
Risoluzione: decidi a quale categoria appartiene il valore e fai in modo che la specifica e il backend corrispondano:
- Per mantenere il valore nella stringa di query, dichiara il parametro
in: query. - Per inviarlo come intestazione o cookie, lascia la dichiarazione così com'è e leggi il valore da quella posizione nel backend.
Il backend smette di ricevere un cookie trasportato dalla richiesta del client MCP
Problema: un cookie che arriva nella richiesta HTTP effettuata dal client MCP, ad esempio un cookie di sessione di un client basato su browser, non raggiunge più il backend in alcune chiamate allo strumento.
Sintomi: il backend si comporta come se il chiamante non fosse autenticato o non fosse in sessione e il comportamento è incoerente: la stessa operazione funziona su alcune chiamate e non su altre.
Causa: l'operazione dichiara uno o più parametri in: cookie
e le chiamate interessate ne hanno fornito almeno uno. L'intestazione Cookie viene riscritta nel suo complesso anziché essere aggiunta, quindi in queste chiamate contiene solo i parametri dei cookie dichiarati e tutti gli altri cookie vengono eliminati. Le chiamate che non hanno fornito nessuno dei parametri dei cookie trasmettono l'intestazione invariata, motivo per cui solo alcune chiamate non vanno a buon fine. Consulta
Cookie
nella richiesta al backend.
Risoluzione: dichiara ogni cookie necessario al backend come parametro in: cookie in ogni operazione che lo richiede, in modo che il suo valore venga sempre fornito dalla chiamata allo strumento anziché essere ereditato dalla richiesta del client. Non esiste un'impostazione che conservi un cookie non dichiarato.
Codici di stato della risposta di errore per le chiamate agli strumenti e i metadati
Gli endpoint MCP di Apigee restituiscono codici di stato HTTP che seguono la specifica Model Context Protocol (MCP) e gli standard OAuth correlati. Comprendere questo comportamento ti aiuta a gestire correttamente gli errori nel tuo client MCP o agente AI.
La tabella seguente riassume i codici di stato restituiti dagli endpoint MCP di Apigee:
| Scenario | Codice di stato HTTP | Corpo della risposta |
|---|---|---|
L'esecuzione di uno strumento non riesce su tools/call (ad esempio, l'API di backend restituisce un errore 4xx o 5xx, come un errore di convalida o un campo obbligatorio mancante). |
200 OK |
Un CallToolResult con result.isError impostato su
true e i dettagli dell'errore in content. In questo modo, il client MCP e l'agente LLM possono leggere l'errore ed eseguire il recupero (ad esempio, richiedendo nuovamente l'input mancante e riprovando) anziché terminare la sessione. |
I metadati della risorsa protetta OAuth (PRM) non sono configurati o non possono essere trovati in /.well-known/oauth-protected-resource/mcp. |
404 Not Found |
Indica che non sono disponibili metadati delle risorse protette nella località richiesta. |
| Il token di accesso è mancante, non valido o scaduto. | 401 Unauthorized |
Include una verifica WWW-Authenticate per guidare il flusso di discovery OAuth. |
| L'ambito del token di accesso è insufficiente. | 403 Forbidden |
Include una verifica WWW-Authenticate per gestire il flusso di autorizzazione step-up. |
Esempio: corpo della risposta di errore di esecuzione dello strumento
Quando una chiamata allo strumento non va a buon fine, Apigee MCP restituisce HTTP 200 OK e segnala l'errore nell'oggetto JSON-RPC result, con isError impostato su true. L'errore originale restituito dal backend viene conservato: il corpo della risposta del backend viene inserito letteralmente (come stringa) in result.content[].text. Ad esempio, se il backend restituisce HTTP 404 con il corpo {"error":"User 42 not found"}, la risposta MCP è:
{ "jsonrpc": "2.0", "id": 1, "result": { "content": [ { "type": "text", "text": "{\"error\":\"User 42 not found\"}" } ], "isError": true } }
id corrisponde a id della tua richiesta tools/call.
Se il backend non restituisce un corpo della risposta, text contiene un riepilogo generato, ad esempio Operation failed (HTTP 500).
Il tuo client MCP deve ispezionare result.isError (non il codice di stato HTTP) per rilevare una chiamata allo strumento non riuscita. Se il codice client prevede specificamente uno stato HTTP 4xx o 5xx per segnalare un errore di esecuzione dello strumento, non rileva l'errore, perché la risposta è HTTP 200 OK. Aggiorna questi client in modo che leggano result.isError e l'array content.
Gli errori a livello di protocollo (ad esempio, una richiesta JSON-RPC non corretta) sono distinti dagli errori di esecuzione dello strumento: continuano a essere restituiti nell'oggetto JSON-RPC error (ad esempio, {"jsonrpc": "2.0", "error": {"code": -32700, ...}}) anziché in result.isError.
Suggerimento: i client MCP conformi agli standard gestiscono questi codici di stato tramite la logica predefinita, pertanto non sono necessarie modifiche. Se in precedenza hai aggiunto una soluzione alternativa lato client per gestire i codici di stato non standard, ad esempio l'analisi di un corpo della risposta non 2xx per gli errori tools/call o il trattamento di una risposta 500 dall'endpoint PRM come "metadati non configurati", ti consigliamo di rimuoverla. In caso contrario, il client potrebbe continuare a utilizzare la logica di gestione obsoleta anziché elaborare normalmente i codici di stato corretti.
Policy CORS per le chiamate MCP basate su browser
Una policy di condivisione delle risorse tra origini (CORS) è necessaria quando le chiamate MCP di Apigee vengono effettuate direttamente da un browser (ad esempio, quando l'inspector MCP utilizza l'impostazione "Diretto" anziché "Tramite proxy"). Il modello di proxy di rilevamento MCP include per impostazione predefinita la policy CORS di Apigee nel PreFlow della richiesta del proxy endpoint del bundle proxy per abilitare le chiamate basate su browser.
Se riscontri problemi relativi a CORS quando effettui chiamate direttamente da un browser, potresti dover modificare le impostazioni della policy CORS nel PreFlow della richiesta dell'endpoint proxy del bundle proxy di rilevamento MCP.
Errore di analisi JSON durante l'invio della richiesta all'endpoint MCP
Quando invii una richiesta al tuo endpoint MCP, potresti ricevere un messaggio di errore simile al seguente (o con un codice di errore e un messaggio diversi):
{
"error": {
"code": -32700,
"message": "JSON parse error"
},
"id": null,
"jsonrpc": "2.0"
}In questo caso, ti consigliamo di verificare le seguenti informazioni:
- Hai inserito l'URL dell'endpoint MCP corretto.
- La tua richiesta è formattata correttamente.
- Stai accedendo a un metodo supportato.
- Hai attivato e configurato il proxy di rilevamento MCP in una regione supportata. Per un elenco delle regioni che potrebbero avere limiti di capacità, consulta Errori di deployment.
Errori di deployment
Se il deployment del proxy di rilevamento MCP non va a buon fine con lo stato Non riuscito nella UI, controlla il messaggio di errore per maggiori dettagli. Gli errori più comuni includono:
- Configurazione di rete non riuscita o Schema non supportato in OAS: questi errori in genere indicano un problema con la specifica OpenAPI. Assicurati che la specifica sia valida e utilizzi una versione supportata.
- Limiti di capacità della regione (solo Apigee): se visualizzi un errore relativo a un errore di provisioning del bilanciatore del carico o se lo stato del provisioning non cambia mai in Deployment eseguito, potrebbe essere dovuto a limiti temporanei di capacità dell'infrastruttura in una delle seguenti regioni:
asia-east2asia-northeast3asia-southeast2australia-southeast1europe-central2europe-west12europe-west9me-central2us-central2
Per risolvere l'errore, prova a eseguire il deployment del proxy in un ambiente in un'altra regione. Questa modalità di errore non si applica ad Apigee hybrid, in cui l'infrastruttura di runtime è il tuo cluster.
- MCP non abilitato nel cluster (solo Apigee hybrid): se il deployment del proxy MCP rimane nello stato Provisioning a tempo indeterminato e non raggiunge mai lo stato Deployment eseguito, verifica che MCP sia abilitato nel cluster. Consulta la sezione Diagnostica lato cluster di seguito.
Diagnostica lato cluster (solo Apigee hybrid)
Poiché il piano dati MCP di Apigee hybrid viene eseguito all'interno del tuo cluster Kubernetes,
le modalità di errore all'interno del cluster vengono diagnosticate con kubectl sul cluster.
Segui l'elenco di controllo diagnostico riportato di seguito nell'ordine indicato.
Passaggio 1: verifica che MCP sia abilitato nel cluster
MCP viene eseguito il deployment come risorsa personalizzata ApigeeDeployment (gestita dall'operatore Apigee), non come Deployment Kubernetes standard. Controlla la piattaforma di connettività mobile ApigeeDeployment:
kubectl -n APIGEE_NAMESPACE get apigeedeployment -l app=apigee-mcp-server
Output previsto (i nomi delle risorse includono un suffisso derivato dall'organizzazione, mostrato qui come ORG_CR_SUFFIX):
NAME STATE NESTEDSTATE AGE apigee-mcp-server-default-ORG_CR_SUFFIX running 1h
Se il comando restituisce No resources found in APIGEE_NAMESPACE namespace.,
MCP non è abilitato. Torna ad Attiva MCP in Apigee Hybrid e verifica che enableMcpServer: true sia impostata come chiave di primo livello in overrides.yaml e di aver eseguito l'upgrade della release Helm apigee-operator prima della release apigee-org. Consulta il passaggio 3 e il passaggio 4 della procedura di attivazione per i comandi helm corretti.
Passaggio 2: verifica che i pod MCP siano in esecuzione
kubectl -n APIGEE_NAMESPACE get pods -l app=apigee-mcp-server
Output previsto (i suffissi dei pod saranno diversi):
NAME READY STATUS RESTARTS AGE apigee-mcp-server-default-ORG_CR_SUFFIX-1170-abcd1234 2/2 Running 0 1h apigee-mcp-server-default-ORG_CR_SUFFIX-1170-efgh5678 2/2 Running 0 1h
I nomi dei pod seguono il modello apigee-mcp-server-default-ORG_CR_SUFFIX-REV-POD_HASH, dove REV è la revisione della release ibrida di quattro cifre (ad esempio, 1170 per la versione ibrida 1.17.0) e POD_HASH è un suffisso alfanumerico di otto caratteri che varia per ogni pod.
Ogni pod deve mostrare 2/2 nella colonna READY e
Running nella colonna STATUS. Se i pod non sono Running,
kubectl -n APIGEE_NAMESPACE describe pod POD_NAME mostra
il motivo. Le cause più comuni sono errori di pull delle immagini (verifica il traffico in uscita dal cluster al registry delle immagini configurato nel tuo overrides.yaml) e spazio di CPU o memoria insufficiente (aumenta mcpServer.resources.requests in overrides.yaml).
Passaggio 3: controlla lo stato di pull della configurazione del sidecar
Il container sidecar apigee-mcp-server-config in ogni pod MCP estrae periodicamente la configurazione MCP dal control plane di Apigee. Ogni pull recupera il riferimento alla configurazione corrente da apigee.googleapis.com, quindi recupera il bundle di configurazione di riferimento da Cloud Storage. Il piano dati MCP inizia a gestire il traffico degli strumenti MCP su https://mcp.apigee.internal/mcp una volta che un pull viene completato correttamente con una configurazione valida.
Prima del primo pull riuscito con una configurazione valida (perché non è ancora stato eseguito il deployment di un proxy di rilevamento MCP per la tua organizzazione o perché il sidecar non riesce a raggiungere il control plane), i pod MCP rimangono Ready, ma le richieste a https://mcp.apigee.internal/mcp non vanno a buon fine con l'errore connessione rifiutata.
Ispeziona i log del sidecar per determinare in quale caso ti trovi:
kubectl -n APIGEE_NAMESPACE logs -l app=apigee-mcp-server -c apigee-mcp-server-config --tail=100
- Riga
inforipetuta che indica l'assenza di configurazione MCP dal control plane: Il control plane Apigee ha restituito una risposta positiva, ma non è stato ancora eseguito il deployment di un proxy di rilevamento MCP per la tua organizzazione. Questo è lo stato stabile previsto durante l'onboarding. Per passare il piano dati MCP allo stato di pubblicazione, esegui il deployment di un proxy di rilevamento MCP in base alla guida rapida di MCP.{"level":"info","ts":1787582542.68,"caller":"mcpsidecar/sidecar.go:397","msg":"mcpsidecar: no MCP config from CP yet; skipping tick, pod stays Ready via seed","org":"YOUR_ORG","mcp_server_id":"default"} - Linea
errorcon un contatoreconsecutive_failures: I log sidecar sono JSON strutturati. Quando vedi{"level":"error","ts":1787613247.74,"caller":"mcpsidecar/sidecar.go:...","msg":"mcpsidecar: ...","org":"YOUR_ORG","mcp_server_id":"default","consecutive_failures":185,"error":"<wrapped error text>"}"level":"error"con un contatoreconsecutive_failuresin aumento, significa che il sidecar non è riuscito a completare un pull della configurazione. Il sidecar riprova automaticamente con backoff e reimposta il contatore su 0 al successivo pull riuscito.Cause principali comuni da verificare quando questo contatore continua ad aumentare:
- Il account di servizio Google Cloud
apigee-watchernon è presente nell'elencowatcher_identitiesdella risorsacontrolPlaneAccessdella tua organizzazione Apigee. Consulta il Passaggio 2: concedi all'identità watcher l'accesso alla configurazione MCP sul control plane nella procedura di abilitazione per aggiungere la concessione e verificare che sia stata applicata. - Il traffico in uscita dal cluster verso
apigee.googleapis.comostorage.googleapis.comè bloccato. Entrambi gli endpoint devono essere raggiungibili dai pod MCP (consulta i requisiti di rete in uscita nella procedura di attivazione). - Il account di servizio
apigee-watchernon può ottenere token di accesso Google Cloud da questo cluster. Se anche i componenti Apigee hybrid esistenti nello stesso spazio dei nomi segnalano errori di autenticazione, risolvi prima il problema di autenticazione condiviso. - Un errore temporaneo del control plane Apigee o di Cloud Storage. Se il contatore continua ad aumentare per un periodo prolungato dopo aver escluso le cause precedenti, contatta l'assistenza Apigee.
- Il account di servizio Google Cloud
Passaggio 4: verifica che gli hostAliases del processore di messaggi siano stati inseriti
Quando attivi MCP, l'operatore Apigee inserisce una voce hostAliases nella specifica del pod del processore di messaggi (MP). La voce contiene un IP (il ClusterIP del servizio MCP) e due nomi host: mcp.apigee.internal e ORG_NAME.mcp.apigee.internal in minuscolo. Verifica che l'inserimento sia andato a buon fine:
kubectl -n APIGEE_NAMESPACE get pods -l app=apigee-runtime \ -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.hostAliases}{"\n"}{end}'
Ogni pod MP elencato deve avere una voce hostAliases contenente sia mcp.apigee.internal sia ORG_NAME.mcp.apigee.internal in minuscolo che puntano al ClusterIP del servizio MCP. Qualsiasi pod MP che mostra una voce vuota o mancante è stato creato prima dell'abilitazione di MCP. Elimina il pod MP interessato in modo che il controller ApigeeDeployment lo ricrei dalla specifica del pod attuale (che include la voce hostAliases inserita):
kubectl -n APIGEE_NAMESPACE delete pod -l app=apigee-runtime
Passaggio 5: verifica end-to-end
Per un test end-to-end che invia una richiesta MCP initialize effettiva tramite il piano dati MCP, esegui il deployment di un proxy di rilevamento MCP e segui la guida rapida di MCP.
Prima del deployment di un proxy di rilevamento MCP per la tua organizzazione, le richieste a https://mcp.apigee.internal/mcp non vanno a buon fine con l'errore connessione rifiutata, indipendentemente dal fatto che il processore di messaggi possa raggiungere i pod MCP (vedi il passaggio 3).
Passaggio 6: controlla mTLS nel gateway in entrata (se configurato)
Questo passaggio si applica solo se hai configurato virtualhosts[].mcpMtls per un gruppo di ambienti (Apigee hybrid 1.17.4 e versioni successive). Il sintomo tipico di un problema mTLS è che le chiamate dello strumento MCP a un gruppo di ambienti non vanno a buon fine (di solito 503 Service Unavailable), mentre le chiamate ad altri gruppi di ambienti vanno a buon fine, perché il piano dati MCP mantiene la configurazione del certificato per gruppo di ambienti.
- Verifica che l'operatore abbia accettato il campo. La risorsa di routing del gruppo di ambienti deve contenere il blocco
mcpMtls: Una seconda colonna vuota, diversi minuti dopo l'upgrade dikubectl -n APIGEE_NAMESPACE get apigeeroutes -l envGroupId=ENV_GROUP_NAME \ -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.mcpMtls}{"\n"}{end}'
apigee-virtualhost, di solito significa che le definizioni delle risorse personalizzate di Apigee nel cluster sono precedenti a1.17.4e non dichiaranomcpMtls, quindi il server API ha eliminato il campo. (Meno spesso, non è stato eseguito l'upgrade del graficoapigee-orgche fornisce l'immagine del watcher a1.17.4.) Questo accade quando un upgrade ha eseguitohelm upgradeper il grafico dell'operatore, ma ha saltato il passaggio Installa le CRD Apigee aggiornate. Il piano dati MCP utilizza ancora TLS unidirezionale e il gateway in entrata in modalitàMUTUALlo rifiuta; le stesse CRD obsolete impediscono inoltre la segnalazione dei problemi diAIS_MCP_MTLS_*nel passaggio successivo. Controlla e correggi con: Eseguikubectl get crd apigeeroutes.apigee.cloud.google.com -o yaml | grep -c mcpMtls # 0 means the CRDs are stale kubectl apply -k apigee-operator/etc/crds/default/ --server-side --force-conflicts --validate=false
kubectl applydalla directory dei chart Helm, quindi esegui di nuovo l'upgrade diapigee-virtualhostper il gruppo di ambienti. - Controlla se sono presenti problemi relativi ai certificati segnalati dal cluster. Il watcher analizza i secret configurati e crea un
ApigeeIssueper ogni problema: Il campokubectl -n APIGEE_NAMESPACE get apigeeissues -l 'ais-reason in (AIS_MCP_MTLS_CLIENT_CERT_INVALID,AIS_MCP_MTLS_CLIENT_CERT_EXPIRY,AIS_MCP_MTLS_CA_CERT_INVALID,AIS_MCP_MTLS_CA_CERT_EXPIRY)' kubectl -n APIGEE_NAMESPACE describe apigeeissue ISSUE_NAME
Spec.Detailsindica il nome del secret e dellaApigeeRouteConfig(denominataORG_NAME-ENV_GROUP_NAME) a cui appartiene il problema, nonché il difetto specifico.
I problemi vengono ritirati automaticamente alla scansione successiva dopo la correzione del secret.Motivo Gravità Significato Correggi AIS_MCP_MTLS_CLIENT_CERT_INVALIDERRORIl secret del certificato client non esiste ( secret not found), manca una vocecertokey, una voce è vuota o non è PEM, il certificato e la chiave non corrispondono o l'utilizzo della chiave estesa del certificato ometteclientAuth. Il piano dati MCP non lo carica.Crea o correggi il secret (opzione 2) o i file seguiti da helm upgrade(opzione 1); se il problema è l'utilizzo della chiave estesa, emetti nuovamente il certificato conclientAuth.AIS_MCP_MTLS_CLIENT_CERT_EXPIRYWARNINGentro 14 giorni dalla scadenza;ERRORdopoIl certificato client sta per scadere o è scaduto. Viene comunque presentato un certificato scaduto; il gateway in entrata rifiuta l'handshake. Ruota il certificato come descritto in Ruota i certificati. AIS_MCP_MTLS_CA_CERT_INVALIDERRORIl secret -cacertnon esiste (secret not found; consslSecretlo crei tu), manca la vocecacert, la voce non è PEM, un blocco non è un certificato o un certificato al suo interno non è un certificato CA.Se necessario, crea il secret e inserisci il certificato CA (o la catena) che ha firmato il certificato del gateway in entrata nella voce cacert.AIS_MCP_MTLS_CA_CERT_EXPIRYWARNINGentro 14 giorni dalla scadenza;ERRORdopoUn certificato CA nel secret -cacertsta per scadere o è scaduto. Dopo la scadenza, il piano dati MCP non considera più attendibile la catena di certificati del gateway in entrata.Sostituisci il certificato CA nel Secret -cacertprima che scada, insieme al certificato del gateway in entrata se anche questo viene riemesso. - Leggi i messaggi mTLS del sidecar. Il container
apigee-mcp-server-configregistra una rigaerrorogni volta che non può applicare i certificati di un gruppo di ambienti. In genere, ogni riga include campi comeenv_group,secret(e un campo trust-Secret quando la convalida della catena è attiva), un codicereasone il testo dell'errore aggregato. Filtra in base al valore del codicereason, che è l'identificatore stabile; non fare affidamento sugli altri nomi dei campi: Cerca nell'intero log anziché in una finestra recente: un secret difettoso viene segnalato quando il sidecar lo rileva per la prima volta (e di nuovo quando cambia), non a ogni aggiornamento.kubectl -n APIGEE_NAMESPACE logs -l app=apigee-mcp-server -c apigee-mcp-server-config \ | grep MCP_MTLS_
I seguenti codici motivo sono stabili per la release corrente. Se visualizzi un codice non presente nell'elenco, contatta l'assistenza clienti Google Cloud.
Ad eccezione direasonSignificato Azione MCP_MTLS_SECRET_NOT_FOUNDUn secret a cui viene fatto riferimento non esiste nello spazio dei nomi Apigee. Il testo errorne indica il nome e se si tratta del secret del client o del trust.Crea il secret con il nome esatto (ricorda il suffisso -cacertper la CA di attendibilità). Il sidecar rileva autonomamente il nuovo secret.MCP_MTLS_MATERIAL_UNUSABLEIl secret esiste, ma i suoi contenuti vengono rifiutati: una chiave dati mancante o vuota, contenuti non PEM, un certificato e una chiave non accoppiati, un certificato client senza clientAutho un secret di attendibilità senza certificato CA. Lo stesso difetto viene segnalato comeApigeeIssue(passaggio precedente).Correggi i contenuti del secret. La modifica del secret attiva un nuovo tentativo. MCP_MTLS_SECRET_READ_FAILED,MCP_MTLS_SECRET_WATCH_FAILED,MCP_MTLS_SECRET_ACCESS_FAILEDIl sidecar non è riuscito a leggere o monitorare i secret tramite l'API Kubernetes (server API non disponibile o il ruolo MCP ha perso l'autorizzazione secrets). Una rigaMCP_MTLS_SECRET_READ_FAILEDinclude il contesto dei nuovi tentativi e il sidecar riprova con backoff; le altre due segnalano lo stato del monitoraggio del secret del sidecar eMCP_MTLS_SECRET_READER_RECOVEREDviene registrato quando l'accesso viene restituito.Verifica che il ruolo MCP conceda ancora get,list,watchsusecrets(vedi Confine di attendibilità) e che altri componenti nello spazio dei nomi possano raggiungere il server API. Il nome del ruolo termina con un suffisso generato, quindi trovalo conkubectl -n APIGEE_NAMESPACE get role | grep apigee-mcp-server.MCP_MTLS_PUBLISH_FAILEDI certificati erano validi, ma non è stato possibile scriverli nel volume in memoria del pod MCP. Il sidecar riprova con backoff e registra MCP_MTLS_PUBLISH_RECOVEREDquando la scrittura va a buon fine.Questo non è previsto durante il normale funzionamento. Se si ripete, raccogli i log del sidecar e contatta l'assistenza clienti Google Cloud. MCP_MTLS_UNKEYABLE_ENV_GROUPIl gruppo di ambienti ha mcpMtlsconfigurato, ma il valore dell'etichettaenvGroupIdnon è un elemento di percorso valido, pertanto il piano dati MCP gestisce il gruppo tramite TLS unidirezionale e un gateway in entrata in modalitàMUTUALrifiuta le chiamate allo strumento. Le regole delle etichette Kubernetes normalmente impediscono questi valori, quindi un gruppo in questo stato proviene da una risorsa di routing applicata direttamente al cluster. NessunApigeeIssuelo segnala.Verifica che la risorsa di routing abbia un'etichetta valida: kubectl -n APIGEE_NAMESPACE get apigeeroutes --show-labels. Esegui nuovamente l'upgrade diapigee-virtualhostper il gruppo di ambienti in modo che la risorsa venga ricreata dal grafico.MCP_MTLS_SAN_WITHOUT_CHAIN_VALIDATIONIl gruppo di ambienti imposta disableChainValidation: trueedisableSanValidation: falseinsieme. La corrispondenza SAN avviene all'interno del set di validazione configurato dalla convalida della catena, quindi se la convalida della catena è disattivata non esiste alcun elemento con cui trovare una corrispondenza e l'impostazione viene ignorata. Il grafico rifiuta questo accoppiamento, quindi un gruppo in questo stato proviene da una risorsa personalizzata applicata direttamente al cluster.Rimuovi disableSanValidationdal bloccomcpMtlsdel gruppo di ambienti o imposta nuovamentedisableChainValidationsufalsee fornisci una CA attendibile (vedidisableSanValidation).MCP_MTLS_CONFLICTING_CONFIGDue risorse di routing nello stesso gruppo di ambienti contengono blocchi mcpMtlsdiversi, pertanto quello utilizzato dal piano dati MCP dipende dall'ordine di elaborazione delle route. Il gruppo può finire per presentare un certificato client diverso da quello configurato e nessun elemento a valle registra quale blocco ha vinto.Esegui di nuovo l'upgrade di apigee-virtualhostper il gruppo di ambiente, quindi verifica che i blocchi corrispondano al comandoget apigeeroutesnel passaggio 1. Ogni route di un gruppo deriva dalla singola vocevirtualhosts[]del gruppo, quindi un disaccordo indica che le risorse sono state applicate direttamente al cluster o che un upgrade precedente è stato propagato solo parzialmente.MCP_MTLS_UNKEYABLE_ENV_GROUP, che riduce il gruppo di ambienti a TLS unidirezionale, il gruppo di ambienti continua a utilizzare gli ultimi certificati caricati correttamente dal sidecar. Se non ne ha mai caricati (prima attivazione), le chiamate allo strumento MCP a quel gruppo di ambienti non vanno a buon fine finché il problema non viene risolto; gli altri gruppi di ambienti non sono interessati. Dopo la correzione, non è necessario riavviare il pod.I restanti codici
MCP_MTLS_non richiedono alcuna azione.MCP_MTLS_CHAIN_VALIDATION_DISABLEDeMCP_MTLS_SAN_VALIDATION_DISABLEDregistrano che un gruppo di ambienti ha disattivato una convalida, in modo che la scelta rimanga rilevabile in un parco risorse.MCP_MTLS_MATERIAL_REMOVEDè la pulizia di routine dopo che un gruppo ha disattivato la funzionalità, mentreMCP_MTLS_COLLECTION_FAILEDindica che la pulizia non è stata completata e i file dei certificati del gruppo sono ancora nel pod; il prossimo aggiornamento riproverà la pulizia. - Se il cluster non segnala alcun problema e i log del sidecar sono puliti ma le chiamate allo strumento al gruppo di ambiente continuano a fallire, l'handshake viene rifiutato da una delle due parti:
- Il gateway in entrata rifiuta il certificato client quando l'emittente non si trova nella CA considerata attendibile dal gateway in entrata per quel gruppo di ambienti (
virtualhosts[].caCertPathoINGRESS_SECRET_NAME-cacert). Verifica conopenssl verify -CAfile INGRESS_CA_FILE MCP_CLIENT_CERT_FILE. - Il piano dati MCP rifiuta il certificato del gateway in entrata quando non è concatenato alla CA in
mcpMtls.caCertPathoMCP_CLIENT_SECRET_NAME-cacerto quando i relativi nomi alternativi del soggetto non includono l'alias host del gruppo di ambiente. Verifica conopenssl verify -CAfile MCP_TRUST_CA_FILE INGRESS_CERT_FILEe ispeziona i SAN conopenssl x509 -in INGRESS_CERT_FILE -noout -ext subjectAltName. È preferibile riemettere il certificato del gateway in entrata in modo che copra l'alias host. Solo se non è possibile, impostamcpMtls.disableSanValidation: trueper quel gruppo di ambienti, in modo che il piano dati MCP non controlli il nome sul certificato del gateway in entrata.
- Il gateway in entrata rifiuta il certificato client quando l'emittente non si trova nella CA considerata attendibile dal gateway in entrata per quel gruppo di ambienti (
Richieste di assistenza
Se apri una richiesta di assistenza che coinvolge il piano dati MCP di Apigee Hybrid, allega il seguente output per accelerare la diagnosi:
kubectl -n APIGEE_NAMESPACE logs -l app=apigee-mcp-server --all-containers --tail=1000kubectl -n APIGEE_NAMESPACE describe pod -l app=apigee-mcp-serverkubectl -n APIGEE_NAMESPACE get pods -l app=apigee-mcp-server -o wideekubectl -n APIGEE_NAMESPACE get svc -l app=apigee-mcp-server.- Output recenti di
overrides.yamlehelm history APIGEE_ORG_RELEASE_NAME -n APIGEE_NAMESPACE(doveAPIGEE_ORG_RELEASE_NAMEè il nome della release Helm per il graficoapigee-org; trovalo conhelm list -n APIGEE_NAMESPACE | grep apigee-org). Prima di condividereoverrides.yaml, oscura il materiale secret, tra cui:- Qualsiasi chiave account di servizio in linea in
gcp.workloadIdentity,envs[].serviceAccountPathsomcpServer.serviceAccountPath. - Qualsiasi certificato TLS o chiave privata in
virtualhosts. - I campi della password
cassandra.auth. - Eventuali credenziali in linea che gli override passano all'operatore.
- Qualsiasi chiave account di servizio in linea in
- Il comando
curlcompleto e la risposta che riproduce il problema.
Impossibile modificare lo stile dell'API in MCP in API Hub
Se nell'hub delle API Apigee è già presente una risorsa API con operazioni API esistenti, non puoi modificare l'attributo Stile API per quella risorsa in MCP. Per registrare un'API con l'hub delle API Apigee come API MCP, devi selezionare lo stile MCP quando registri l'API per la prima volta o assicurarti che non siano presenti operazioni sulla risorsa API prima di modificare lo stile in MCP.
Se riscontri altri problemi, consulta Utilizzo del debug per informazioni dettagliate sull'utilizzo dello strumento di debug nella console Google Cloud per analizzare le richieste e le risposte da e verso il tuo proxy di rilevamento MCP.