Memecahkan masalah deployment MCP di Apigee

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat dokumentasi Apigee Edge.

Halaman ini menjelaskan cara memecahkan masalah dan menyelesaikan masalah terkait deployment proxy penemuan MCP. Anda dapat menggunakan halaman ini untuk memahami siklus proses penyediaan asinkron deployment MCP, menyelesaikan kode error, dan memverifikasi konektivitas runtime.

Memahami deployment MCP

Deployment Proxy Penemuan MCP adalah proses asinkron multi-langkah yang memastikan konfigurasi disebarkan sepenuhnya di seluruh infrastruktur Apigee dan Google Cloud sebelum deployment proxy selesai.

Saat langkah-langkah penyediaan downstream ini berlangsung, UI akan menampilkan proxy dalam status Provisioning. Setelah proses selesai, statusnya akan berubah menjadi Deployed. Status ini mengonfirmasi bahwa semua komponen downstream telah disediakan sepenuhnya dan proxy siap menangani traffic.

Pemecahan masalah

Bagian berikut menjelaskan error dan masalah umum yang mungkin Anda alami saat menggunakan MCP di Apigee.

Masalah: Backend membaca argumen alat dari satu lokasi permintaan — string kueri, header, atau cookie — tetapi spesifikasi OpenAPI menyatakan parameter in di lokasi yang berbeda, sehingga argumen tiba di tempat lain pada permintaan backend. Panggilan akan gagal atau berperilaku seolah-olah argumen tidak ada.

Gejala: Permintaan tools/call berhasil di lapisan MCP dan klien MCP menyediakan argumen, tetapi backend merespons seolah-olah nilai tidak ada — misalnya 400 untuk nilai yang diperlukan, atau default yang diterapkan sebagai pengganti nilai yang dikirim.

Penyebab: Parameter dideklarasikan sebagai in: header atau in: cookie dalam spesifikasi OpenAPI, sehingga Apigee mengirimkan nilainya sebagai header permintaan atau di header Cookie, bukan dalam string kueri. Backend yang membaca nilai hanya dari string kueri tidak akan melihatnya. Lihat Penempatan argumen alat pada permintaan backend.

Penyelesaian: Tentukan tempat nilai berada dan buat spesifikasi serta backend setuju:

  • Untuk mempertahankan nilai dalam string kueri, deklarasikan parameter in: query.
  • Untuk mengirimkannya sebagai header atau cookie, biarkan deklarasi apa adanya dan baca nilai dari lokasi tersebut di backend Anda.

Masalah: Cookie yang tiba di permintaan HTTP yang dibuat klien MCP — misalnya, cookie sesi dari klien berbasis browser — berhenti mencapai backend pada beberapa panggilan alat.

Gejala: Backend berperilaku seolah-olah pemanggil tidak diautentikasi atau tidak dalam sesi, dan perilakunya tidak konsisten: operasi yang sama berfungsi pada beberapa panggilan dan tidak pada panggilan lainnya.

Penyebab: Operasi mendeklarasikan satu atau beberapa parameter in: cookie, dan panggilan yang terpengaruh menyediakan setidaknya salah satunya. Header Cookie ditulis ulang secara keseluruhan, bukan ditambahkan, sehingga pada panggilan tersebut, header hanya membawa parameter cookie yang dideklarasikan dan setiap cookie lainnya dihapus. Panggilan yang tidak menyediakan parameter cookie akan meneruskan header tanpa perubahan, sehingga hanya beberapa panggilan yang gagal. Lihat Cookie pada permintaan ke backend Anda.

Penyelesaian: Deklarasikan setiap cookie yang diperlukan backend sebagai parameter in: cookie pada setiap operasi yang memerlukannya, sehingga nilainya selalu disediakan oleh panggilan alat, bukan diwarisi dari permintaan klien. Tidak ada setelan yang mempertahankan cookie yang tidak dideklarasikan.

Kode status respons error untuk panggilan alat dan metadata

