Claude MCP API: Hubungkan APIPedia ke Claude dan Agen AI

MCP (Model Context Protocol) adalah protokol terbuka yang membuat asisten AI seperti Claude bisa memanggil alat dan data eksternal dengan format standar. APIPedia menyediakan MCP server Indonesia di https://api.apipedia.id/v1/mcp, sehingga Claude dapat langsung mengecek kode pos, gempa BMKG, ongkir, atau OCR KTP memakai kunci API apk_ milikmu.

Artikel ini membahas cara menyambungkan server MCP APIPedia ke Claude Desktop, claude.ai, Claude Code, dan Cursor. Kita juga akan melihat cara autentikasinya, tool apa saja yang tersedia, dan kenapa URL berisi kunci harus diperlakukan sebagai rahasia.

Apa itu MCP dan kenapa berguna untuk developer Indonesia?

Model Context Protocol adalah standar yang diperkenalkan Anthropic untuk menghubungkan model bahasa ke sumber data dan aksi di luar model. Satu server MCP mendeklarasikan daftar tool lengkap dengan nama, deskripsi, dan skema input. Klien MCP seperti Claude Desktop membaca daftar itu, lalu model memutuskan sendiri kapan sebuah tool perlu dipanggil.

Tanpa MCP, kamu harus menulis kode perekat untuk setiap API: membuat fungsi, mendefinisikan skema, menangani error, lalu menyuapkannya ke model. Dengan MCP, semua itu sudah dikemas di sisi server. Kamu cukup menempelkan satu URL dan satu kunci.

Untuk developer Indonesia, nilai praktisnya jelas. Banyak pertanyaan sehari-hari butuh data lokal: kode pos sebuah kelurahan, gempa terbaru dari BMKG, jadwal sholat, hari libur nasional, atau validasi format NIK. Model AI umum tidak punya data itu secara langsung. Server MCP APIPedia menjembatani celah tersebut lewat endpoint REST yang sama dengan yang kamu panggil dari aplikasi.

Bagaimana cara kerja MCP server APIPedia?

Server MCP APIPedia berjalan di POST /v1/mcp dengan transport Streamable HTTP. Server ini bersifat stateless: setiap request POST membuat instans server baru tanpa header Mcp-Session-Id. Karena itu, method GET dan DELETE dijawab dengan status 405, dan respons dikirim sebagai JSON biasa, bukan aliran SSE.

Saat sebuah tool dipanggil, server MCP meneruskan kunci API kamu apa adanya ke endpoint REST aslinya. Artinya cakupan kunci, kuota, dan pencatatan pemakaian tetap ditegakkan oleh endpoint tersebut. MCP tidak membuka jalan pintas: memanggil gempa_terkini lewat Claude sama dengan memanggil GET /v1/gempa/terkini dari curl.

Hasil setiap tool berupa teks yang memuat baris status HTTP plus amplop JSON standar APIPedia: { is_success, message, data }. Pesan error umumnya berbahasa Indonesia dan menjelaskan cara memperbaikinya, sehingga Claude bisa membacanya dan memberi tahu kamu apa yang salah.

Ringkasan teknis server

Aspek	Nilai
URL	https://api.apipedia.id/v1/mcp
Transport	Streamable HTTP, mode stateless (hanya POST)
Format respons	JSON-RPC 2.0, isi tool berupa amplop { is_success, message, data }
Autentikasi	Header Authorization: Bearer apk_xxx atau query ?key=apk_xxx
OAuth	Belum tersedia
Batas waktu per tool	90 detik (OCR dan downloader bisa memakan waktu lama)
Gambar dari URL	Field image_url diunduh server, maksimal 10 MB, alamat privat ditolak

Bagaimana cara autentikasi ke MCP APIPedia?

Autentikasi memakai kunci API berawalan apk_ yang dibuat di konsol APIPedia, menu Token API. Kunci hanya ditampilkan sekali saat dibuat, jadi simpan baik-baik. OAuth belum diimplementasikan, sehingga untuk saat ini ada dua cara mengirim kunci.

Cara pertama: header Bearer. Kirim Authorization: Bearer apk_xxx. Ini cara yang disarankan karena kunci tidak ikut tercatat sebagai bagian URL. Claude Desktop (lewat konfigurasi), Claude Code, dan Cursor mendukung header kustom.

Cara kedua: parameter query. Tambahkan ?key=apk_xxx di belakang URL MCP. Cara ini ada karena connector kustom di claude.ai belum bisa menyetel header sendiri. Kalau header dan query sama-sama dikirim, header yang dipakai.

Kalau kunci tidak dikirim atau tidak valid, server menjawab HTTP 401 dengan header WWW-Authenticate dan pesan error JSON-RPC yang menjelaskan dua cara di atas.

Peringatan: URL berisi ?key= adalah rahasia

