Risolvere i problemi di deployment di MCP in Apigee

Questa pagina si applica ad Apigee e 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 la propagazione completa della configurazione nell'infrastruttura Apigee e Google Cloud prima del completamento del deployment del proxy.

Mentre vengono eseguiti questi passaggi di provisioning downstream, l'interfaccia utente mostra il proxy con lo stato Provisioning. Al termine del processo, lo stato cambia in Eseguito il deployment. Questo stato conferma che tutti i componenti downstream sono completamente sottoposti a provisioning e che il proxy è pronto a 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.

Codici di stato della risposta di errore per chiamate allo strumento e metadati

Gli endpoint Apigee MCP restituiscono codici di stato HTTP che seguono le specifiche del Model Context Protocol (MCP) e gli standard OAuth correlati. Comprendere questo comportamento ti aiuta a gestire correttamente gli errori nel client MCP o nell'agente AI.

La tabella seguente riassume i codici di stato restituiti dagli endpoint Apigee MCP:

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, ad esempio 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 e recuperare (ad esempio, riproponendo l'input mancante e riprovando) anziché terminare la sessione.
I metadati della risorsa protetta da OAuth (PRM) non sono configurati o non sono disponibili all'indirizzo /.well-known/oauth-protected-resource/mcp. 404 Not Found Indica che non sono disponibili metadati delle risorse protette nella posizione richiesta.
Il token di accesso è mancante, non valido o scaduto. 401 Unauthorized Include una sfida WWW-Authenticate per guidare il flusso di individuazione di OAuth.
Il token di accesso ha un ambito insufficiente. 403 Forbidden Include una sfida WWW-Authenticate per guidare il flusso di autorizzazione step-up.

Esempio: corpo della risposta all'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 preservato: 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
  }
}

Il id corrisponde al id della tua richiesta relativa a tools/call. Se il backend non restituisce un corpo della risposta, text contiene un riepilogo generato, ad esempio Operation failed (HTTP 500).

Il client MCP deve esaminare 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 in formato errato) sono diversi 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.

Consiglio: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 codici di stato non standard, ad esempio l'analisi di un corpo della risposta non 2xx per errori tools/call o il trattamento di una risposta 500 dall'endpoint PRM come "metadati non configurati", ti consigliamo di rimuovere questa soluzione alternativa. In caso contrario, il client potrebbe continuare a utilizzare una logica di gestione obsoleta anziché elaborare normalmente i codici di stato corretti.

Policy CORS per le chiamate MCP basate sul browser

Una policy di condivisione delle risorse tra origini (CORS) è necessaria quando le chiamate Apigee MCP vengono effettuate direttamente da un browser (ad esempio, quando l'ispettore MCP utilizza l'impostazione "Diretta" anziché "Tramite proxy"). Il modello di proxy di rilevamento MCP include i criteri CORS in Proxy Endpoint Request PreFlow del bundle proxy per impostazione predefinita per abilitare le chiamate basate su browser.

Se riscontri problemi relativi a CORS quando effettui chiamate direttamente da un browser, potrebbe essere necessario modificare le impostazioni dei criteri CORS nel Request PreFlow dell'endpoint proxy del bundle proxy MCP Discovery.

Errore di analisi JSON durante l'invio della richiesta all'endpoint MCP

Quando invii una richiesta all'endpoint MCP, potresti ricevere un messaggio di errore simile al seguente (o con un codice e un messaggio di errore 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 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 riesce e viene visualizzato lo stato Non riuscito nell'interfaccia utente, controlla il messaggio di errore per maggiori dettagli. I problemi 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 al provisioning del bilanciatore del carico non riuscito o se lo stato del provisioning non cambia mai in Eseguito il deployment, il problema 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 ibrido, in cui l'infrastruttura di runtime è il tuo cluster.

  • MCP non abilitato nel cluster (solo Apigee Hybrid): se il deployment del proxy MCP rimane indefinitamente nello stato Provisioning e non raggiunge mai lo stato Deployed, verifica che MCP sia abilitato nel cluster. Consulta la sezione Diagnosi lato cluster di seguito.

