Hubungkan agen AI dengan MCP

Arahkan Claude, ChatGPT, Cursor atau Gemini ke MCP yang dihosting untuk membaca dan mengelola lokasi, profil bisnis, dan ulasan Anda dengan alat yang sama.

Listings API menyediakan server Model Context Protocol (MCP) di https://listingsapi.com/mcp. Tidak ada yang perlu diinstal atau dijalankan. Asisten AI yang mendukung MCP terhubung ke URL tersebut, menemukan satu alat untuk setiap endpoint REST beserta beberapa alat dokumentasi, lalu memanggilnya pada akun Anda. Panduan ini menjelaskan cara menghubungkan setiap klien utama, lalu memverifikasi koneksinya.

1. Pahami apa yang tersedia bagi agen

Server menyediakan sedikit lebih dari 60 alat, dan sekitar dua pertiganya hanya dapat membaca data. Nama alat mengikuti sumber daya REST, sehingga locations_search, listings_premium, reviews_respond, dan posts_create_social melakukan hal yang sama dengan endpoint yang sesuai, dengan parameter dan struktur respons yang sama. Tiga alat dokumentasi, search_docs, get_doc, dan get_endpoint, memungkinkan asisten mencari halaman atau kontrak endpoint alih-alih menebak struktur payload.

Operasi destruktif seperti menghapus postingan atau mengarsipkan lokasi tidak disediakan sebagai alat. Gunakan REST API atau SDK untuk operasi tersebut, sehingga asisten tidak dapat menghapus data atas inisiatifnya sendiri.

2. Pilih cara klien masuk

Setiap klien melakukan autentikasi dengan salah satu dari dua cara. Keduanya pada akhirnya menggunakan kunci API yang sama di sisi server, sehingga batas laju dan pelaporan penggunaan identik.

OAuth menggunakan alur kode otorisasi dengan PKCE dan pendaftaran klien dinamis, sehingga klien tidak memerlukan kredensial yang diterbitkan sebelumnya. Metadata tersedia di https://listingsapi.com/.well-known/oauth-authorization-server. Cakupan yang tersedia adalah read dan write; klien yang tidak meminta cakupan apa pun mendapatkan read. Setiap persetujuan membuat kunci khusus untuk koneksi tersebut, yang dapat Anda cabut melalui /dashboard/keys seperti kunci lainnya.

3. Hubungkan Claude

Claude.ai dan Claude Desktop. Server tercantum dalam direktori konektor, jadi cara tercepat adalah membuka https://claude.ai/directory/listings-api dan mengeklik Connect (Hubungkan). Claude menjalankan alur OAuth, Anda menyetujui cakupannya, lalu alat tersedia dalam percakapan mana pun tempat Anda mengaktifkan konektor melalui tombol +, lalu Connectors (Konektor).

Jika Anda lebih memilih menambahkannya melalui URL, buka Customize (Sesuaikan), lalu Connectors (Konektor), klik + dan Add custom connector (Tambahkan konektor kustom), tempelkan https://listingsapi.com/mcp, lalu klik Add (Tambahkan). Biarkan Advanced settings (Pengaturan lanjutan) kosong; server mendaftarkan Claude sebagai klien secara otomatis. Pada paket Team dan Enterprise, pemilik menambahkan konektor melalui Organization settings (Pengaturan organisasi), lalu Connectors (Konektor), kemudian anggota mengeklik Connect (Hubungkan) pada konektor tersebut. Claude terhubung dari server Anthropic, bukan dari komputer Anda, sehingga URL yang dihosting tersebut penting.

Claude Code. Satu perintah menambahkan server menggunakan kunci Anda:

claude mcp add --transport http listingsapi https://listingsapi.com/mcp \--header "Authorization: API $LISTINGSAPI_KEY"

Hapus flag --header dan jalankan /mcp di dalam Claude Code untuk masuk melalui browser sebagai gantinya. Gunakan --scope project untuk memasukkan konfigurasi server ke dalam commit pada .mcp.json yang digunakan bersama oleh seluruh tim; jangan sertakan kunci dalam commit tersebut.

4. Hubungkan ChatGPT

ChatGPT terhubung ke server MCP jarak jauh sebagai konektor kustom setelah Developer mode (mode pengembang) diaktifkan. Fitur ini tersedia pada paket Plus, Pro, Business, Enterprise, dan Edu, bukan pada paket gratis.

