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. Kurmanız veya çalıştırmanız gereken bir şey yoktur. MCP'yi destekleyen bir yapay zekâ asistanı bu URL'ye bağlanır, her REST uç noktası için bir araç ve birkaç dokümantasyon aracı keşfeder 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. Adlar REST kaynaklarına göre belirlenir; dolayısıyla locations_search, listings_premium, reviews_respond ve posts_create_social, karşılık gelen uç noktalarla aynı işlemleri, aynı parametrelerle ve aynı yanıt yapısıyla gerçekleştirir. Üç dokümantasyon aracı olan search_docs, get_doc ve get_endpoint, asistanın veri yükünün yapısını tahmin etmek yerine bir sayfaya veya uç nokta sözleşmesine başvurması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; dolayısıyla istek hızı sınırları ve kullanım raporlaması aynıdır.

OAuth, PKCE ve dinamik istemci kaydıyla birlikte yetkilendirme kodu akışı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; 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 listelenir; bu nedenle en hızlı yöntem https://claude.ai/directory/listings-api adresini açıp Connect (Bağlan) düğmesine tıklamaktır. Claude OAuth akışını çalıştırır, siz kapsamları onaylarsınız ve + düğmesine, ardından Connectors (Bağlayıcılar) seçeneğine tıklayarak bağlayıcıyı etkinleştirdiğiniz tüm sohbetlerde araçlar kullanılabilir hâle gelir.

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) bölümünü boş bırakın; sunucu Claude'u otomatik olarak istemci olarak kaydeder. Team ve Enterprise planlarında bir sahip, Organization settings (Kuruluş ayarları), ardından Connectors (Bağlayıcılar) bölümünden bağlayıcıyı ekler; üyeler daha sonra bu bağlayıcının Connect (Bağlan) düğmesine tıklar. Claude, bilgisayarınızdan değil Anthropic sunucularından bağlanır; bu nedenle barındırılan sunucunun URL'si önemlidir.

Claude Code. Tek bir komut, sunucuyu anahtarınızla 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. Sunucuyu tüm ekibin paylaştığı bir .mcp.json dosyasına kaydedip sürüm kontrolüne eklemek için --scope project kullanın; anahtarı bununla birlikte sürüm kontrolüne eklemeyin.

4. ChatGPT'yi bağlayın

Developer mode (Geliştirici modu) açıldığında ChatGPT, 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.

1. 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.
2. Bağlayıcılar sayfasında (güncel sürümlerde Plugins (Eklentiler) olarak adlandırılır) + veya Create (Oluştur) seçeneğine tıklayın.
3. Bir ad girin, sunucu URL'si olarak https://listingsapi.com/mcp değerini yapıştırın ve kimlik doğrulama için OAuth seçeneğini belirleyin. Kaydedin.
4. ChatGPT oturum açma sayfasını açar. read veya read write için onay verin.
5. 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ının kullanımı için onay istenmeye devam eder.

Codex CLI. OpenAI'ın terminal ajanı, MCP sunucularını ~/.codex/config.toml dosyasından okur. Codex, HTTP sunucuları için OAuth akışını kendiliğinden 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 kurulum tek tıklamayla tamamlanır.

Elle yapılandırmak için sunucuyu tüm projelerde kullanmak üzere ~/.cursor/mcp.json dosyasına veya tek bir depo içinde kullanmak üzere .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ındaki MCP bölümünde sunucuya ait kayıtta bir Connect (Bağlan) düğmesi gösterir ve tarayıcıdaki akışı açar. Proje düzeyindeki .cursor/mcp.json dosyasına yazılmış bir 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 sunucuları ~/.gemini/settings.json dosyasından (veya proje içindeki .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), 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 değerini 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 client ID ve client secret ister. Bu sunucu, client secret içermeyen herkese açık PKCE istemcileri oluşturur; bu nedenle formda gösterilen yönlendirme URL'siyle bir istemci kaydedin ve form izin veriyorsa client secret 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 client secret girilmesini 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 URL'ye erişebilen herhangi bir istemciyle bu çağrı 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 400

Ardından asistandan hesabınıza erişmesini gerektiren bir işlem isteyin:

listingsapi araçlarını kullanarak planımı göster, konumlarımı say ve bu ayki API kullanımımı raporla.

Çalışan bir bağlantı, whoami üzerinden planınızı ve erişim durumunuzu, locations_all üzerinden konum verilerini ve get_usage üzerinden kullanım sayılarını 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ıyla sonuçlanır.

Bağlantı çalıştıktan sonra deneyebileceğiniz ilk ajan talimatları:

• "İşletme kaydı hataları olan konumlarımı listele ve her hatayı özetle."
• "Son 7 günde gelen ve yanıtlanmamış yorumları göster ve her biri için bir yanıt taslağı hazırla. Yanıtları henüz gönderme."
• "1800289 numaralı konumun son iki aya ait Google profil analizlerini karşılaştır."
• "create-location uç noktasının sözleşmesini oku, ardından şu konumu ekle: ..."

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şini de projenize yükleyin:

npx skills add listings-api/listingsapi-mcp

Veya birini adıyla yükleyin ve -a ile ajanı seçin:

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

Bu ajanlar için -a cursor veya -a codex kullanın; yalnızca mevcut proje yerine tüm projeler için yüklemek üzere -g ekleyin.

Yapay zekâ aracı dizinlerinde listingsAPI bulun

Aynı sunucu, listingsAPI ajan becerisiyle birlikte bu dizinlerde listelenir. İstemcinizin zaten kullandığı dizinden yükleyin. Her MCP sunucusu kaydı https://listingsapi.com/mcp adresine yönlendirir.

Sorun giderme

Sonraki adımlar

• Entegrasyon yöntemini seçin: MCP'nin ne zaman uygun olduğunu ve REST veya bir SDK'nın ne zaman daha iyi bir seçenek 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 sorgulamak 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ı bölümlerine bakın.