Diagnosi 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 nel cluster vengono diagnosticate con kubectl rispetto al cluster. Segui l'elenco di controllo diagnostico riportato di seguito in ordine.

Passaggio 1: verifica che MCP sia abilitato nel cluster

MCP viene implementato come risorsa personalizzata ApigeeDeployment (gestita dall'operatore Apigee), non come Deployment Kubernetes di base. Controlla se l'MCP 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 a Attiva MCP in Apigee Hybrid e verifica che enableMcpServer: true sia impostata come chiave di primo livello nel tuo 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 differisce 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 comuni sono gli errori di pull delle immagini (verifica l'uscita dal cluster al registro delle immagini configurato in overrides.yaml) e lo spazio libero insufficiente di CPU o memoria (aumenta mcpServer.resources.requests in overrides.yaml).

Passaggio 3: controlla lo stato del pull della configurazione del sidecar

Il container sidecar apigee-mcp-server-config in ogni pod MCP recupera periodicamente la configurazione MCP dal control plane Apigee. Ogni pull recupera il riferimento alla configurazione corrente da apigee.googleapis.com, quindi recupera il bundle di configurazione a cui viene fatto riferimento da Cloud Storage. Il data plane MCP inizia a gestire il traffico dello strumento 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 alcun 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 e viene visualizzato il messaggio 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 piano di controllo: 
    {"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 piano di controllo Apigee ha restituito una risposta riuscita, ma non è ancora stato implementato alcun proxy di rilevamento MCP per la tua organizzazione. Questo è lo stato stazionario previsto durante l'onboarding. Per eseguire la transizione del piano dati MCP allo stato di servizio, 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, il sidecar non è riuscito a completare un pull della configurazione. Il sidecar esegue automaticamente nuovi tentativi con backoff e reimposta il contatore su 0 al successivo pull riuscito.

    Cause principali comuni da controllare 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 Passaggio 2: concedi all'identità watcher l'accesso alla configurazione MCP sul control plane nella procedura di attivazione per aggiungere la concessione e verificare che sia stata applicata.
    • Il traffico in uscita dal cluster a apigee.googleapis.com o storage.googleapis.com è bloccato. Entrambi gli endpoint devono essere raggiungibili dai pod MCP (vedi Requisiti di rete in uscita nella procedura di attivazione).
    • L'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 di tempo prolungato dopo aver escluso le cause sopra indicate, contatta l'assistenza Apigee.

Passaggio 4: verifica che siano stati inseriti gli hostAliases del processore di messaggi

Quando attivi MCP, l'operator Apigee inserisce una voce hostAliases nella specifica del pod del processore di messaggi (MP). La voce contiene un IP (l'IP del cluster del servizio MCP) e due nomi host: mcp.apigee.internal e ORG_NAME.mcp.apigee.internal in minuscolo. Verifica che l'inserimento sia riuscito:

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 punta a Service ClusterIP di 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 corrente (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 tramite il piano dati MCP, esegui il deployment di un proxy di rilevamento MCP e segui la guida rapida di MCP. Prima che venga eseguito il 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 connessione rifiutata indipendentemente dal fatto che il processore di messaggi possa raggiungere i pod MCP (vedi passaggio 3).

Richieste di assistenza

Se apri una richiesta di assistenza che riguarda il data plane MCP ibrido di Apigee, 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, oscurane il materiale segreto, tra cui:
    • Qualsiasi chiave account di servizio incorporata in gcp.workloadIdentity, envs[].serviceAccountPaths o mcpServer.serviceAccountPath.
    • Eventuali certificati TLS o chiavi private in virtualhosts.
    • I campi della password cassandra.auth.
    • Eventuali credenziali inline che gli override passano all'operatore.
  • Il comando curl completo e la risposta che riproduce il problema.

Impossibile modificare lo stile API in MCP nell'hub API

Se una risorsa API con operazioni API esistenti è già presente nell'hub delle API Apigee, 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 al momento della registrazione iniziale dell'API o assicurarti che non siano presenti operazioni nella risorsa API prima di modificare lo stile in MCP.

Se riscontri altri problemi, consulta Utilizzo di 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 proxy di rilevamento MCP.