1. Buka Settings (pengaturan) dari menu profil Anda dan aktifkan Developer mode (mode pengembang). Bergantung pada versi aplikasi, opsi ini berada di bagian Apps & Connectors (aplikasi dan konektor) atau Security and login (keamanan dan masuk).
2. Pada halaman konektor (berlabel Plugins (plugin) dalam versi aplikasi saat ini), klik + atau Create (buat).
3. Masukkan nama, tempel https://listingsapi.com/mcp sebagai URL server, dan pilih OAuth untuk autentikasi. Simpan.
4. ChatGPT membuka halaman masuk. Setujui read atau read write.
5. Dalam percakapan baru, buka menu alat, pilih konektor, dan pastikan konektor tersebut muncul beserta alat-alatnya. Alat untuk menulis data tetap memerlukan konfirmasi.

Codex CLI. Agen terminal OpenAI membaca server MCP dari ~/.codex/config.toml. Codex memulai OAuth secara otomatis untuk server HTTP dan mengikuti cakupan yang dinyatakan oleh server, sehingga baris header bersifat opsional:

[mcp_servers.listingsapi]url = "https://listingsapi.com/mcp"http_headers = { "Authorization" = "API <your key>" }

5. Hubungkan Cursor

Halaman dasbor di /dashboard/mcp memiliki tombol Add to Cursor (tambahkan ke Cursor). Tombol ini membuka tautan instalasi Cursor dengan URL server dan kunci Anda yang sudah terisi, sehingga satu klik menyelesaikan penyiapan.

Untuk mengonfigurasinya secara manual, tambahkan server ke ~/.cursor/mcp.json agar berlaku untuk semua proyek, atau ke .cursor/mcp.json di dalam satu repositori:

{"mcpServers": {  "listingsapi": {    "url": "https://listingsapi.com/mcp",    "headers": {      "Authorization": "API <your key>"    }  }}}

Hapus blok headers untuk masuk menggunakan OAuth sebagai gantinya: Cursor menampilkan tombol Connect (hubungkan) pada entri server di bagian Settings (pengaturan), lalu MCP, dan membuka alur autentikasi di browser. Jangan pernah memasukkan kunci ke dalam commit melalui .cursor/mcp.json di tingkat proyek; gunakan berkas global atau OAuth untuk repositori bersama.

6. Hubungkan Gemini

Gemini CLI. Agen terminal Google menerima konfigurasi server jarak jauh di ~/.gemini/settings.json (atau .gemini/settings.json dalam sebuah proyek). Gunakan httpUrl, bukan url, agar agen memilih transport Streamable HTTP:

{"mcpServers": {  "listingsapi": {    "httpUrl": "https://listingsapi.com/mcp",    "headers": {      "Authorization": "API <your key>"    },    "timeout": 30000  }}}

Untuk OAuth, ganti blok headers dengan "oauth": { "enabled": true }, mulai CLI, lalu jalankan /mcp auth listingsapi. Jalankan /mcp kapan saja untuk menampilkan server, status koneksinya, dan alat-alat yang ditemukannya.

Aplikasi Gemini. Aplikasi Gemini untuk konsumen tidak memiliki pengaturan konektor kustom. Server MCP kustom tersedia bagi administrator tim edisi Gemini Enterprise Business: masuk di business.gemini.google, buka Settings & help (pengaturan dan bantuan), lalu Manage team (kelola tim) dan Connected apps (aplikasi terhubung), kemudian klik Add MCP Server (tambahkan server MCP). Tempel https://listingsapi.com/mcp sebagai URL. Formulir tersebut meminta detail OAuth: URL otorisasi adalah https://listingsapi.com/oauth/authorize, URL token adalah https://listingsapi.com/oauth/token, dan cakupannya adalah read write. Formulir tersebut juga meminta client ID dan client secret. Server ini menerbitkan klien PKCE publik tanpa secret, jadi daftarkan satu klien dengan URL pengalihan yang ditampilkan formulir dan biarkan secret kosong jika formulir mengizinkannya:

curl -s https://listingsapi.com/oauth/register \-H "Content-Type: application/json" \-d '{  "client_name": "Gemini Business",  "redirect_uris": ["<redirect URL shown in the Gemini form>"],  "grant_types": ["authorization_code", "refresh_token"],  "token_endpoint_auth_method": "none"}'

