Server MCP

Zelnum menyediakan server MCP publik di https://mcp.zelnum.com/mcp. Klien apa pun yang mendukung MCP — Claude, Cursor, agen di dalam IDE — dapat menampilkan daftar produk, meminta harga satu pemeriksaan, menjalankannya, dan membaca hasilnya tanpa menulis kode integrasi. Satu URL melayani semua pelanggan: Anda terhubung dengan kunci API Anda sendiri, dan setiap biaya dibebankan ke saldo Anda sendiri.

Titik koneksi

Pengaturan	Nilai
URL	https://mcp.zelnum.com/mcp
Transport	Streamable HTTP
Kredensial	Authorization: Bearer YOUR_KEY_HERE

Kredensialnya adalah kunci API yang sama dengan yang dipakai panggilan REST Anda. Buat, ganti, dan cabut kunci tersebut di API Center pada konsol.

Menghubungkan klien

Tiga langkah, tanpa memasang apa pun.

1. Buat kunci. Buat API key di API Center pada konsol — kunci yang sama dengan yang dipakai panggilan REST Anda. Lihat Authentication.

2. Tambahkan server. Cursor dan klien lain yang membaca peta mcpServers standar dapat memakai entri ini apa adanya:

{
  "mcpServers": {
    "zelnum": {
      "url": "https://mcp.zelnum.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_KEY_HERE"
      }
    }
  }
}

Claude menerima dua nilai yang sama lewat dialog konektor kustomnya — URL, dan header Authorization yang membawa kunci Anda.

3. Periksa koneksi. Minta agen menyebutkan produk realtime apa saja yang bisa diperiksa. Koneksi yang sehat akan menjawab dengan memanggil list_products, yang bersifat hanya-baca dan gratis, jadi pemeriksaan ini tidak memakan biaya. Sebaliknya, 401 berarti kunci hilang, dicabut, atau tidak diterima platform.

Alat

Alat	Fungsinya	Berbayar
list_products	Katalog produk aktif beserta ID, slug, dan series. Hanya baca.	Tidak
get_balance	Saldo akun yang menjadi identitas koneksi ini. Hanya baca.	Tidak
quote_realtime_check	Harga resmi untuk satu pemeriksaan. Satu-satunya sumber harga yang pantas dipercaya agen.	Gratis
check_realtime	Menjalankan satu pemeriksaan realtime terhadap maksimal sepuluh produk.	Ya
create_bulk_task	Mengirim daftar inline untuk tugas massal asinkron.	Ya
get_task_status	Progres dan penghitung penagihan sebuah tugas massal.	Tidak
get_task_result	Metadata hasil dan tautan unduhan terautentikasi untuk tugas yang sudah selesai.	Tidak

Yang bisa Anda katakan

Di atas adalah alatnya; di bawah ini kalimat yang Anda ketik. Semuanya dilayani oleh alat yang sudah ada — tidak ada susunan kata yang diperlakukan khusus.

Katakan ini	Yang terjadi
Produk apa saja yang bisa saya periksa secara realtime?	Memanggil list_products dan menjawab dengan ID yang perlu dipakai. Gratis.
Berapa sisa saldo saya?	Memanggil get_balance untuk kunci yang Anda pakai terhubung. Gratis.
Berapa biaya memeriksa +14155550123 di WhatsApp?	Memanggil quote_realtime_check dan menampilkan harganya. Gratis, dan tidak ada yang ditagih.
Lanjut, pakai harga itu.	Memanggil check_realtime untuk produk dalam penawaran dan menagih sejumlah yang ditawarkan.
Periksa 200 nomor ini di WhatsApp dan beri tahu saya kalau sudah selesai.	Memanggil create_bulk_task, lalu menanyakan get_task_status dan melaporkan kemajuannya.
Tugas itu sudah selesai? Kirim tautan unduhannya.	Memanggil get_task_result dan mengembalikan tautan terautentikasi.

Dua kebiasaan yang layak dijaga:

• Tanyakan harganya lebih dulu. Setiap alat berbayar menjawab dengan penawaran sebelum menagih, jadi bertanya berapa biayanya selalu gratis. Hanya langkah konfirmasi yang memindahkan uang.
• Sebutkan field country bila nomornya bukan E.164. +14155550123 sudah membawa negaranya; 0812345678 tidak, dan gateway menolak menebak.

Mengonfirmasi biaya

Alat berbayar tidak pernah menagih pada panggilan pertamanya. Bila dipanggil tanpa confirmed, alat itu justru mengembalikan payload konfirmasi — produk, jumlah, dan perkiraan biaya — beserta quote_token yang menandatangani input persis. Konfirmasi dengan mengulang panggilan yang sama dengan:

1. confirmed diatur ke true
2. quote_token dari payload tersebut
3. quoted_total, persis jumlah yang ditampilkan kepada Anda
4. identitas, produk, dan field country yang sama

Agen tidak pernah menyediakan kunci idempotensi sendiri: gateway menurunkannya dari kuotasi bertanda tangan, sehingga kuotasi yang sama dan sudah disetujui mempertahankan kunci yang sama pada percobaan ulang, sambungan ulang, dan restart gateway. Biaya yang berbeda memerlukan kuotasi baru. Bila timeout membuat hasilnya tidak diketahui, ulangi panggilan yang identik daripada mengubah parameter.

Jangan pernah mengonfirmasi diam-diam

Agen wajib menampilkan perkiraan biaya dan memperoleh persetujuan eksplisit sebelum menyalakan penanda konfirmasi. Kuotasi kedaluwarsa setelah lima menit, dan kuotasi yang snapshot harganya sudah bergeser ditolak, bukan ditagih dengan harga baru.

Aturan identitas

Aturan identitas mengikuti kontrak REST, jadi apa yang divalidasi agen adalah apa yang diterima API:

• Field country tidak dikirim — identitas harus berupa nomor E.164 dengan awalan +.
• Field country dikirim — kode ISO dua huruf kapital, dan identitasnya lalu berupa nomor nasional atau nomor E.164.
• Negara tidak pernah disimpulkan dari nomor nasional yang ambigu seperti 0812345678, yang cocok dengan beberapa negara. Kosongkan country hanya bila nomornya sudah E.164 lengkap.
• Tugas massal pada produk telepon mewajibkan field country yang eksplisit.

Pagar pengaman dana

Ada empat pagar pengaman antara agen dan saldo Anda:

1. Kuotasi bertanda tangan. Platform membaca harga terkini dan mengembalikan kuotasi terenkripsi yang mengikat akun, input persis, produk, dan snapshot harga. Input yang berubah, kuotasi kedaluwarsa, atau harga yang bergeser ditolak sebelum ada yang ditagih.
2. Idempotensi deterministik. Kunci idempotensi berasal dari kuotasi bertanda tangan, bukan dari model, sehingga tidak ada penyusunan kata permintaan yang bisa mengubah satu persetujuan menjadi dua tagihan.
3. Batas per kunci. Plafon biaya harian dan batas bawah saldo diberlakukan per kunci API, dan setiap reservasi diserialkan sebelum panggilan ke platform, sehingga agen yang berjalan bersamaan tidak dapat melewatinya.
4. Gagal berarti ditolak. Jika saldo tidak dapat dibaca atau kembali dalam bentuk yang rusak, panggilan berbayar ditolak alih-alih dijalankan tanpa pengaman.

Error dan batasan

• Kredensial yang hilang atau rusak ditolak dengan HTTP 401 sebelum permintaan mencapai platform.
• Kunci yang tidak diterima platform kembali sebagai error alat yang membawa status dan body dari platform, sehingga agen melaporkannya alih-alih mencoba ulang secara membabi buta.
• Batas laju, kode error, dan unduhan hasil berperilaku persis seperti melalui REST — gateway tidak menambahkan kontrak kedua yang harus dipelajari.

Langkah berikutnya

• Authentication — buat kunci yang akan Anda pakai untuk terhubung.
• Realtime check — endpoint di balik check_realtime.
• Bulk workflow — jalur asinkron di balik create_bulk_task.
• Error codes — kode yang dikembalikan platform.