Layanan Akses MCP Merchant API (Alfa)

Gunakan Layanan Akses Model Context Protocol (MCP) Merchant API untuk mendapatkan akses resmi ke data dan insight Merchant Center Anda guna membangun pengalaman agentic dan alur kerja otomatis baru.

Ringkasan

Layanan Akses MCP Merchant API menyediakan jembatan yang standar dan aman bagi LLM, agen, dan bantuan coding untuk membangun dan mengorkestrasi pengalaman agentic baru dan alur kerja otomatis yang didasarkan dalam data Merchant Center.

Secara khusus, API ini memungkinkan akses yang diizinkan ke data Merchant Center Anda serta laporan dan insight yang dihasilkan Google untuk melakukan operasi hanya baca dan operasi tulis terbatas guna menangani kasus penggunaan seperti:

• Mendiagnosis dan memperbaiki penolakan produk
• Membuat laporan performa dan insight
• Meninjau keikutsertaan untuk peningkatan otomatis
• Membuat dan mengambil sumber data

Kontrol keamanan dan akses

Layanan Akses MCP Merchant API dirancang dengan memprioritaskan keamanan:

• Autentikasi: Eksekusi alat diatur oleh autentikasi Merchant API standar, yang memerlukan kredensial OAuth 2.0 atau akun layanan. Sebaiknya gunakan kredensial dengan hak akses yang paling ketat.
• Keamanan Eksekusi: Meskipun visibilitas alat tidak dibatasi untuk penemuan agentic, eksekusi alat dibatasi untuk kredensial API spesifik Anda.
• Pengamanan: Alat dibatasi secara ketat untuk operasi hanya baca dan alat tulis berisiko rendah (misalnya, pembuatan sumber data) sebagai pagar pembatas keamanan.

Pertimbangan penting

Layanan Akses MCP Merchant API adalah versi alfa; cakupan dan kemampuannya akan diperluas dan dapat berubah.

Sebelum memulai, tinjau batasan dan praktik terbaik berikut:

Perubahan dan rilis

Perubahan dapat terjadi tanpa pemberitahuan sebelumnya dan akan dipublikasikan di catatan rilis.

Pengujian yang aman

Sebaiknya lakukan eksperimen terlebih dahulu menggunakan akun pengujian atau akun non-live sebelum menggunakan alat ini di lingkungan produksi live.

Kuota bersama

Layanan Akses MCP Merchant API menggunakan kumpulan kuota yang sama dengan panggilan API Merchant standar Anda. Menjalankan agen dapat dengan cepat menghabiskan kuota, terutama untuk pengambilan sumber data. Kami sangat menyarankan penggunaan akun pengujian untuk mencegah gangguan layanan produksi.

Pemfilteran alat dan keamanan

Kemampuan baru, terutama tindakan tulis, akan ditambahkan pada masa mendatang. Sebaiknya konfigurasikan klien Anda secara eksplisit ke pemfilteran alat bawaan, bukan mengekspos seluruh set alat.

Ringkasan kemampuan yang tersedia

Anda dapat menggunakan Layanan Akses MCP Merchant API untuk melakukan tindakan berikut dengan cara agentic:

• Ambil status mendetail dan konteks pelaporan untuk produk tertentu menggunakan nama resource yang tepat.
• Mencantumkan dan menelusuri beberapa produk.
• Buat kueri metrik performa, status produk, dan insight tentang produk populer, analisis harga, visibilitas kompetitif, dan analisis Afiliasi YouTube Shopping.
• Identifikasi masalah tingkat akun yang memengaruhi visibilitas produk atau partisipasi program.
• Mencantumkan, membuat, mengambil, dan memeriksa status upload sumber data.
• Mencantumkan alasan gabungan untuk penolakan produk di seluruh inventaris Anda.
• Tinjau setelan penyempurnaan otomatis untuk item, gambar, dan pengiriman.
• Periksa wilayah aktif, persyaratan yang belum terpenuhi, dan status partisipasi untuk program Merchant Center tertentu.

Memulai

Untuk menghubungkan IDE, asisten coding, atau agen Anda ke Layanan Akses MCP Merchant API, perbarui setelan klien MCP Anda (misalnya, mcp.json atau settings.json).

Konfigurasi klien

Penyiapan konfigurasi:

{
    "mcpServers": {
        "merchant-api-access": {
            "serverUrl": "https://merchantapi.googleapis.com/mcp",
            "headers": {
                "Authorization": "Bearer {ACCESS_TOKEN}",
                "x-goog-user-project": "{GOOGLE_CLOUD_PROJECT_ID}"
            }
        }
    }
}