Endpoint MCP Apigee menampilkan kode status HTTP yang mengikuti spesifikasi Model Context Protocol (MCP) dan standar OAuth terkait. Memahami perilaku ini akan membantu Anda menangani error dengan benar di klien MCP atau agen AI Anda.

Tabel berikut merangkum kode status yang ditampilkan oleh endpoint MCP Apigee:

Skenario Kode status HTTP Isi respons
Eksekusi alat gagal di tools/call (misalnya, API backend menampilkan error 4xx atau 5xx, seperti error validasi atau kolom wajib diisi yang tidak ada). 200 OK CallToolResult dengan result.isError yang ditetapkan ke true dan detail error di content. Hal ini memungkinkan klien MCP dan agen LLM membaca error dan memulihkan (misalnya, dengan meminta ulang input yang tidak ada dan mencoba lagi) daripada menghentikan sesi.
Metadata Resource yang Dilindungi OAuth (PRM) tidak dikonfigurasi atau tidak dapat ditemukan di /.well-known/oauth-protected-resource/mcp. 404 Not Found Menunjukkan bahwa tidak ada metadata resource yang dilindungi yang tersedia di lokasi yang diminta.
Token akses tidak ada, tidak valid, atau sudah tidak berlaku. 401 Unauthorized Menyertakan tantangan WWW-Authenticate untuk mendorong alur penemuan OAuth.
Token akses tidak memiliki cakupan yang memadai. 403 Forbidden Menyertakan tantangan WWW-Authenticate untuk mendorong alur otorisasi peningkatan.

Contoh: isi respons error eksekusi alat

Jika panggilan alat gagal, Apigee MCP akan menampilkan HTTP 200 OK dan melaporkan kegagalan dalam objek result JSON-RPC, dengan isError ditetapkan ke true. Error asli yang ditampilkan oleh backend Anda dipertahankan: isi respons backend ditempatkan secara verbatim (sebagai string) di result.content[].text. Misalnya, jika backend menampilkan HTTP 404 dengan isi {"error":"User 42 not found"}, respons MCP adalah:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"error\":\"User 42 not found\"}"
      }
    ],
    "isError": true
  }
}

id cocok dengan id permintaan tools/call Anda. Jika backend tidak menampilkan isi respons, text akan berisi ringkasan yang dihasilkan, seperti Operation failed (HTTP 500).

Klien MCP Anda harus memeriksa result.isError (bukan kode status HTTP) untuk mendeteksi panggilan alat yang gagal. Jika kode klien Anda secara khusus mengharapkan status HTTP 4xx atau 5xx untuk menandakan error eksekusi alat, kode tersebut tidak akan mendeteksi error, karena responsnya adalah HTTP 200 OK. Update klien tersebut untuk membaca result.isError dan array content.

Error tingkat protokol (misalnya, permintaan JSON-RPC yang salah format) berbeda dengan error eksekusi alat: error tersebut terus ditampilkan dalam objek error JSON-RPC (misalnya, {"jsonrpc": "2.0", "error": {"code": -32700, ...}}) bukan di result.isError.

Rekomendasi: Klien MCP yang mematuhi standar menangani kode status ini melalui logika defaultnya, sehingga tidak diperlukan perubahan. Jika sebelumnya Anda menambahkan solusi sisi klien untuk menangani kode status non-standar—misalnya, mengurai isi respons non-2xx untuk error tools/call, atau memperlakukan respons 500 dari endpoint PRM sebagai "metadata tidak dikonfigurasi"—sebaiknya hapus solusi tersebut. Jika tidak, klien Anda mungkin akan terus menggunakan logika penanganan yang sudah tidak berlaku, bukan memproses kode status yang telah diperbaiki seperti biasa.

Kebijakan CORS untuk panggilan MCP berbasis browser

Kebijakan Cross-Origin Resource Sharing (CORS) diperlukan saat panggilan MCP Apigee dilakukan langsung dari browser (misalnya, saat pemeriksa MCP menggunakan setelan "Direct", bukan "Via Proxy"). Template Proxy Discovery MCP menyertakan kebijakan CORS Apigee di PreFlow Permintaan Endpoint Proxy dari paket proxy secara default untuk mengaktifkan panggilan berbasis browser.