Respons berisi client_id. Jika formulir Gemini Anda mewajibkan secret, gunakan cara melalui Gemini CLI di atas atau bangun dengan Gemini API sebagai gantinya.

Membangun dengan Gemini API. SDK Gemini API menerima sesi klien MCP sebagai alat, sehingga skrip dapat memberikan alat-alat yang sama kepada model Gemini:

import asyncio, osfrom google import genaifrom mcp import ClientSessionfrom mcp.client.streamable_http import streamablehttp_client HEADERS = {"Authorization": "API " + os.environ["LISTINGSAPI_KEY"]} async def main():  gemini = genai.Client()  async with streamablehttp_client("https://listingsapi.com/mcp", headers=HEADERS) as (r, w, _):      async with ClientSession(r, w) as session:          await session.initialize()          reply = await gemini.aio.models.generate_content(              model="gemini-2.5-pro",              contents="Which of my locations have a Google listing that is not live yet?",              config=genai.types.GenerateContentConfig(tools=[session]),          )          print(reply.text) asyncio.run(main())

7. Verifikasi koneksi

Sebelum Anda memercayai asisten, pastikan server menjawab Anda secara langsung. Penemuan alat tidak memerlukan kunci, sehingga panggilan ini berhasil dengan klien apa pun yang dapat mengakses URL tersebut:

curl -s https://listingsapi.com/mcp \-H "Content-Type: application/json" \-H "Accept: application/json, text/event-stream" \-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | head -c 400

Kemudian, di dalam asisten, mintalah sesuatu yang mengharuskan akses ke akun Anda:

Gunakan alat listingsapi untuk memberi tahu saya akun mana yang terhubung dengan saya, berapa banyak lokasi yang dimilikinya, dan penggunaan API saya bulan ini.

Koneksi yang benar memberikan jawaban dari whoami, locations_all, dan get_usage dengan id akun serta jumlah yang sebenarnya milik Anda. Kunci yang salah atau kedaluwarsa menghasilkan kesalahan Unauthenticated pada panggilan alat pertama, bukan pada tahap penemuan alat.

Instruksi untuk agen yang cocok untuk dicoba pertama kali setelah koneksi berfungsi:

• "Tampilkan daftar lokasi saya yang memiliki kesalahan profil bisnis dan ringkas setiap kesalahan."
• "Tampilkan ulasan yang diterima dalam 7 hari terakhir dan belum dibalas, lalu buat draf balasan untuk masing-masing ulasan. Jangan kirim balasan tersebut dulu."
• "Bandingkan analitik profil Google untuk lokasi 1800289 antara dua bulan terakhir."
• "Baca kontrak endpoint create-location, lalu tambahkan lokasi ini: ..."

Tambahkan skill agen listingsAPI

Skill adalah instruksi yang dimuat agen saat suatu tugas sesuai, sehingga agen mengikuti alur kerja yang telah diuji alih-alih menyusun alur kerjanya sendiri. Skill bekerja bersama server MCP: server melakukan panggilan, dan skill menentukan panggilan mana yang harus dilakukan serta urutannya. Lima skill listingsAPI dipublikasikan di skills.sh dari repositori listingsapi-mcp publik:

Instal kelima skill ke proyek Anda dengan Skills CLI:

npx skills add listings-api/listingsapi-mcp

Atau instal satu skill berdasarkan namanya, dan pilih agen dengan -a:

npx skills add listings-api/listingsapi-mcp --skill listingsapi-integration -a claude-code

Gunakan -a cursor atau -a codex untuk agen tersebut, dan tambahkan -g untuk menginstalnya bagi setiap proyek, bukan hanya proyek saat ini.

Temukan listingsAPI di direktori alat AI

Server yang sama tercantum di direktori berikut, bersama skill agen listingsAPI. Instal dari direktori yang sudah digunakan klien Anda. Setiap entri server MCP mengarah ke https://listingsapi.com/mcp.

Pemecahan masalah

Langkah berikutnya

• Pilih cara integrasi: kapan MCP sesuai dan kapan REST atau SDK menjadi pilihan yang lebih baik.
• Lakukan panggilan API pertama Anda: dapatkan kunci dan pelajari struktur respons yang dikembalikan alat.
• Tanggapi peristiwa dengan webhook: atur agar platform memberi tahu agen Anda alih-alih melakukan polling.
• Autentikasi dan Kode kesalahan untuk kode yang akan dilaporkan asisten kepada Anda.