Einen KI-Agenten mit MCP verbinden

Lassen Sie Claude, ChatGPT, Cursor oder Gemini per gehostetem MCP-Server Ihre Standorte, Einträge und Bewertungen mit denselben Tools lesen und bearbeiten.

Die Listings API hostet einen Model Context Protocol-Server (MCP) unter https://listingsapi.com/mcp. Sie müssen nichts installieren oder ausführen. Ein KI-Assistent, der MCP unterstützt, verbindet sich mit dieser URL, ermittelt ein Tool pro REST-Endpunkt sowie einige Dokumentationstools und ruft sie in Ihrem Konto auf. Diese Anleitung führt Sie durch die Verbindung der wichtigsten Clients und die anschließende Überprüfung der Verbindung.

1. Verstehen, welche Möglichkeiten der Agent erhält

Der Server stellt etwas mehr als 60 Tools bereit, von denen etwa 2 Drittel ausschließlich lesend arbeiten. Die Namen orientieren sich an den REST-Ressourcen, sodass locations_search, listings_premium, reviews_respond und posts_create_social dieselben Funktionen wie die entsprechenden Endpunkte ausführen, mit denselben Parametern und derselben Antwortstruktur. Mit den 3 Dokumentationstools search_docs, get_doc und get_endpoint kann der Assistent eine Seite oder die Schnittstellenspezifikation eines Endpunkts nachschlagen, statt die Struktur der Nutzdaten zu erraten.

Destruktive Vorgänge wie das Löschen eines Beitrags oder das Archivieren eines Standorts werden nicht als Tools bereitgestellt. Verwenden Sie dafür die REST-API oder ein SDK, damit ein Assistent Daten nicht eigenständig entfernen kann.

2. Die Anmeldemethode des Clients wählen

Jeder Client authentifiziert sich auf eine von 2 Arten. Beide führen serverseitig zum selben API-Schlüssel, sodass Ratenlimits und Nutzungsberichte identisch sind.

OAuth verwendet den Authorization Code Flow mit PKCE und dynamischer Clientregistrierung, sodass ein Client keine vorab ausgestellten Zugangsdaten benötigt. Die Metadaten befinden sich unter https://listingsapi.com/.well-known/oauth-authorization-server. Die Scopes sind read und write; ein Client, der keinen Scope anfordert, erhält read. Jede Genehmigung erstellt einen eigenen Schlüssel für diese Verbindung, den Sie unter /dashboard/keys wie jeden anderen Schlüssel widerrufen können.

3. Claude verbinden

Claude.ai und Claude Desktop. Der Server ist im Konnektorverzeichnis aufgeführt. Am schnellsten geht es daher, wenn Sie https://claude.ai/directory/listings-api öffnen und auf Connect (Verbinden) klicken. Claude führt den OAuth-Ablauf aus, Sie genehmigen die Scopes, und die Tools sind in jedem Chat verfügbar, in dem Sie den Konnektor über die Schaltfläche + und anschließend Connectors (Konnektoren) aktivieren.

Wenn Sie ihn lieber per URL hinzufügen möchten, gehen Sie zu Customize (Anpassen), dann zu Connectors (Konnektoren), klicken Sie auf + und Add custom connector (Benutzerdefinierten Konnektor hinzufügen), fügen Sie https://listingsapi.com/mcp ein und klicken Sie auf Add (Hinzufügen). Lassen Sie Advanced settings (Erweiterte Einstellungen) leer; der Server registriert Claude automatisch als Client. In den Tarifen Team und Enterprise fügt ein Inhaber den Konnektor unter Organization settings (Organisationseinstellungen) und dann Connectors (Konnektoren) hinzu, und die Mitglieder klicken anschließend bei diesem Konnektor auf Connect (Verbinden). Claude stellt die Verbindung von den Servern von Anthropic aus her, nicht von Ihrem Rechner, weshalb die gehostete URL wichtig ist.

Claude Code. Ein Befehl fügt den Server mit Ihrem Schlüssel hinzu:

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

Lassen Sie das Flag --header weg und führen Sie /mcp in Claude Code aus, um sich stattdessen über den Browser anzumelden. Verwenden Sie --scope project, um den Server in einer vom gesamten Team gemeinsam genutzten .mcp.json zu committen; committen Sie dabei keinen Schlüssel.