Jika Anda mengalami masalah terkait CORS saat melakukan panggilan langsung dari browser, Anda mungkin perlu menyesuaikan setelan kebijakan CORS di PreFlow Permintaan Endpoint Proxy dari paket proxy MCP Discovery Anda.

Error penguraian JSON saat mengirim permintaan ke endpoint MCP

Anda mungkin menerima pesan error yang mirip dengan berikut ini (atau dengan kode dan pesan error yang berbeda) saat mengirim permintaan ke endpoint MCP Anda: 

{
  "error": {
    "code": -32700,
    "message": "JSON parse error"
  },
  "id": null,
  "jsonrpc": "2.0"
}

Jika demikian, sebaiknya konfirmasi informasi berikut:

  • Anda telah memasukkan URL endpoint MCP yang benar.
  • Permintaan Anda diformat dengan benar.
  • Anda mengakses metode yang didukung.
  • Anda telah mengaktifkan dan mengonfigurasi Proxy Penemuan MCP di wilayah yang didukung. Untuk mengetahui daftar region yang mungkin memiliki batas kapasitas, lihat kegagalan deployment.

Kegagalan deployment

Jika deployment Proxy Discovery MCP Anda gagal dengan status Failed di UI, periksa pesan error untuk mengetahui detail selengkapnya. Kegagalan umum meliputi:

  • Networking configuration failed atau Unsupported Schema in OAS: Error ini biasanya menunjukkan masalah pada spesifikasi OpenAPI Anda. Pastikan spesifikasi Anda valid dan menggunakan versi yang didukung.
  • Batas kapasitas region (khusus Apigee): Jika Anda melihat error terkait kegagalan penyediaan load balancer, atau status penyediaan tidak pernah berubah menjadi Deployed, hal ini mungkin disebabkan oleh batas kapasitas infrastruktur sementara di salah satu region berikut:
    • asia-east2
    • asia-northeast3
    • asia-southeast2
    • australia-southeast1
    • europe-central2
    • europe-west12
    • europe-west9
    • me-central2
    • us-central2

    Untuk mengatasi error, coba deploy proxy ke lingkungan di region lain. Mode kegagalan ini tidak berlaku untuk Apigee hybrid, yang infrastruktur runtime-nya adalah cluster Anda sendiri.

  • MCP tidak diaktifkan di cluster (khusus Apigee hybrid): Jika deployment proxy MCP Anda tetap dalam status Provisioning tanpa batas waktu dan tidak pernah mencapai Deployed, pastikan MCP diaktifkan di cluster Anda. Lihat Diagnosis sisi cluster di bawah.

Diagnosis sisi cluster (khusus Apigee hybrid)

Karena bidang data MCP hybrid Apigee berjalan di dalam cluster Kubernetes Anda sendiri, mode kegagalan dalam cluster didiagnosis dengan kubectl terhadap cluster. Ikuti checklist diagnostik berikut secara berurutan.

Langkah 1: Pastikan MCP diaktifkan di cluster

MCP di-deploy sebagai resource kustom ApigeeDeployment (dikelola oleh operator Apigee), bukan sebagai Deployment Kubernetes standar. Periksa MCP ApigeeDeployment:

kubectl -n APIGEE_NAMESPACE get apigeedeployment -l app=apigee-mcp-server

Output yang diharapkan (nama resource menyertakan akhiran yang berasal dari organisasi, yang ditampilkan di sini sebagai ORG_CR_SUFFIX):

NAME                                     STATE     NESTEDSTATE   AGE
apigee-mcp-server-default-ORG_CR_SUFFIX       running                 1h

Jika perintah menampilkan No resources found in APIGEE_NAMESPACE namespace., MCP tidak diaktifkan. Kembali ke Mengaktifkan MCP di Apigee hybrid dan pastikan enableMcpServer: true ditetapkan sebagai kunci level teratas di overrides.yaml, dan Anda telah mengupgrade rilis Helm apigee-operator sebelum rilis apigee-org. Lihat Langkah 3 dan Langkah 4 dari prosedur pengaktifan untuk perintah helm yang benar.