Siapa pun yang memegang URL ?key=apk_... bisa memakai saldo dan kuota akunmu. Jangan menempelnya di chat, tangkapan layar, issue, atau repositori.

URL dengan query string juga bisa terekam di log akses proxy. Gunakan kunci khusus untuk MCP dengan cakupan sempit dan masa berlaku, lalu cabut di halaman Token begitu kamu curiga kunci bocor. Server sendiri mengirim header Cache-Control: no-store pada setiap respons MCP.

Langkah menghubungkan APIPedia ke Claude

Sebelum mulai, pastikan kamu sudah punya akun dan kunci API. Paket Free gratis selamanya dengan kuota 500 request per hari dan rate limit 10 request per detik, cukup untuk mencoba semua langkah di bawah. Ingat, setiap panggilan tool lewat MCP dihitung ke kuota seperti panggilan REST biasa.

claude.ai (web)

1. Buka Settings, lalu Connectors.
2. Klik Add custom connector.
3. Tempel URL dengan kunci: https://api.apipedia.id/v1/mcp?key=apk_xxx. Connector web belum bisa mengirim header kustom.
4. Biarkan pengaturan OAuth kosong, lalu klik Add.
5. Di percakapan baru, aktifkan APIPedia dari menu tools.

Claude Desktop

Cara tercepat sama dengan versi web: Settings, Connectors, Add custom connector, beri nama "APIPedia", lalu tempel URL dengan kunci. Kalau tidak ingin kunci berada di URL, pakai claude_desktop_config.json (Settings, Developer, Edit Config) dengan jembatan mcp-remote yang mengirim kunci sebagai header:

{
  "mcpServers": {
    "apipedia": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://api.apipedia.id/v1/mcp",
        "--header", "Authorization:${APIPEDIA_AUTH}"
      ],
      "env": { "APIPEDIA_AUTH": "Bearer apk_xxx" }
    }
  }
}

Claude Code

Jalankan perintah berikut di terminal. Tambahkan --scope user supaya server tersedia di semua proyek.

claude mcp add --transport http apipedia https://api.apipedia.id/v1/mcp \
  --header "Authorization: Bearer apk_xxx"

Cursor dan agen lain

Cursor membaca ~/.cursor/mcp.json (global) atau .cursor/mcp.json di proyek. Klien MCP lain yang mendukung Streamable HTTP dengan header kustom bisa memakai pola yang sama.

{
  "mcpServers": {
    "apipedia": {
      "url": "https://api.apipedia.id/v1/mcp",
      "headers": { "Authorization": "Bearer apk_xxx" }
    }
  }
}

Tool apa saja yang tersedia di MCP APIPedia?

Server mendaftarkan puluhan tool yang dikelompokkan per kategori. Setiap tool memetakan satu endpoint REST, dan deskripsinya mencantumkan method serta path aslinya, misalnya [Gempa] GET /v1/gempa/terkini. Tool list_apis mengembalikan seluruh daftar per kategori, endpoint yang segera hadir, dan katalog produk, jadi itu tempat terbaik untuk mulai.

Kategori	Contoh tool
Wilayah dan Kode Pos	list_provinsi, list_kabupaten, cari_kodepos, detail_kodepos
Identitas dan keuangan	parse_nik, parse_npwp, parse_qris, validate_rekening, kurs_convert
Gempa dan Cuaca (BMKG)	gempa_terkini, gempa_m5, gempa_dirasakan, prakiraan_cuaca
Tanggal, Libur, Sholat	cek_libur, hitung_hari_kerja, jadwal_sholat
Ongkir	ongkir_search, cek_ongkir, ongkir_couriers
OCR dan Vision	ocr_ktp, ocr_sim, ocr_general, face_match, remove_background
Koneksi pihak ketiga	gmail_send, calendar_create_event, docs_create, linkedin_post, github_create_issue
Akun dan Dompet	get_quota, get_usage, get_logs, get_wallet
Dukungan dan Blog	create_ticket, blog_list_posts, blog_get_post

Tool yang butuh koneksi akun

Tool Gmail, Google Calendar, Docs, Sheets, Drive, Meet, LinkedIn, dan GitHub butuh akun yang sudah terhubung di halaman Koneksi konsol. Claude bisa mengeceknya dengan list_connections, lalu memanggil connect_account dan memintamu membuka redirectUrl yang dikembalikan. Server juga menginstruksikan model agar meminta konfirmasi sebelum aksi yang mengirim sesuatu atas namamu, seperti email atau postingan.

Tool gambar menerima URL

Tool seperti ocr_ktp menerima image_base64 atau image_url. Kalau kamu memberi URL publik, server MCP mengunduhnya (maksimal 10 MB) lalu mengirim base64 ke endpoint. Alamat privat atau loopback ditolak untuk mencegah pemindaian jaringan internal. Detail endpoint OCR ada di artikel API OCR KTP Indonesia.

