Risolvere i problemi di deployment di MCP in Apigee

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.

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.

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-east2
    • asia-northeast3
    • asia-southeast2
    • australia-southeast1
    • europe-central2
    • europe-west12
    • europe-west9
    • me-central2
    • us-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 info ripetuta che indica l'assenza di configurazione MCP dal control plane:
    {"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"}
    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.
  • Linea error con un contatore consecutive_failures:
    {"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>"}
    I log sidecar sono JSON strutturati. Quando vedi "level":"error" con un contatore consecutive_failures in 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-watcher non è presente nell'elenco watcher_identities della risorsa controlPlaneAccess della 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.com o storage.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-watcher non 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.

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.

  1. Verifica che l'operatore abbia accettato il campo. La risorsa di routing del gruppo di ambienti deve contenere il blocco mcpMtls:
    kubectl -n APIGEE_NAMESPACE get apigeeroutes -l envGroupId=ENV_GROUP_NAME \
      -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.mcpMtls}{"\n"}{end}'
    Una seconda colonna vuota, diversi minuti dopo l'upgrade di apigee-virtualhost, di solito significa che le definizioni delle risorse personalizzate di Apigee nel cluster sono precedenti a 1.17.4 e non dichiarano mcpMtls, quindi il server API ha eliminato il campo. (Meno spesso, non è stato eseguito l'upgrade del grafico apigee-org che fornisce l'immagine del watcher a 1.17.4.) Questo accade quando un upgrade ha eseguito helm upgrade per 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à MUTUAL lo rifiuta; le stesse CRD obsolete impediscono inoltre la segnalazione dei problemi di AIS_MCP_MTLS_* nel passaggio successivo. Controlla e correggi con:
    kubectl 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
    Esegui kubectl apply dalla directory dei chart Helm, quindi esegui di nuovo l'upgrade di apigee-virtualhost per il gruppo di ambienti.
  2. Controlla se sono presenti problemi relativi ai certificati segnalati dal cluster. Il watcher analizza i secret configurati e crea un ApigeeIssue per ogni problema:
    kubectl -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
    Il campo Spec.Details indica il nome del secret e della ApigeeRouteConfig (denominata ORG_NAME-ENV_GROUP_NAME) a cui appartiene il problema, nonché il difetto specifico.
    Motivo Gravità Significato Correggi
    AIS_MCP_MTLS_CLIENT_CERT_INVALID ERROR Il secret del certificato client non esiste (secret not found), manca una voce cert o key, una voce è vuota o non è PEM, il certificato e la chiave non corrispondono o l'utilizzo della chiave estesa del certificato omette clientAuth. 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 con clientAuth.
    AIS_MCP_MTLS_CLIENT_CERT_EXPIRY WARNING entro 14 giorni dalla scadenza; ERROR dopo Il 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_INVALID ERROR Il secret -cacert non esiste (secret not found; con sslSecret lo crei tu), manca la voce cacert, 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_EXPIRY WARNING entro 14 giorni dalla scadenza; ERROR dopo Un certificato CA nel secret -cacert sta 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 -cacert prima che scada, insieme al certificato del gateway in entrata se anche questo viene riemesso.
    I problemi vengono ritirati automaticamente alla scansione successiva dopo la correzione del secret.
  3. Leggi i messaggi mTLS del sidecar. Il container apigee-mcp-server-config registra una riga error ogni volta che non può applicare i certificati di un gruppo di ambienti. In genere, ogni riga include campi come env_group, secret (e un campo trust-Secret quando la convalida della catena è attiva), un codice reason e il testo dell'errore aggregato. Filtra in base al valore del codice reason, che è l'identificatore stabile; non fare affidamento sugli altri nomi dei campi:
    kubectl -n APIGEE_NAMESPACE logs -l app=apigee-mcp-server -c apigee-mcp-server-config \
      | grep MCP_MTLS_
    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.

    I seguenti codici motivo sono stabili per la release corrente. Se visualizzi un codice non presente nell'elenco, contatta l'assistenza clienti Google Cloud.

    reason Significato Azione
    MCP_MTLS_SECRET_NOT_FOUND Un secret a cui viene fatto riferimento non esiste nello spazio dei nomi Apigee. Il testo error ne indica il nome e se si tratta del secret del client o del trust. Crea il secret con il nome esatto (ricorda il suffisso -cacert per la CA di attendibilità). Il sidecar rileva autonomamente il nuovo secret.
    MCP_MTLS_MATERIAL_UNUSABLE Il 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 clientAuth o un secret di attendibilità senza certificato CA. Lo stesso difetto viene segnalato come ApigeeIssue (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_FAILED Il 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 riga MCP_MTLS_SECRET_READ_FAILED include il contesto dei nuovi tentativi e il sidecar riprova con backoff; le altre due segnalano lo stato del monitoraggio del secret del sidecar e MCP_MTLS_SECRET_READER_RECOVERED viene registrato quando l'accesso viene restituito. Verifica che il ruolo MCP conceda ancora get, list, watch su secrets (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 con kubectl -n APIGEE_NAMESPACE get role | grep apigee-mcp-server.
    MCP_MTLS_PUBLISH_FAILED I 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_RECOVERED quando 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_GROUP Il gruppo di ambienti ha mcpMtls configurato, ma il valore dell'etichetta envGroupId non è un elemento di percorso valido, pertanto il piano dati MCP gestisce il gruppo tramite TLS unidirezionale e un gateway in entrata in modalità MUTUAL rifiuta 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. Nessun ApigeeIssue lo segnala. Verifica che la risorsa di routing abbia un'etichetta valida: kubectl -n APIGEE_NAMESPACE get apigeeroutes --show-labels. Esegui nuovamente l'upgrade di apigee-virtualhost per il gruppo di ambienti in modo che la risorsa venga ricreata dal grafico.
    MCP_MTLS_SAN_WITHOUT_CHAIN_VALIDATION Il gruppo di ambienti imposta disableChainValidation: true e disableSanValidation: false insieme. 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 disableSanValidation dal blocco mcpMtls del gruppo di ambienti o imposta nuovamente disableChainValidation su false e fornisci una CA attendibile (vedi disableSanValidation).
    MCP_MTLS_CONFLICTING_CONFIG Due risorse di routing nello stesso gruppo di ambienti contengono blocchi mcpMtls diversi, 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-virtualhost per il gruppo di ambiente, quindi verifica che i blocchi corrispondano al comando get apigeeroutes nel passaggio 1. Ogni route di un gruppo deriva dalla singola voce virtualhosts[] del gruppo, quindi un disaccordo indica che le risorse sono state applicate direttamente al cluster o che un upgrade precedente è stato propagato solo parzialmente.
    Ad eccezione di 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_DISABLED e MCP_MTLS_SAN_VALIDATION_DISABLED registrano 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à, mentre MCP_MTLS_COLLECTION_FAILED indica che la pulizia non è stata completata e i file dei certificati del gruppo sono ancora nel pod; il prossimo aggiornamento riproverà la pulizia.

  4. 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[].caCertPath o INGRESS_SECRET_NAME-cacert). Verifica con openssl 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.caCertPath o MCP_CLIENT_SECRET_NAME-cacert o quando i relativi nomi alternativi del soggetto non includono l'alias host del gruppo di ambiente. Verifica con openssl verify -CAfile MCP_TRUST_CA_FILE INGRESS_CERT_FILE e ispeziona i SAN con openssl 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, imposta mcpMtls.disableSanValidation: true per quel gruppo di ambienti, in modo che il piano dati MCP non controlli il nome sul certificato del gateway in entrata.

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=1000
  • kubectl -n APIGEE_NAMESPACE describe pod -l app=apigee-mcp-server
  • kubectl -n APIGEE_NAMESPACE get pods -l app=apigee-mcp-server -o wide e kubectl -n APIGEE_NAMESPACE get svc -l app=apigee-mcp-server.
  • Output recenti di overrides.yaml e helm history APIGEE_ORG_RELEASE_NAME -n APIGEE_NAMESPACE (dove APIGEE_ORG_RELEASE_NAME è il nome della release Helm per il grafico apigee-org; trovalo con helm list -n APIGEE_NAMESPACE | grep apigee-org). Prima di condividere overrides.yaml, oscura il materiale secret, tra cui:
    • Qualsiasi chiave account di servizio in linea in gcp.workloadIdentity, envs[].serviceAccountPaths o mcpServer.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.
  • Il comando curl completo 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.