Langkah 2: Pastikan pod MCP berjalan

kubectl -n APIGEE_NAMESPACE get pods -l app=apigee-mcp-server

Output yang diharapkan (akhiran pod akan berbeda):

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

Nama pod mengikuti template apigee-mcp-server-default-ORG_CR_SUFFIX-REV-POD_HASH, dengan REV adalah revisi rilis hybrid empat digit (misalnya, 1170 untuk hybrid 1.17.0) dan POD_HASH adalah akhiran alfanumerik delapan karakter yang berbeda untuk setiap pod.

Setiap pod harus menampilkan 2/2 di kolom READY dan Running di kolom STATUS. Jika pod tidak Running, kubectl -n APIGEE_NAMESPACE describe pod POD_NAME akan menampilkan alasannya. Penyebab umumnya adalah kegagalan pull image (verifikasi egress dari cluster Anda ke registry image yang dikonfigurasi di overrides.yaml) dan headroom CPU atau memori yang tidak memadai (naikkan mcpServer.resources.requests di overrides.yaml).

Langkah 3: Periksa status pull konfigurasi sidecar

Container sidecar apigee-mcp-server-config di setiap pod MCP secara berkala mengambil konfigurasi MCP dari bidang kontrol Apigee. Setiap pull mengambil referensi konfigurasi saat ini dari apigee.googleapis.com, lalu mengambil paket konfigurasi yang direferensikan dari Cloud Storage. Data plane MCP mulai menyalurkan traffic alat MCP di https://mcp.apigee.internal/mcp setelah pull berhasil diselesaikan dengan konfigurasi yang valid.

Sebelum pull pertama yang berhasil dengan konfigurasi yang valid (baik karena belum ada Proxy Discovery MCP yang di-deploy untuk organisasi Anda, atau karena sidecar tidak dapat menjangkau bidang kontrol), pod MCP tetap Ready, tetapi permintaan ke https://mcp.apigee.internal/mcp gagal dengan koneksi ditolak.

Periksa log file bantuan untuk menentukan kasus yang Anda alami:

kubectl -n APIGEE_NAMESPACE logs -l app=apigee-mcp-server -c apigee-mcp-server-config --tail=100
  • Baris info berulang yang menunjukkan tidak ada konfigurasi MCP dari bidang kontrol: 
    {"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"}
     Bidang kontrol Apigee menampilkan respons yang berhasil, tetapi belum ada Proxy Discovery MCP yang di-deploy untuk organisasi Anda. Ini adalah status stabil yang diharapkan selama orientasi. Untuk mentransisikan bidang data MCP ke status penyajian, deploy Proxy Penemuan MCP sesuai dengan panduan memulai MCP.
  • error baris dengan penghitung 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>"}
     Log sidecar adalah JSON terstruktur. Saat Anda melihat "level":"error" dengan penghitung consecutive_failures yang meningkat, sidecar tidak dapat menyelesaikan pengambilan konfigurasi. Sidecar akan otomatis mencoba lagi dengan backoff dan mereset penghitung ke 0 pada penarikan berikutnya yang berhasil.

    Penyebab utama yang umum untuk diperiksa saat penghitung ini terus meningkat:

    • Akun layanan Google Cloud apigee-watcher tidak ada dalam daftar watcher_identities di resource controlPlaneAccess organisasi Apigee Anda. Lihat Langkah 2: Berikan akses identitas watcher ke konfigurasi MCP di bidang kontrol dalam prosedur pengaktifan untuk menambahkan pemberian dan memverifikasi bahwa pemberian tersebut telah diterapkan.
    • Egress dari cluster Anda ke apigee.googleapis.com atau storage.googleapis.com diblokir. Kedua endpoint harus dapat dijangkau dari pod MCP (lihat Persyaratan jaringan keluar dalam prosedur pengaktifan).
    • Akun layanan apigee-watcher tidak dapat memperoleh token akses Google Cloud dari cluster ini. Jika komponen Apigee hybrid yang ada di namespace yang sama juga melaporkan kegagalan autentikasi, selesaikan masalah autentikasi bersama terlebih dahulu.
    • Error sementara pada bidang kontrol Apigee atau Cloud Storage. Jika penghitung terus meningkat dalam jangka waktu yang lama setelah mengesampingkan penyebab di atas, hubungi Dukungan Apigee.