Bagaimana menguji MCP server dengan curl dan JavaScript?

Karena transportnya HTTP biasa, kamu bisa menguji server tanpa Claude sama sekali. Ini berguna untuk memastikan kunci valid sebelum menempelkannya ke klien. Kirim header Accept yang memuat application/json dan text/event-stream sesuai spesifikasi Streamable HTTP.

Melihat daftar tool

curl -X POST "https://api.apipedia.id/v1/mcp" \
  -H "Authorization: Bearer apk_xxx" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Memanggil satu tool

Contoh berikut memanggil gempa_terkini, yang meneruskan data gempa terakhir dari BMKG. Penjelasan field responsnya ada di artikel API gempa dan cuaca BMKG.

curl -X POST "https://api.apipedia.id/v1/mcp" \
  -H "Authorization: Bearer apk_xxx" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": { "name": "gempa_terkini", "arguments": {} }
  }'

Memanggil tool dari JavaScript

Untuk agen buatan sendiri, cukup fetch dengan body JSON-RPC tools/call. Simpan kunci di variabel lingkungan, jangan ditulis langsung di kode.

const MCP_URL = "https://api.apipedia.id/v1/mcp";

async function callTool(name, args = {}) {
  const res = await fetch(MCP_URL, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.APIPEDIA_KEY}`, // apk_xxx
      "Content-Type": "application/json",
      Accept: "application/json, text/event-stream",
    },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: Date.now(),
      method: "tools/call",
      params: { name, arguments: args },
    }),
  });
  const body = await res.json();
  if (body.error) throw new Error(body.error.message);
  return body.result; // { content: [...], isError? }
}

const hasil = await callTool("cari_kodepos", { q: "Cibubur", limit: 5 });
console.log(hasil.content[0].text);

Kalau hasilnya memuat isError: true, baca teks di content[0].text. Isinya status HTTP dan amplop JSON yang menjelaskan penyebabnya, misalnya parameter wajib yang kosong atau kuota yang habis.

Contoh prompt yang bisa langsung dicoba

Setelah connector aktif, kamu tidak perlu menyebut nama tool. Claude memilihnya sendiri berdasarkan deskripsi. Beberapa prompt yang memanfaatkan data lokal:

• "Ada gempa apa saja yang dirasakan masyarakat menurut BMKG?"
• "Cari kode pos untuk Cibubur, lalu tampilkan kecamatan dan kotanya." Lihat juga API data wilayah dan kode pos.
• "Berapa estimasi ongkir 2 kg dari Bandung ke Surabaya?" Tool cek_ongkir memakai data tarif statis, bukan tarif live kurir. Detailnya di cara cek ongkir lewat API.
• "Berapa hari kerja antara 1 Desember dan 31 Desember tahun ini?"
• "Sisa kuota APIPedia saya berapa?" Claude akan memanggil get_quota.

Pertanyaan yang sering diajukan

Apakah memakai MCP menghabiskan kuota?

Ya. Setiap panggilan tool diteruskan ke endpoint REST dengan kunci kamu, sehingga dihitung ke kuota dan penagihan akun persis seperti panggilan biasa. Di paket Free, batasnya 500 request per hari dan 10 request per detik.

Apakah sudah mendukung OAuth?

Belum. Untuk sementara autentikasi memakai kunci API apk_ lewat header Authorization: Bearer atau parameter ?key=. Saat menambahkan custom connector di claude.ai, biarkan kolom OAuth kosong.

Kenapa request GET ke /v1/mcp ditolak?

Server berjalan dalam mode stateless, jadi tidak ada sesi atau aliran SSE dari server. GET dan DELETE dijawab 405 dengan header Allow: POST. Semua komunikasi MCP dilakukan lewat POST.

Apa yang harus dilakukan kalau URL ?key= tidak sengaja tersebar?

Segera cabut kunci itu di halaman Token API konsol, lalu buat kunci baru. Sejak awal, sebaiknya pakai kunci khusus MCP dengan cakupan sempit dan masa berlaku supaya dampak kebocoran terbatas.

Bisakah dipakai selain Claude?

Bisa. Server mengikuti spesifikasi MCP dengan transport Streamable HTTP, jadi klien lain seperti Cursor atau agen buatan sendiri bisa terhubung selama mendukung transport tersebut dan bisa mengirim kunci.

Mulai hubungkan Claude ke data Indonesia

Satu URL, satu kunci, dan Claude langsung bisa menjawab pertanyaan yang butuh data lokal Indonesia. Daftar gratis di console.apipedia.id, buat kunci di menu Token API, lalu buka panel MCP di dokumentasi API konsol untuk menyalin URL dan konfigurasi yang siap tempel.