Hubungkan agen AI ke MCP listingsAPI

Arahkan Claude, ChatGPT, Cursor atau Gemini ke server MCP yang dihosting agar membaca dan mengelola lokasi, profil bisnis, dan ulasan lewat 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 ini menyediakan sedikit lebih dari 60 alat, dan sekitar 2/3 di antaranya hanya dapat membaca data. Nama alat mengikuti sumber daya REST, sehingga locations_search, listings_premium, reviews_respond, dan posts_create_social menjalankan fungsi yang sama dengan endpoint terkait, 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 tersedia sebagai alat. Gunakan REST API atau SDK untuk operasi tersebut, sehingga asisten tidak dapat menghapus data sendiri.

2. Pilih cara klien masuk

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

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 dari /dashboard/keys seperti kunci lainnya.

3. Hubungkan Claude

Claude.ai dan Claude Desktop. Server ini tercantum dalam direktori konektor, sehingga cara tercepat adalah membuka https://claude.ai/directory/listings-api dan mengeklik Connect (Hubungkan). Claude menjalankan alur OAuth, Anda menyetujui cakupannya, lalu alat tersedia di setiap percakapan 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 diperlukan.

Claude Code. Satu perintah menambahkan server dengan 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 menyimpan konfigurasi server dalam .mcp.json yang digunakan bersama oleh seluruh tim melalui commit; 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, tetapi tidak 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. Di halaman konektor (berlabel Plugins (plugin) pada versi saat ini), klik + atau Create (buat).
3. Masukkan nama, tempelkan https://listingsapi.com/mcp sebagai URL server, lalu pilih OAuth untuk autentikasi. Simpan.
4. ChatGPT membuka halaman masuk. Setujui read atau read write.
5. Dalam percakapan baru, buka menu alat, pilih konektor, lalu pastikan konektor tersebut muncul beserta alatnya. Alat untuk operasi tulis tetap meminta konfirmasi sebelum dijalankan.

Codex CLI. Agen terminal OpenAI membaca konfigurasi server MCP dari ~/.codex/config.toml. Codex memulai OAuth secara otomatis untuk server HTTP dan mengikuti cakupan akses yang dinyatakan 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 pemasangan Cursor dengan URL server dan kunci Anda yang sudah terisi, sehingga penyiapan selesai dengan satu klik.

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: Cursor menampilkan tombol Connect (hubungkan) pada entri server di bagian Settings (pengaturan), lalu MCP, dan membuka alur autentikasi di browser. Jangan pernah melakukan commit kunci di dalam .cursor/mcp.json pada tingkat proyek; gunakan file 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 yang ditemukannya.

Aplikasi Gemini. Aplikasi Gemini untuk konsumen tidak memiliki pengaturan konektor kustom. Server MCP kustom tersedia bagi administrator tim Gemini Enterprise edisi 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). Tempelkan https://listingsapi.com/mcp sebagai URL. Formulir meminta detail OAuth: URL otorisasi adalah https://listingsapi.com/oauth/authorize, URL token adalah https://listingsapi.com/oauth/token, dan cakupan aksesnya adalah read write. Formulir juga meminta client ID dan client secret. Server ini menerbitkan klien PKCE publik tanpa secret, jadi daftarkan satu klien menggunakan 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 memuat client_id. Jika formulir Gemini Anda mewajibkan secret, gunakan cara Gemini CLI di atas atau kembangkan aplikasi dengan Gemini API.

Mengembangkan aplikasi dengan Gemini API. SDK Gemini API menerima sesi klien MCP sebagai alat, sehingga skrip dapat menyediakan alat yang sama untuk 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 mengandalkan asisten, pastikan server merespons Anda secara langsung. Penemuan alat tidak memerlukan kunci, sehingga panggilan ini berhasil dari klien mana 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, minta sesuatu yang mengharuskan akses ke akun Anda:

Gunakan alat listingsapi untuk menampilkan paket saya, menghitung jumlah lokasi saya, dan melaporkan penggunaan API saya bulan ini.

Koneksi yang berfungsi mengembalikan paket dan status akses Anda dari whoami, data lokasi dari locations_all, serta jumlah penggunaan dari get_usage. Kunci yang salah atau kedaluwarsa menghasilkan kesalahan Unauthenticated pada panggilan alat pertama, bukan saat penemuan alat.

Contoh instruksi untuk agen yang dapat Anda gunakan setelah koneksi berfungsi:

• "Tampilkan daftar lokasi saya yang memiliki kesalahan pada profil bisnis dan rangkum 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 selama dua bulan terakhir."
• "Baca kontrak endpoint create-location, lalu tambahkan lokasi ini: ..."

Tambahkan skill agen listingsAPI

Skill adalah instruksi yang dimuat agen saat ada tugas yang sesuai, sehingga agen mengikuti alur kerja yang telah diuji alih-alih menyusunnya sendiri. Skill bekerja bersama server MCP: server menjalankan panggilan, dan skill menentukan panggilan mana yang harus dijalankan 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, lalu 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 semua 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.