Langkah 4: Pastikan hostAliases Message Processor telah dimasukkan

Saat Anda mengaktifkan MCP, operator Apigee memasukkan satu entri hostAliases ke dalam spesifikasi pod Message Processor (MP). Entri ini berisi satu IP (ClusterIP Layanan MCP) dan dua nama host: mcp.apigee.internal dan ORG_NAME.mcp.apigee.internal dalam huruf kecil. Pastikan injeksi berhasil:

kubectl -n APIGEE_NAMESPACE get pods -l app=apigee-runtime \
  -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.hostAliases}{"\n"}{end}'

Setiap pod MP yang tercantum harus memiliki entri hostAliases yang berisi mcp.apigee.internal dan ORG_NAME.mcp.apigee.internal dalam huruf kecil yang mengarah ke ClusterIP Layanan MCP. Setiap pod MP yang menampilkan entri kosong atau tidak ada dibuat sebelum MCP diaktifkan. Hapus pod MP yang terpengaruh sehingga pengontrol ApigeeDeployment membuatnya ulang dari spesifikasi pod saat ini (yang mencakup entri hostAliases yang dimasukkan):

kubectl -n APIGEE_NAMESPACE delete pod -l app=apigee-runtime

Langkah 5: Verifikasi menyeluruh

Untuk pengujian menyeluruh yang mengirimkan permintaan initialize MCP yang sebenarnya melalui bidang data MCP, deploy Proxy Discovery MCP dan ikuti panduan memulai MCP. Sebelum Proxy Discovery MCP di-deploy untuk organisasi Anda, permintaan ke https://mcp.apigee.internal/mcp akan gagal dengan pesan connection refused, terlepas dari apakah Message Processor dapat menjangkau pod MCP atau tidak (lihat Langkah 3).

Kasus dukungan

Jika Anda membuka kasus dukungan yang melibatkan bidang data MCP hybrid Apigee, lampirkan output berikut untuk mempercepat diagnosis:

  • 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 dan kubectl -n APIGEE_NAMESPACE get svc -l app=apigee-mcp-server.
  • Output overrides.yaml dan helm history APIGEE_ORG_RELEASE_NAME -n APIGEE_NAMESPACE terbaru (dengan APIGEE_ORG_RELEASE_NAME adalah nama rilis Helm untuk diagram apigee-org; temukan dengan helm list -n APIGEE_NAMESPACE | grep apigee-org). Sebelum membagikan overrides.yaml, edit materi rahasia, termasuk:
    • Kunci akun layanan inline apa pun di bagian gcp.workloadIdentity, envs[].serviceAccountPaths, atau mcpServer.serviceAccountPath.
    • Setiap sertifikat TLS atau kunci pribadi di bagian virtualhosts.
    • Kolom sandi cassandra.auth.
    • Kredensial inline apa pun yang diteruskan penggantian Anda ke operator.
  • Perintah dan respons curl lengkap yang mereproduksi masalah.

Tidak dapat mengubah gaya API ke MCP di API Hub

Jika resource API dengan operasi API yang ada sudah ada di hub API Apigee, Anda tidak dapat mengubah atribut API style untuk resource tersebut menjadi MCP. Untuk mendaftarkan API ke hub API Apigee sebagai API MCP, Anda harus memilih gaya MCP saat pertama kali mendaftarkan API, atau memastikan tidak ada operasi yang ada di resource API sebelum mengubah gaya ke MCP.

Jika Anda mengalami masalah lain, lihat Menggunakan debug untuk mengetahui informasi mendetail tentang cara menggunakan alat Debug di konsol Google Cloud untuk menganalisis permintaan dan respons ke dan dari Proxy Discovery MCP Anda.