Yapay zekâ ajanlarını listingsAPI MCP'ye bağlayın
Claude, ChatGPT, Cursor veya Gemini'yi barındırılan MCP sunucusuna bağlayın; konum, işletme kaydı ve yorumlarınızı sizinle aynı araçlarla okuyup işlesin.
Listings API, https://listingsapi.com/mcp adresinde bir Model Context Protocol (MCP) sunucusu barındırır. Yüklemeniz veya çalıştırmanız gereken bir şey yoktur. MCP destekleyen bir yapay zekâ asistanı bu URL'ye bağlanır, her REST uç noktası için bir araç ve birkaç dokümantasyon aracı bulur ve bunları hesabınızda çağırır. Bu kılavuz, yaygın kullanılan istemcilerin her birini bağlama ve ardından bağlantıyı doğrulama adımlarını açıklar.
1. Ajanın hangi araçlara erişebildiğini öğrenin
Sunucu, yaklaşık üçte ikisi salt okunur olan 60'tan biraz fazla araç sunar. Araç adları REST kaynaklarıyla eşleşir; dolayısıyla locations_search, listings_premium, reviews_respond ve posts_create_social, karşılık gelen uç noktalarla aynı işlemleri, aynı parametreler ve aynı yanıt yapısıyla gerçekleştirir. Üç dokümantasyon aracı olan search_docs, get_doc ve get_endpoint, asistanın istek gövdesinin yapısını tahmin etmek yerine bir sayfaya veya uç noktanın sözleşmesine bakmasını sağlar.
Gönderi silme veya konum arşivleme gibi yıkıcı işlemler araç olarak sunulmaz. Bu işlemler için REST API'yi veya bir SDK'yı kullanın; böylece asistan kendi başına veri kaldıramaz.
2. İstemcinin nasıl oturum açacağını seçin
Her istemci, iki yöntemden biriyle kimlik doğrular. Her iki yöntem de sunucu tarafında aynı API anahtarını kullanır; bu nedenle istek hızı sınırları ve kullanım raporlaması aynıdır.
OAuth, PKCE ile yetkilendirme kodu akışını ve dinamik istemci kaydını kullanır; bu nedenle istemcinin önceden verilmiş kimlik bilgilerine ihtiyacı yoktur. Meta veriler https://listingsapi.com/.well-known/oauth-authorization-server adresindedir. Kapsamlar read ve write şeklindedir; kapsam istemeyen bir istemciye read verilir. Her onay, ilgili bağlantıya özel bir anahtar oluşturur ve bu anahtarı diğer anahtarlar gibi /dashboard/keys üzerinden iptal edebilirsiniz.
3. Claude'u bağlayın
Claude.ai ve Claude Desktop. Sunucu bağlayıcı dizininde listelendiği için en hızlı yol, https://claude.ai/directory/listings-api adresini açıp Connect (Bağlan) düğmesine tıklamaktır. Claude OAuth akışını yürütür, siz kapsamları onaylarsınız ve + düğmesinin ardından Connectors (Bağlayıcılar) seçeneğini kullanarak bağlayıcıyı etkinleştirdiğiniz her sohbette araçlar kullanılabilir.
URL ile eklemeyi tercih ederseniz Customize (Özelleştir), ardından Connectors (Bağlayıcılar) bölümüne gidin, + ve Add custom connector (Özel bağlayıcı ekle) seçeneklerine tıklayın, https://listingsapi.com/mcp adresini yapıştırın ve Add (Ekle) düğmesine tıklayın. Advanced settings (Gelişmiş ayarlar) alanını boş bırakın; sunucu Claude'u otomatik olarak istemci olarak kaydeder. Team ve Enterprise planlarında bir hesap sahibi, Organization settings (Kuruluş ayarları) altındaki Connectors (Bağlayıcılar) bölümünden bağlayıcıyı ekler, ardından üyeler bu bağlayıcının Connect (Bağlan) düğmesine tıklar. Claude, sizin makinenizden değil Anthropic'in sunucularından bağlanır; barındırılan URL'nin önemli olmasının nedeni budur.
Claude Code. Tek bir komut, anahtarınızla sunucuyu ekler:
claude mcp add --transport http listingsapi https://listingsapi.com/mcp \--header "Authorization: API $LISTINGSAPI_KEY"Bunun yerine tarayıcı üzerinden oturum açmak için --header bayrağını kaldırın ve Claude Code içinde /mcp komutunu çalıştırın. Sunucu yapılandırmasını tüm ekibin paylaştığı bir .mcp.json dosyasına ekleyip sürüm kontrolüne kaydetmek için --scope project kullanın; beraberinde bir anahtarı sürüm kontrolüne kaydetmeyin.
4. ChatGPT'yi bağlayın
ChatGPT, Developer mode (Geliştirici modu) açıldığında uzak MCP sunucularına özel bağlayıcı olarak bağlanır. Bu özellik Plus, Pro, Business, Enterprise ve Edu planlarında kullanılabilir; ücretsiz planda kullanılamaz.
- Profil menünüzden Settings (Ayarlar) bölümünü açın ve Developer mode (Geliştirici modu) seçeneğini etkinleştirin. Kullandığınız sürüme bağlı olarak bu seçenek Apps & Connectors (Uygulamalar ve bağlayıcılar) veya Security and login (Güvenlik ve oturum açma) altında bulunur.
- Bağlayıcılar sayfasında (güncel sürümlerde Plugins (Eklentiler) olarak adlandırılır) + veya Create (Oluştur) düğmesine tıklayın.
- Bir ad girin, sunucu URL'si olarak
https://listingsapi.com/mcpadresini yapıştırın ve kimlik doğrulama için OAuth seçeneğini belirleyin. Kaydedin. - ChatGPT oturum açma sayfasını açar.
readveyaread writeseçeneğini onaylayın. - Yeni bir sohbette araçlar menüsünü açın, bağlayıcıyı seçin ve araçlarıyla birlikte göründüğünü doğrulayın. Yazma araçları için bir ajan talimatıyla onay istenmeye devam edilir.
Codex CLI. OpenAI'ın terminal ajanı, MCP sunucularını ~/.codex/config.toml dosyasından okur. Codex, HTTP sunucuları için OAuth sürecini kendisi başlatır ve sunucunun bildirdiği kapsamları dikkate alır; bu nedenle üstbilgi satırı isteğe bağlıdır:
[mcp_servers.listingsapi]url = "https://listingsapi.com/mcp"http_headers = { "Authorization" = "API <your key>" }5. Cursor'ı bağlayın
/dashboard/mcp adresindeki kontrol paneli sayfasında bir Add to Cursor (Cursor'a ekle) düğmesi bulunur. Bu düğme, sunucu URL'si ve anahtarınız önceden doldurulmuş bir Cursor kurulum bağlantısını açar; böylece tek tıklamayla kurulum tamamlanır.
Elle yapılandırmak için sunucuyu tüm projelerde kullanılmak üzere ~/.cursor/mcp.json dosyasına veya tek bir depo içindeki .cursor/mcp.json dosyasına ekleyin:
{"mcpServers": { "listingsapi": { "url": "https://listingsapi.com/mcp", "headers": { "Authorization": "API <your key>" } }}}Bunun yerine OAuth ile oturum açmak için headers bloğunu kaldırın: Cursor, Settings (Ayarlar) altında MCP bölümündeki sunucu kaydında bir Connect (Bağlan) düğmesi gösterir ve tarayıcıdaki oturum açma akışını başlatır. Proje düzeyindeki bir .cursor/mcp.json dosyasında bulunan anahtarı asla sürüm kontrolüne kaydetmeyin; paylaşılan depolar için genel dosyayı veya OAuth kullanın.
6. Gemini'ı bağlayın
Gemini CLI. Google'ın terminal ajanı, uzak sunucu yapılandırmalarını ~/.gemini/settings.json dosyasından (veya bir projedeki .gemini/settings.json dosyasından) alır. Streamable HTTP aktarımını seçmesi için url yerine httpUrl kullanın:
{"mcpServers": { "listingsapi": { "httpUrl": "https://listingsapi.com/mcp", "headers": { "Authorization": "API <your key>" }, "timeout": 30000 }}}OAuth için headers bloğunu "oauth": { "enabled": true } ile değiştirin, CLI'ı başlatın ve /mcp auth listingsapi komutunu çalıştırın. Sunucuyu, bağlantı durumunu ve keşfettiği araçları listelemek için istediğiniz zaman /mcp komutunu çalıştırın.
Gemini uygulaması. Bireysel kullanıcılara yönelik Gemini uygulamasında özel bağlayıcı ayarı yoktur. Özel MCP sunucuları, Gemini Enterprise Business sürümünün ekip yöneticileri tarafından kullanılabilir: business.gemini.google adresinde oturum açın, Settings & help (Ayarlar ve yardım) bölümünü, ardından Manage team (Ekibi yönet) ve Connected apps (Bağlı uygulamalar) bölümlerini açın ve Add MCP Server (MCP sunucusu ekle) düğmesine tıklayın. URL olarak https://listingsapi.com/mcp adresini yapıştırın. Form OAuth bilgilerini ister: yetkilendirme URL'si https://listingsapi.com/oauth/authorize, token URL'si https://listingsapi.com/oauth/token ve kapsamlar read write şeklindedir. Ayrıca bir istemci kimliği ve istemci gizli anahtarı ister. Bu sunucu, gizli anahtarı olmayan genel PKCE istemcileri oluşturur; bu nedenle formda gösterilen yönlendirme URL'siyle bir istemci kaydedin ve form izin veriyorsa gizli anahtar alanını boş bırakın:
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"}'Yanıt client_id içerir. Gemini formunuz gizli anahtarı zorunlu tutuyorsa yukarıdaki Gemini CLI yöntemini kullanın veya bunun yerine Gemini API ile geliştirin.
Gemini API ile geliştirme. Gemini API SDK, bir MCP istemci oturumunu araç olarak kabul eder; böylece bir betik, Gemini modeline aynı araçları sağlayabilir:
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. Bağlantıyı doğrulayın
Asistana güvenmeden önce sunucunun size doğrudan yanıt verdiğini doğrulayın. Araç keşfi için anahtar gerekmez; bu nedenle bu çağrı, URL'ye erişebilen herhangi bir istemciyle başarılı olur:
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 400Ardından asistanın içinde, hesabınıza erişilmesini gerektiren bir istekte bulunun:
Planımı göstermek, konumlarımı saymak ve bu ayki API kullanımımı raporlamak için listingsapi araçlarını kullanın.
Çalışan bir bağlantı, planınızı ve erişim durumunuzu whoami üzerinden, konum verilerini locations_all üzerinden ve kullanım sayılarını get_usage üzerinden döndürür. Yanlış veya süresi dolmuş bir anahtar, keşif sırasında değil, ilk araç çağrısında Unauthenticated hatası döndürülmesine neden olur.
Bağlantı çalıştığında başlangıç için kullanabileceğiniz ajan talimatları:
- "İşletme kaydı hataları olan konumlarımı listeleyin ve her hatayı özetleyin."
- "Son 7 günde gelen ve yanıtlanmamış yorumları gösterin ve her biri için bir yanıt taslağı hazırlayın. Yanıtları henüz göndermeyin."
- "1800289 numaralı konumun son iki aya ait Google profil analizlerini karşılaştırın."
- "create-location uç noktasının sözleşmesini okuyun, ardından şu konumu ekleyin: ..."
listingsAPI ajan becerilerini ekleyin
Beceriler, bir görevle eşleştiğinde ajanın yüklediği talimatlardır; böylece ajan kendi iş akışını oluşturmak yerine test edilmiş bir iş akışını izler. MCP sunucusuyla birlikte çalışırlar: sunucu çağrıları yapar, beceri ise hangi çağrıların hangi sırayla yapılacağını belirler. Herkese açık listingsapi-mcp deposundaki beş listingsAPI becerisi skills.sh üzerinde yayımlanır:
Skills CLI ile beş becerinin tamamını projenize yükleyin:
npx skills add listings-api/listingsapi-mcpVeya bir beceriyi adıyla yükleyin ve ajanı -a ile seçin:
npx skills add listings-api/listingsapi-mcp --skill listingsapi-integration -a claude-codeBu ajanlar için -a cursor veya -a codex kullanın ve yalnızca mevcut proje yerine tüm projeler için yüklemek üzere -g ekleyin.
listingsAPI öğesini yapay zekâ araç dizinlerinde bulun
Aynı sunucu, listingsAPI ajan becerisiyle birlikte bu dizinlerde yer alır. İstemcinizin zaten kullandığı dizinden yükleyin. Her MCP sunucusu girdisi https://listingsapi.com/mcp adresine yönlendirir.
Sorun giderme
Sonraki adımlar
- Entegrasyon yöntemini seçin: MCP'nin hangi durumlarda uygun olduğunu ve REST veya bir SDK'nın hangi durumlarda daha iyi bir seçim olduğunu öğrenin.
- İlk API çağrınızı yapın: bir anahtar alın ve araçların döndürdüğü yanıt yapısını öğrenin.
- Webhook'larla olaylara tepki verin: düzenli aralıklarla sorgulama yapmak yerine platformun ajanınıza bildirim göndermesini sağlayın.
- Asistanın size bildireceği kodlar için Kimlik doğrulama ve Hata kodları.