Bir yapay zekâ ajanını MCP ile 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ı aynı araçlarla okusun ve 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 hiç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 nelere erişebildiğini öğrenin

Sunucu, yaklaşık 3'te 2'si salt okunur olan 60'tan biraz fazla araç sunar. Adlar REST kaynaklarını temel alır; 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ç nokta sözleşmesine bakmasını sağlar.

Bir gönderiyi silmek veya bir konumu arşivlemek 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 ve dinamik istemci kaydıyla 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; hiçbir kapsam istemeyen bir istemciye read verilir. Her onay, o 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ı yol https://claude.ai/directory/listings-api adresini açıp Connect (Bağlan) seçeneğine tıklamaktır. Claude OAuth akışını başlatır, siz kapsamları onaylarsınız ve + düğmesini, ardından Connectors (Bağlayıcılar) seçeneğini kullanarak bağlayıcıyı etkinleştirdiğiniz her sohbette 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) seçeneğine tıklayın. Advanced settings (Gelişmiş ayarlar) bölümünü boş bırakın; sunucu Claude'u otomatik olarak istemci kaydına alır. 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) seçeneğine tıklar. Claude, sizin makinenizden değil Anthropic'in sunucularından bağlanır; barındırılan URL bu nedenle ö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 commit etmek için --scope project kullanın; bununla birlikte bir anahtarı commit etmeyin.

4. ChatGPT'yi bağlayın

ChatGPT, Developer mode (geliştirici modu) açıldığında uzak MCP sunucularına özel bir 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 yer alır.
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ı için onay vermeniz gerekir.

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 bildirilen kapsamları dikkate alır; bu nedenle üst bilgi 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.

Manuel yapılandırma için sunucuyu tüm projelerde kullanılacak şekilde ~/.cursor/mcp.json dosyasına veya tek bir deponun 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) bölümündeki MCP altında sunucu kaydında bir Connect (bağlan) düğmesi gösterir ve tarayıcı akışını açar. Proje düzeyindeki bir .cursor/mcp.json dosyasına eklediğiniz anahtarı asla commit etmeyin; 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 bir projede .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) seçeneğine 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 istemci kimliği ve istemci gizli anahtarı ister. Bu sunucu, gizli anahtarı olmayan herkese açık 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 değerini 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 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 şey isteyin:

Hangi hesapla bağlantı kurduğumu, bu hesapta kaç konum olduğunu ve bu ayki API kullanımımı söylemek için listingsapi araçlarını kullanın.

Doğru bir bağlantı, whoami, locations_all ve get_usage üzerinden gerçek hesap kimliğinizi ve 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ı olarak döner.

Bağlantı çalıştıktan sonra kullanabileceğiniz ilk 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 aydaki 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 deposundan alınan beş listingsAPI becerisi skills.sh üzerinde yayımlanmıştır:

Skills CLI ile beş becerinin tamamını projenize yükleyin:

npx skills add listings-api/listingsapi-mcp

Ya da bir beceriyi 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 ve yalnızca mevcut proje yerine tüm projeler için yüklemek üzere -g ekleyin.

Yapay zekâ aracı dizinlerinde listingsAPI öğesini bulun

Aynı sunucu, listingsAPI ajan becerisiyle birlikte bu dizinlerde listelenir. İ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 ne zaman uygun olduğu ve REST veya bir SDK'nın ne zaman daha iyi bir seçim olduğu.
• İlk API çağrınızı yapın: bir anahtar edinin ve araçların döndürdüğü yanıtın 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ı.