claude mcp add --transport http merchant-api https://merchantapi.googleapis.com/mcp --scope local \
  --header "Authorization: Bearer {ACCESS_TOKEN}" \
  --header "X-Goog-User-Project: {GOOGLE_CLOUD_PROJECT_ID}"

curl -s -X POST "https://merchantapi.googleapis.com/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-Goog-User-Project: {GOOGLE_CLOUD_PROJECT_ID}" \
  -H "MCP-Protocol-Version: {MCP_PROTOCOL_VERSION}" \
  -H "Mcp-Method: tools/list" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {
      "_meta": {
        "io.modelcontextprotocol/protocolVersion":
          "{MCP_PROTOCOL_VERSION}"
      }
    }
  }'

curl -s -X POST "https://merchantapi.googleapis.com/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-Goog-User-Project: {GOOGLE_CLOUD_PROJECT_ID}" \
  -H "MCP-Protocol-Version: {MCP_PROTOCOL_VERSION}" \
  -H "Mcp-Method: tools/call" \
  -H "Mcp-Name: list_data_sources" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "list_data_sources",
      "arguments": {
        "parent": "accounts/{ACCOUNT_ID}"
      },
      "_meta": {
        "io.modelcontextprotocol/protocolVersion":
          "{MCP_PROTOCOL_VERSION}"
      }
    }
  }'

Contoh skenario penggunaan

Untuk mengilustrasikan cara memanfaatkan Layanan Akses MCP Merchant API untuk membangun pengalaman agentic dan alur kerja otomatis, pertimbangkan skenario berikut:

Skenario 1: Mendiagnosis dan memperbaiki penolakan produk

Anda ingin memahami alasan produk tertentu tidak muncul di hasil Google Penelusuran.

Perintah pengguna:

"Mengapa produk saya dengan ID penawaran 'offer123' tidak disetujui?"

Perilaku agen dengan MCP:

1. Agen memanggil list_products atau get_product_by_name untuk menemukan status produk.
2. Server MCP menampilkan status produk, termasuk daftar issues (misalnya, "Format harga salah" atau "Nilai pengiriman tidak ada").
3. Agen akan menganalisis masalah dan menjelaskan penyebab utamanya kepada Anda, serta menyarankan cara memperbaikinya (misalnya, memperbarui informasi harga).

Skenario 2: Meninjau keikutsertaan untuk peningkatan otomatis

Anda ingin memverifikasi apakah peningkatan kualitas pengiriman otomatis Anda aktif.

Perintah pengguna:

"Apakah peningkatan kualitas pengiriman otomatis saya diaktifkan?"

Perilaku agen dengan MCP:

1. Agen memanggil get_automatic_improvements untuk mengambil setelan tingkat akun.
2. Server MCP menampilkan konfigurasi yang menunjukkan status peningkatan gambar, item, dan pengiriman.
3. Agen akan mengonfirmasi bahwa peningkatan pengiriman aktif, atau menjelaskan cara mengaktifkannya jika nonaktif.

Skenario 3: Membuat laporan dan insight performa

Anda ingin memeriksa performa terbaru dengan cepat tanpa membuka UI Merchant Center.

Perintah pengguna:

"Tampilkan 5 produk berperforma terbaik saya berdasarkan klik minggu lalu."

Perilaku agen dengan MCP:

1. Agen membuat kueri Merchant Center Query Language (MCQL) yang menargetkan tabel product_performance_view, mengurutkan berdasarkan clicks DESC, dan membatasi hingga 5.
2. Agen memanggil report_search dengan kueri yang dibuat.
3. Server MCP menjalankan kueri terhadap database pelaporan langsung dan menampilkan barisnya.
4. Agen akan memformat hasilnya menjadi tabel Markdown yang rapi untuk Anda.

Skenario 4: Membuat dan mengambil sumber data

Anda ingin menambahkan sumber data baru untuk mengupload pembaruan produk.

Perintah pengguna:

"Buat sumber data tambahan bernama 'price-updates' untuk akun penjual saya."

Perilaku agen dengan MCP:

1. Agen memanggil create_data_source dengan setelan yang ditentukan untuk mendaftarkan feed baru.
2. Server MCP membuat sumber data dan menampilkan nama resource uniknya.
3. Agen memanggil fetch_data_source untuk memicu download dan pemrosesan file terkait.
4. Agen memanggil get_file_upload untuk memantau progres upload dan mengonfirmasi status pemrosesan item yang berhasil.

Alat dan deskripsi MCP

Layanan Akses MCP Merchant API mengekspos alat berikut ke agen Anda: