⭐ Antarmuka Utama

MCP Server

Hubungkan platform automasi dan AI agent Anda langsung ke data kode pos Indonesia. Dengan Model Context Protocol, n8n, OpenClaw, dan klien MCP lainnya dapat mencari, memvalidasi, dan menelusuri data lokasi — tanpa kode integrasi HTTP.

Streamable HTTP Transport

10 Tools Siap Pakai

Bearer Token Auth

Apa itu MCP?

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

Dengan MCP Server Kode Pos API, platform automasi dan 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 tanpa kode integrasi HTTP.

MCP Server Kode Pos API menggunakan transport Streamable HTTP, yang kompatibel dengan platform automasi seperti n8n, OpenClaw, dan klien MCP lainnya. Endpoint: https://api.kodepos.dev/kodepos/mcp

Konfigurasi

Tambahkan konfigurasi berikut ke platform automasi atau klien MCP 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. Satu API key untuk semua interface.

Platform Automasi & AI Agent

n8n memiliki node MCP Client Tool bawaan yang mendukung transport Streamable HTTP. Ikuti langkah berikut untuk menghubungkan ke MCP Server Kode Pos API:

1. Buka workflow n8n Anda
2. Tambahkan node "MCP Client Tool"
3. Buat credential baru tipe "MCP Client API"
4. Pilih transport "Streamable HTTP"
5. Masukkan URL dan API key

Konfigurasi Credential

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

Setelah credential dibuat, node MCP Client Tool akan otomatis menemukan semua 10 tools yang tersedia.

Coding Assistant

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

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

Alat yang Tersedia

MCP Server Kode Pos API menyediakan 10 tools yang dapat dipanggil oleh platform automasi dan AI agent:

Tool	Deskripsi	Parameter Utama	Kredit
search_postal_code	Cari kode pos berdasarkan kata kunci (fuzzy search)	q (wajib), first, after	1
get_provinces	Daftar seluruh provinsi di Indonesia	first, after	1
get_cities	Daftar kota/kabupaten berdasarkan kode provinsi	provinceCode (wajib), include.province, first, after	1
get_districts	Daftar kecamatan berdasarkan kode kota/kabupaten	cityCode (wajib), include.city, first, after	1
get_subdistricts	Daftar kelurahan/desa berdasarkan kode kecamatan	districtCode (wajib), include.district, first, after	1
get_location_details	Detail hierarki lokasi lengkap berdasarkan kode pos	postalCode (wajib)	1
validate_postal_code	Validasi apakah kode pos valid dan sesuai lokasi	postalCode (wajib)	1
validate_postal_codes_batch	Validasi beberapa kode pos sekaligus (1–50 per call)	postalCodes (wajib, array)	1
search_postal_codes_batch	Cari beberapa kata kunci sekaligus (1–20 per call)	queries (wajib, array), first	1
get_kodepos_api_status	Cek status API dan versi Gratis	—	0

Semua tools dengan daftar mendukung paginasi berbasis kursor 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 dan lokasi Indonesia berdasarkan kata kunci. Mendukung pencarian fuzzy terhadap nama kelurahan/desa, kode pos, nama kecamatan, nama kota/kabupaten, dan nama provinsi. Gunakan tool ini jika Anda memiliki nama atau kode parsial dan perlu menemukan lokasi yang cocok. Untuk pencarian kode pos yang tepat, gunakan `get_location_details`; untuk validasi alamat, gunakan `validate_postal_code`.

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

{
  "success": true,
  "data": {
    "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

Lihat hierarki lokasi lengkap berdasarkan kode pos. Mengembalikan semua kelurahan/desa yang menggunakan kode pos tersebut, masing-masing dengan hierarki administratif lengkap: kelurahan → kecamatan → kota/kabupaten → provinsi. Catatan: satu kode pos Indonesia dapat mencakup beberapa kelurahan. Gunakan `validate_postal_code` jika hanya perlu mengecek apakah kode pos ada.

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

Jika kode pos tidak ditemukan, respons akan berisi success: false dengan error code NOT_FOUND.

Contoh Input

{
  "postalCode": "10310"
}

Contoh Output

{
  "success": true,
  "data": {
    "postalCode": "10310",
    "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

Cek apakah kode pos Indonesia ada dan valid. Mengembalikan flag `valid`, jumlah lokasi yang cocok, dan daftar kelurahan/desanya. Gunakan untuk workflow validasi alamat yang hanya perlu konfirmasi kode pos. Untuk detail lokasi lengkap, gunakan `get_location_details`. Untuk validasi massal, gunakan `validate_postal_codes_batch`.

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

{
  "success": true,
  "data": {
    "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 semua kota/kabupaten dalam provinsi tertentu. Membutuhkan kode provinsi dari `get_provinces`. Set `include.province` ke `true` untuk menyertakan data provinsi induk dalam setiap hasil. Gunakan kode kota yang dikembalikan sebagai input untuk `get_districts`.

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

{
  "success": true,
  "data": {
    "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 semua kelurahan/desa dalam kecamatan tertentu, termasuk kode posnya. Membutuhkan kode kecamatan dari `get_districts`. Set `include.district` ke `true` untuk menyertakan data kecamatan, kota, dan provinsi induk dalam setiap hasil. Ini adalah level paling granular dalam hierarki administratif Indonesia.

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

{
  "success": true,
  "data": {
    "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 semua provinsi di Indonesia. Mengembalikan kode dan nama provinsi dengan paginasi berbasis kursor. Gunakan sebagai titik awal untuk menelusuri kota, kecamatan, dan kelurahan — kode provinsi yang dikembalikan digunakan sebagai input untuk `get_cities`.

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

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

get_districts

Daftar semua kecamatan dalam kota/kabupaten tertentu. Membutuhkan kode kota/kabupaten dari `get_cities`. Set `include.city` ke `true` untuk menyertakan data kota dan provinsi induk dalam setiap hasil. Gunakan kode kecamatan yang dikembalikan sebagai input untuk `get_subdistricts`.

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

{
  "success": true,
  "data": {
    "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"
    }
  }
}

validate_postal_codes_batch

Validasi hingga 50 kode pos Indonesia dalam satu pemanggilan. Setiap kode divalidasi secara independen — mengembalikan flag `valid`, jumlah lokasi, dan lokasi yang cocok per kode. Gunakan untuk workflow validasi alamat massal. Untuk satu kode pos, gunakan `validate_postal_code`. Untuk hierarki lokasi lengkap, gunakan `get_location_details`.

Parameter	Tipe	Wajib	Deskripsi	Default
postalCodes	string[]	Wajib	Array kode pos yang ingin divalidasi (1-50 kode pos)	—

Setiap kode pos divalidasi secara independen — jika satu gagal, yang lain tetap diproses. Cocok untuk workflow automasi yang memproses daftar alamat dari spreadsheet atau webhook.

Contoh Input

{
  "postalCodes": ["10310", "40135", "99999"]
}

Contoh Output

{
  "success": true,
  "data": {
    "totalRequested": 3,
    "validCount": 2,
    "invalidCount": 1,
    "results": [
      {
        "postalCode": "10310",
        "valid": true,
        "locationCount": 1,
        "locations": [...]
      },
      {
        "postalCode": "40135",
        "valid": true,
        "locationCount": 1,
        "locations": [...]
      },
      {
        "postalCode": "99999",
        "valid": false,
        "locationCount": 0,
        "locations": []
      }
    ]
  }
}

search_postal_codes_batch

Cari hingga 20 kata kunci atau kode pos dalam satu pemanggilan. Setiap query dieksekusi secara independen dan mengembalikan kelurahan/desa yang cocok secara fuzzy. Gunakan untuk workflow automasi yang perlu menyelesaikan beberapa alamat sekaligus. Untuk pencarian tunggal, gunakan `search_postal_code`.

Parameter	Tipe	Wajib	Deskripsi	Default
queries	string[]	Wajib	Array kata kunci pencarian (1-20 query, masing-masing minimal 2 karakter)	—
first	number	Opsional	Jumlah item per query (1-100)	20

Setiap query diproses secara independen. Jika satu query gagal, hasilnya akan berisi error sementara query lain tetap berhasil. Gunakan first untuk mengontrol jumlah hasil per query.

Contoh Input

{
  "queries": ["menteng", "bandung", "surabaya"]
}

Contoh Output

{
  "success": true,
  "data": {
    "totalRequested": 3,
    "successCount": 3,
    "failedCount": 0,
    "results": [
      {
        "query": "menteng",
        "success": true,
        "data": {
          "items": [...],
          "pagination": {...}
        }
      },
      {
        "query": "bandung",
        "success": true,
        "data": {
          "items": [...],
          "pagination": {...}
        }
      },
      {
        "query": "surabaya",
        "success": true,
        "data": {
          "items": [...],
          "pagination": {...}
        }
      }
    ]
  }
}

get_kodepos_api_status

Cek status kesehatan Kode Pos API dan versi server. Ping ringan yang tidak mengonsumsi kredit — gunakan sebagai pengecekan konektivitas sebelum menjalankan workflow automasi kode pos Indonesia, atau sebagai health probe di pipeline CI/CD. Mengembalikan status, versi API, dan waktu server.

Parameter	Tipe	Wajib	Deskripsi	Default

Tool ini tidak mengonsumsi kredit — cocok sebagai pre-flight check sebelum menjalankan workflow automasi yang panjang.

Contoh Input

{}

Contoh Output

{
  "success": true,
  "data": {
    "status": "ok",
    "version": "1.0.0",
    "serverTime": "2025-01-15T10:30:00.000Z"
  }
}

Contoh Interaksi

Setelah MCP Server terkonfigurasi, platform automasi dan AI agent Anda dapat langsung menggunakan tools — berikut contoh penggunaan nyata:

⚡ Contoh Workflow Automasi

Validasi daftar kode pos dari spreadsheet dalam satu pemanggilan:

Validasi Alamat

→

validate_postal_codes_batch

→

2 valid, 1 invalid

Hasil: 10310 ✅, 40135 ✅, 99999 ❌ — lanjutkan proses untuk kode pos valid

Contoh Percakapan dengan AI Agent

👤 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 (window fixed 1 menit), berbasis mode akun (Sandbox atau Production)

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 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.

Tool tanpa kredit: get_kodepos_api_status tidak mengonsumsi kredit. Gunakan sebagai pre-flight check sebelum menjalankan workflow automasi yang panjang.

Metode protokol MCP gratis: Metode standar MCP seperti initialize, tools/list, dan ping tidak dikenakan biaya kredit. Hanya pemanggilan tools/call yang mengonsumsi 1 kredit per panggilan yang berhasil.

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