4. ChatGPT verbinden

ChatGPT verbindet sich über einen benutzerdefinierten Connector mit entfernten MCP-Servern, sobald Developer mode (Entwicklermodus) aktiviert ist. Diese Funktion ist in den Tarifen Plus, Pro, Business, Enterprise und Edu verfügbar, jedoch nicht im kostenlosen Tarif.

1. Öffnen Sie Settings (Einstellungen) über Ihr Profilmenü und aktivieren Sie Developer mode (Entwicklermodus). Je nach Version finden Sie diese Option unter Apps & Connectors (Apps und Connectors) oder Security and login (Sicherheit und Anmeldung).
2. Klicken Sie auf der Connector-Seite (in aktuellen Versionen als Plugins (Erweiterungen) bezeichnet) auf + oder Create (Erstellen).
3. Geben Sie einen Namen ein, fügen Sie https://listingsapi.com/mcp als Server-URL ein und wählen Sie OAuth zur Authentifizierung. Speichern Sie.
4. ChatGPT öffnet die Anmeldeseite. Genehmigen Sie read oder read write.
5. Öffnen Sie in einem neuen Chat das Tool-Menü, wählen Sie den Connector aus und prüfen Sie, ob er mit seinen Tools angezeigt wird. Tools mit Schreibzugriff erfordern weiterhin eine Bestätigung.

Codex CLI. Der Terminal-Agent von OpenAI liest MCP-Server aus ~/.codex/config.toml. Codex startet OAuth für HTTP-Server selbstständig und berücksichtigt die vom Server angegebenen Scopes, daher ist die Header-Zeile optional:

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

5. Cursor verbinden

Die Dashboard-Seite unter /dashboard/mcp enthält die Schaltfläche Add to Cursor (Zu Cursor hinzufügen). Sie öffnet einen Cursor-Installationslink, in dem die Server-URL und Ihr Schlüssel bereits eingetragen sind, sodass ein Klick die Einrichtung abschließt.

Für die manuelle Konfiguration fügen Sie den Server in ~/.cursor/mcp.json für alle Projekte oder in .cursor/mcp.json innerhalb eines einzelnen Repositorys hinzu:

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

Entfernen Sie den Block headers, um sich stattdessen mit OAuth anzumelden: Cursor zeigt beim Servereintrag unter Settings (Einstellungen) und anschließend MCP die Schaltfläche Connect (Verbinden) an und öffnet den Anmeldeablauf im Browser. Committen Sie niemals einen Schlüssel in einer .cursor/mcp.json auf Projektebene; verwenden Sie für gemeinsam genutzte Repositorys die globale Datei oder OAuth.

6. Gemini verbinden

Gemini CLI. Der Terminal-Agent von Google übernimmt entfernte Server aus ~/.gemini/settings.json (oder .gemini/settings.json in einem Projekt). Verwenden Sie httpUrl und nicht url, damit er den Streamable HTTP-Transport auswählt:

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

Ersetzen Sie für OAuth den Block headers durch "oauth": { "enabled": true }, starten Sie die CLI und führen Sie /mcp auth listingsapi aus. Führen Sie jederzeit /mcp aus, um den Server, seinen Verbindungsstatus und die von ihm erkannten Tools aufzulisten.

Gemini-App. Die Gemini-App für Endnutzer bietet keine Einstellung für benutzerdefinierte Connectors. Benutzerdefinierte MCP-Server stehen Teamadministratoren der Gemini Enterprise Business Edition zur Verfügung: Melden Sie sich unter business.gemini.google an, öffnen Sie Settings & help (Einstellungen und Hilfe), dann Manage team (Team verwalten) und Connected apps (Verbundene Apps) und klicken Sie auf Add MCP Server (MCP-Server hinzufügen). Fügen Sie https://listingsapi.com/mcp als URL ein. Das Formular fragt nach OAuth-Angaben: Die Autorisierungs-URL ist https://listingsapi.com/oauth/authorize, die Token-URL ist https://listingsapi.com/oauth/token und die Scopes sind read write. Außerdem werden eine Client-ID und ein Client-Secret abgefragt. Dieser Server stellt öffentliche PKCE-Clients ohne Secret aus. Registrieren Sie daher einen solchen Client mit der im Formular angezeigten Weiterleitungs-URL und lassen Sie das Secret leer, sofern das Formular dies zulässt:

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"}'

Die Antwort enthält client_id. Wenn Ihr Gemini-Formular zwingend ein Secret verlangt, verwenden Sie den oben beschriebenen Weg über die Gemini CLI oder entwickeln Sie stattdessen mit der Gemini API.

Mit der Gemini API entwickeln. Das Gemini API SDK akzeptiert eine MCP-Client-Sitzung als Tool, sodass ein Skript einem Gemini-Modell dieselben Tools bereitstellen kann:

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. Die Verbindung überprüfen

Bevor Sie sich auf den Assistenten verlassen, prüfen Sie, ob der Server Ihnen direkt antwortet. Für die Tool-Erkennung ist kein Schlüssel erforderlich, daher ist dieser Aufruf mit jedem Client erfolgreich, der die URL erreichen kann:

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

Bitten Sie den Assistenten anschließend um etwas, das einen Zugriff auf Ihr Konto erfordert:

Verwenden Sie die listingsapi-Tools, um mir mitzuteilen, mit welchem Konto ich verbunden bin, wie viele Standorte es hat und wie hoch meine API-Nutzung in diesem Monat ist.

Bei einer korrekten Verbindung erhalten Sie Antworten von whoami, locations_all und get_usage mit Ihrer tatsächlichen Konto-ID und den tatsächlichen Anzahlen. Bei einem falschen oder abgelaufenen Schlüssel wird beim ersten Tool-Aufruf ein Unauthenticated-Fehler zurückgegeben, nicht bei der Tool-Erkennung.

Geeignete erste Prompts, sobald die Verbindung funktioniert:

• "Listen Sie meine Standorte mit Fehlern bei Einträgen auf und fassen Sie jeden Fehler zusammen."
• "Zeigen Sie Bewertungen, die in den letzten 7 Tagen eingegangen sind und noch keine Antwort haben, und entwerfen Sie für jede eine Antwort. Senden Sie die Antworten noch nicht."
• "Vergleichen Sie die Google-Profilanalysen für Standort 1800289 für die letzten zwei Monate."
• "Lesen Sie die Schnittstellenspezifikation des Endpunkts create-location und fügen Sie dann diesen Standort hinzu: ..."

Die listingsAPI-Agenten-Skills hinzufügen

Skills sind Anweisungen, die ein Agent bei einer passenden Aufgabe lädt, damit er einem erprobten Ablauf folgt, statt selbst einen zu entwickeln. Sie arbeiten mit dem MCP-Server zusammen: Der Server führt die Aufrufe aus, und der Skill legt fest, welche Aufrufe in welcher Reihenfolge erfolgen. Fünf listingsAPI-Skills aus dem öffentlichen listingsapi-mcp-Repository sind auf skills.sh veröffentlicht:

Installieren Sie alle fünf mit der Skills CLI in Ihrem Projekt:

npx skills add listings-api/listingsapi-mcp

Oder installieren Sie einen einzelnen Skill anhand seines Namens und wählen Sie den Agenten mit -a aus:

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

Verwenden Sie -a cursor oder -a codex für die jeweiligen Agenten und fügen Sie -g hinzu, um die Installation für alle Projekte statt nur für das aktuelle durchzuführen.

listingsAPI in KI-Tool-Verzeichnissen finden

Derselbe Server ist zusammen mit dem listingsAPI-Agenten-Skill in diesen Verzeichnissen aufgeführt. Installieren Sie ihn aus dem Verzeichnis, das Ihr Client bereits verwendet. Jeder MCP-Server-Eintrag verweist auf https://listingsapi.com/mcp.

Fehlerbehebung

Nächste Schritte

• Integrationsweg wählen: wann MCP geeignet ist und wann REST oder ein SDK die bessere Wahl ist.
• Ihren ersten API-Aufruf ausführen: Holen Sie sich einen Schlüssel und lernen Sie die Struktur der Antworten kennen, die die Tools zurückgeben.
• Mit Webhooks auf Ereignisse reagieren: Lassen Sie die Plattform Ihren Agenten benachrichtigen, statt regelmäßig Abfragen durchzuführen.
• Authentifizierung und Fehlercodes erläutern die Codes, die der Assistent Ihnen zurückmeldet.