⭐ Antarmuka Utama

MCP Server

Hubungkan AI agent Anda langsung ke data kode pos Indonesia. Dengan Model Context Protocol, Claude, Cursor, dan VS Code dapat mencari, memvalidasi, dan menelusuri data lokasi — tanpa menulis satu baris kode HTTP pun.

Streamable HTTP Transport

7 Tools Siap Pakai

Bearer Token Auth

Apa itu MCP?

Model Context Protocol (MCP) adalah protokol terbuka yang memungkinkan AI agent berinteraksi dengan layanan eksternal secara terstandarisasi. Alih-alih menulis kode HTTP manual untuk setiap API, AI agent cukup memanggil tools yang disediakan oleh MCP Server — sama seperti memanggil fungsi lokal.

Dengan MCP Server Kode Pos API, AI agent Anda mendapatkan kemampuan bawaan untuk mencari kode pos, menelusuri hierarki wilayah Indonesia (provinsi → kota → kecamatan → kelurahan), memvalidasi kode pos, dan mendapatkan detail lokasi — semua dalam percakapan natural language.

MCP Server Kode Pos API menggunakan transport Streamable HTTP, yang kompatibel dengan klien MCP terbaru seperti Claude Desktop, Cursor, dan VS Code. Endpoint: https://api.kodepos.dev/api/kodepos/mcp

Konfigurasi

Tambahkan konfigurasi berikut ke file pengaturan MCP klien Anda. API key dikirim melalui header Authorization: Bearer. Ganti kp_live_xxxxxxxxxxxxxxxx dengan API key Anda.

MCP Server mengirim API key melalui header Authorization: Bearer — format yang sama dengan REST dan GraphQL API.

File: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "kodepos": {
      "url": "https://api.kodepos.dev/api/kodepos/mcp",
      "headers": {
        "Authorization": "Bearer kp_live_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

Alat yang Tersedia

MCP Server Kode Pos API menyediakan 7 tools yang dapat dipanggil langsung oleh AI agent:

Tool	Deskripsi	Parameter Utama
search_postal_code	Cari kode pos berdasarkan kata kunci (fuzzy search)	q (wajib), first, after
get_provinces	Daftar seluruh provinsi di Indonesia	first, after
get_cities	Daftar kota/kabupaten berdasarkan kode provinsi	provinceCode (wajib), include.province, first, after
get_districts	Daftar kecamatan berdasarkan kode kota/kabupaten	cityCode (wajib), include.city, first, after
get_subdistricts	Daftar kelurahan/desa berdasarkan kode kecamatan	districtCode (wajib), include.district, first, after
get_location_details	Detail hierarki lokasi lengkap berdasarkan kode pos	postalCode (wajib)
validate_postal_code	Validasi apakah kode pos valid dan sesuai lokasi	postalCode (wajib)

Semua tools dengan daftar mendukung cursor-based pagination melalui parameter first dan after. Gunakan nilai endCursor dari response sebelumnya sebagai after untuk halaman berikutnya.

Detail Tool

Dokumentasi lengkap setiap tool termasuk parameter, contoh input yang dikirim AI agent, dan contoh output yang dikembalikan server.

Paling Sering Digunakan

search_postal_code

Cari kode pos berdasarkan kata kunci. Melakukan pencarian fuzzy terhadap nama kelurahan/desa, kode pos, nama kecamatan, nama kota/kabupaten, dan nama provinsi.

Parameter	Tipe	Wajib	Deskripsi	Default
q	string	Wajib	Kata kunci pencarian (minimal 2 karakter). Bisa berupa nama kelurahan, kecamatan, kota, provinsi, atau kode pos.	—
first	number	Opsional	Jumlah item per halaman (1-100)	20
after	string?	Opsional	Kursor halaman berikutnya (dari respons sebelumnya)	—

Parameter q mendukung pencarian fuzzy — cukup ketik sebagian nama lokasi dan server akan mencocokkan secara otomatis.

Contoh Input

{
  "q": "menteng"
}

Contoh Output

{
  "items": [
    {
      "code": "31.73.01.1002",
      "name": "Menteng",
      "postalCode": "10310",
      "district": {
        "code": "31.73.01",
        "name": "Menteng"
      },
      "city": {
        "code": "31.73",
        "name": "Kota Jakarta Pusat"
      },
      "province": {
        "code": "31",
        "name": "DKI Jakarta"
      }
    }
  ],
  "pagination": {
    "hasNextPage": true,
    "endCursor": "eyJvZmZzZXQiOjJ9"
  }
}

Eksklusif MCP

get_location_details

Dapatkan detail hierarki lokasi lengkap berdasarkan kode pos. Mengembalikan seluruh rantai: kelurahan/desa → kecamatan → kota/kabupaten → provinsi.

Parameter	Tipe	Wajib	Deskripsi	Default
postalCode	string	Wajib	Kode pos yang ingin dilihat detailnya (contoh: "23511")	—

Jika kode pos tidak ditemukan, respons akan berisi found: false dengan pesan penjelasan.

Contoh Input

{
  "postalCode": "10310"
}

Contoh Output

{
  "postalCode": "10310",
  "found": true,
  "locations": [
    {
      "code": "31.73.01.1002",
      "name": "Menteng",
      "postalCode": "10310",
      "district": {
        "code": "31.73.01",
        "name": "Menteng"
      },
      "city": {
        "code": "31.73",
        "name": "Kota Jakarta Pusat"
      },
      "province": {
        "code": "31",
        "name": "DKI Jakarta"
      }
    }
  ]
}

Eksklusif MCP

validate_postal_code

Validasi apakah sebuah kode pos ada dan sesuai dengan lokasi tertentu. Mengembalikan status valid, jumlah lokasi, dan daftar lokasi yang cocok.

Parameter	Tipe	Wajib	Deskripsi	Default
postalCode	string	Wajib	Kode pos yang ingin divalidasi (contoh: "23511")	—

Untuk kode pos yang tidak valid, respons akan berisi valid: false dengan locationCount: 0 dan locations kosong.

Contoh Input

{
  "postalCode": "10310"
}

Contoh Output

{
  "valid": true,
  "postalCode": "10310",
  "locationCount": 1,
  "locations": [
    {
      "code": "31.73.01.1002",
      "name": "Menteng",
      "postalCode": "10310",
      "district": {
        "code": "31.73.01",
        "name": "Menteng"
      },
      "city": {
        "code": "31.73",
        "name": "Kota Jakarta Pusat"
      },
      "province": {
        "code": "31",
        "name": "DKI Jakarta"
      }
    }
  ]
}

get_cities

Daftar kota/kabupaten berdasarkan kode provinsi. Sertakan hierarki provinsi induk dengan parameter include.

Parameter	Tipe	Wajib	Deskripsi	Default
provinceCode	string	Wajib	Kode provinsi (contoh: "11" untuk Aceh, "31" untuk DKI Jakarta)	—
include.province	boolean	Opsional	Sertakan data provinsi induk dalam respons	false
first	number	Opsional	Jumlah item per halaman (1-100)	20
after	string?	Opsional	Kursor halaman berikutnya	—

Gunakan include: { province: true } untuk menyertakan data provinsi induk dalam setiap item kota, berguna untuk menghindari pemanggilan get_provinces terpisah.

Contoh Input

{
  "provinceCode": "31",
  "include": {
    "province": true
  },
  "first": 10
}

Contoh Output

{
  "items": [
    {
      "code": "31.71",
      "name": "Kota Jakarta Selatan",
      "province": {
        "code": "31",
        "name": "DKI Jakarta"
      }
    },
    {
      "code": "31.72",
      "name": "Kota Jakarta Timur",
      "province": {
        "code": "31",
        "name": "DKI Jakarta"
      }
    },
    {
      "code": "31.73",
      "name": "Kota Jakarta Pusat",
      "province": {
        "code": "31",
        "name": "DKI Jakarta"
      }
    }
  ],
  "pagination": {
    "hasNextPage": true,
    "endCursor": "eyJvZmZzZXQiOjN9"
  }
}

get_subdistricts

Daftar kelurahan/desa berdasarkan kode kecamatan. Sertakan hierarki kecamatan, kota, dan provinsi induk dengan parameter include.

Parameter	Tipe	Wajib	Deskripsi	Default
districtCode	string	Wajib	Kode kecamatan (contoh: "11.01.01" untuk Sukajaya, "31.73.01" untuk Menteng)	—
include.district	boolean	Opsional	Sertakan data kecamatan induk beserta kota dan provinsi	false
first	number	Opsional	Jumlah item per halaman (1-100)	20
after	string?	Opsional	Kursor halaman berikutnya	—

Gunakan include: { district: true } untuk mendapatkan hierarki lengkap kecamatan → kota → provinsi dalam setiap item kelurahan. Sangat berguna untuk mendapatkan konteks lokasi tanpa pemanggilan tambahan.

Contoh Input

{
  "districtCode": "31.73.01",
  "include": {
    "district": true
  }
}

Contoh Output

{
  "items": [
    {
      "code": "31.73.01.1001",
      "name": "Pegangsaan",
      "postalCode": "10320",
      "district": {
        "code": "31.73.01",
        "name": "Menteng",
        "city": {
          "code": "31.73",
          "name": "Kota Jakarta Pusat",
          "province": {
            "code": "31",
            "name": "DKI Jakarta"
          }
        }
      }
    },
    {
      "code": "31.73.01.1002",
      "name": "Menteng",
      "postalCode": "10310",
      "district": {
        "code": "31.73.01",
        "name": "Menteng",
        "city": {
          "code": "31.73",
          "name": "Kota Jakarta Pusat",
          "province": {
            "code": "31",
            "name": "DKI Jakarta"
          }
        }
      }
    }
  ],
  "pagination": {
    "hasNextPage": false,
    "endCursor": null
  }
}

get_provinces

Daftar seluruh provinsi di Indonesia dengan paginasi berbasis kursor.

Parameter	Tipe	Wajib	Deskripsi	Default
first	number	Opsional	Jumlah item per halaman (1-100)	20
after	string?	Opsional	Kursor halaman berikutnya (dari respons sebelumnya)	—

Contoh Input

{
  "first": 10
}

Contoh Output

{
  "items": [
    { "code": "11", "name": "Aceh" },
    { "code": "12", "name": "Sumatera Utara" },
    { "code": "13", "name": "Sumatera Barat" }
  ],
  "pagination": {
    "hasNextPage": true,
    "endCursor": "eyJvZmZzZXQiOjN9"
  }
}

get_districts

Daftar kecamatan berdasarkan kode kota/kabupaten. Sertakan hierarki kota dan provinsi induk dengan parameter include.

Parameter	Tipe	Wajib	Deskripsi	Default
cityCode	string	Wajib	Kode kota/kabupaten (contoh: "11.01" untuk Kota Sabang, "31.73" untuk Kota Jakarta Pusat)	—
include.city	boolean	Opsional	Sertakan data kota induk beserta provinsi	false
first	number	Opsional	Jumlah item per halaman (1-100)	20
after	string?	Opsional	Kursor halaman berikutnya	—

Gunakan include: { city: true } untuk mendapatkan hierarki kota → provinsi dalam setiap item kecamatan.

Contoh Input

{
  "cityCode": "31.73",
  "include": {
    "city": true
  }
}

Contoh Output

{
  "items": [
    {
      "code": "31.73.01",
      "name": "Menteng",
      "city": {
        "code": "31.73",
        "name": "Kota Jakarta Pusat",
        "province": {
          "code": "31",
          "name": "DKI Jakarta"
        }
      }
    }
  ],
  "pagination": {
    "hasNextPage": true,
    "endCursor": "eyJvZmZzZXQiOjF9"
  }
}

Contoh Interaksi

Setelah MCP Server terkonfigurasi, AI agent Anda dapat langsung menggunakan tools — berikut contoh percakapan nyata:

👤 User:

Cari kode pos untuk Menteng di Jakarta

🤖 AI Agent:

Memanggil tool search_postal_code dengan parameter { q: "menteng" }

→ Menteng, Kec. Menteng, Kota Jakarta Pusat, DKI Jakarta — Kode Pos 10310

👤 User:

Apa saja kelurahan di Kecamatan Menteng?

🤖 AI Agent:

Memanggil tool get_subdistricts dengan parameter { districtCode: "31.73.01", include: { district: true } }

→ Pegangsaan (10320), Menteng (10310), Cikini (10330), Kebon Sirih (10210), Gondangdia (10350), dan lainnya

👤 User:

Validasi kode pos 10310

🤖 AI Agent:

Memanggil tool validate_postal_code dengan parameter { postalCode: "10310" }

→ Valid — Kode pos 10310 sesuai dengan 1 lokasi: Menteng, Kota Jakarta Pusat, DKI Jakarta

👤 User:

Detail lokasi untuk kode pos 10310

🤖 AI Agent:

Memanggil tool get_location_details dengan parameter { postalCode: "10310" }

→ Kelurahan Menteng → Kec. Menteng → Kota Jakarta Pusat → DKI Jakarta

Autentikasi & Kredit

MCP Server menggunakan API key dan sistem kredit yang sama dengan REST dan GraphQL API, dengan beberapa perbedaan penting pada cara autentikasi:

Alur Autentikasi MCP

Validasi API Key — API key diekstrak dari header Authorization: Bearer dan divalidasi terhadap database

Rate Limiting — Cek batas per menit menggunakan Redis INCR + EXPIRE (window 60 detik)

Cek Kredit — Fast-path rejection jika kredit ≤ 0. Deduksi kredit hanya dilakukan setelah tool berhasil dieksekusi

Deduksi Kredit — Hanya pemanggilan tool yang berhasil yang dikenakan biaya (1 kredit per tool call)

Tracking Penggunaan — Data penggunaan di-buffer ke Redis setelah tool call selesai

Penting: MCP Server menggunakan header Authorization: Bearer — format yang sama digunakan di REST dan GraphQL API. Cukup satu API key untuk semua interface.

Setiap pemanggilan tool MCP yang berhasil mengonsumsi 1 kredit, sama seperti request ke REST atau GraphQL API. Pemanggilan yang gagal (error, rate limit, dll.) tidak dikenakan biaya.

Aspek	Detail
Metode Autentikasi	Authorization: Bearer kp_live_xxx
Biaya per Tool Call	1 kredit (hanya jika berhasil)
Rate Limit	100 request/menit per akun
Transport	Streamable HTTP
Endpoint	https://api.kodepos.dev/api/kodepos/mcp