Collega gli agenti AI a listingsAPI MCP

Collega Claude, ChatGPT, Cursor o Gemini al server MCP ospitato per leggere e gestire le tue sedi, schede e recensioni con gli stessi strumenti che usi tu.

Listings API ospita un server Model Context Protocol (MCP) all'indirizzo https://listingsapi.com/mcp. Non c'è nulla da installare o eseguire. Un assistente IA che supporta MCP si connette a quell'URL, rileva uno strumento per ogni endpoint REST e alcuni strumenti per la documentazione, e li invoca sul tuo account. Questa guida spiega come connettere i principali client e poi verificare la connessione.

1. Scopri quali strumenti sono disponibili per l'agente

Il server espone poco più di sessanta strumenti, di cui circa due terzi sono di sola lettura. I nomi corrispondono alle risorse REST, quindi locations_search, listings_premium, reviews_respond e posts_create_social eseguono le stesse operazioni degli endpoint corrispondenti, con gli stessi parametri e la stessa struttura della risposta. Tre strumenti per la documentazione, search_docs, get_doc e get_endpoint, consentono all'assistente di consultare una pagina o il contratto di un endpoint invece di ipotizzare la struttura del payload.

Le operazioni distruttive, come l'eliminazione di un post o l'archiviazione di una sede, non sono esposte come strumenti. Per queste operazioni usa l'API REST o un SDK, così un assistente non può rimuovere dati autonomamente.

2. Scegli come il client effettua l'accesso

Ogni client si autentica in uno di due modi. Entrambi si traducono nella stessa chiave API sul server, quindi i limiti di frequenza delle richieste e i report di utilizzo sono identici.

OAuth usa il flusso con codice di autorizzazione con PKCE e la registrazione dinamica del client, quindi un client non ha bisogno di credenziali emesse in precedenza. I metadati si trovano all'indirizzo https://listingsapi.com/.well-known/oauth-authorization-server. Gli ambiti sono read e write; un client che non ne richiede nessuno ottiene read. Ogni approvazione crea una chiave dedicata a quella connessione, che puoi revocare da /dashboard/keys come qualsiasi altra chiave.

3. Connetti Claude

Claude.ai e Claude Desktop. Il server è presente nella directory dei connettori, quindi il modo più rapido è aprire https://claude.ai/directory/listings-api e fare clic su Connect (Connetti). Claude esegue il flusso OAuth, tu approvi gli ambiti e gli strumenti sono disponibili in qualsiasi chat in cui abiliti il connettore tramite il pulsante +, poi Connectors (Connettori).

Se preferisci aggiungerlo tramite URL, vai su Customize (Personalizza), poi su Connectors (Connettori), fai clic su + e su Add custom connector (Aggiungi connettore personalizzato), incolla https://listingsapi.com/mcp e fai clic su Add (Aggiungi). Lascia vuota la sezione Advanced settings (Impostazioni avanzate); il server registra automaticamente Claude come client. Nei piani Team ed Enterprise, un proprietario aggiunge il connettore in Organization settings (Impostazioni dell'organizzazione), poi in Connectors (Connettori), e successivamente i membri fanno clic su Connect (Connetti) per quel connettore. Claude si connette dai server di Anthropic, non dal tuo computer, ed è per questo che l'URL del server ospitato è importante.

Claude Code. Un solo comando aggiunge il server con la tua chiave:

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

Per effettuare invece l'accesso tramite il browser, rimuovi il flag --header ed esegui /mcp all'interno di Claude Code. Usa --scope project per includere la configurazione del server in un file .mcp.json condiviso da tutto il team e aggiungerlo a un commit; non includere una chiave nel commit.

4. Collega ChatGPT

ChatGPT si collega ai server MCP remoti tramite un connettore personalizzato quando Developer mode (modalità sviluppatore) è attiva. Questa funzionalità è disponibile nei piani Plus, Pro, Business, Enterprise ed Edu, ma non nel piano gratuito.

1. Apri Settings (impostazioni) dal menu del tuo profilo e attiva Developer mode (modalità sviluppatore). A seconda della versione, si trova in Apps & Connectors (app e connettori) o in Security and login (sicurezza e accesso).
2. Nella pagina dei connettori (denominata Plugins (plugin) nelle versioni attuali), fai clic su + o su Create (crea).
3. Inserisci un nome, incolla https://listingsapi.com/mcp come URL del server e scegli OAuth per l'autenticazione. Salva.
4. ChatGPT apre la pagina di accesso. Approva read o read write.
5. In una nuova chat, apri il menu degli strumenti, seleziona il connettore e verifica che compaia con i suoi strumenti. Gli strumenti di scrittura continuano a richiedere una conferma tramite un prompt.

Codex CLI. L'agente da terminale di OpenAI legge i server MCP da ~/.codex/config.toml. Codex avvia automaticamente OAuth per i server HTTP e rispetta gli scope dichiarati, quindi la riga dell'header è facoltativa:

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

5. Collega Cursor

La pagina della dashboard all'indirizzo /dashboard/mcp contiene un pulsante Add to Cursor (aggiungi a Cursor). Il pulsante apre un link di installazione di Cursor con l'URL del server e la tua chiave già compilati, quindi basta un clic per completare la configurazione.

Per configurarlo manualmente, aggiungi il server a ~/.cursor/mcp.json per tutti i progetti oppure a .cursor/mcp.json all'interno di un singolo repository:

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

Rimuovi il blocco headers per accedere invece con OAuth: Cursor mostra un pulsante Connect (connetti) nella voce del server in Settings (impostazioni), poi MCP, e avvia la procedura nel browser. Non includere mai in un commit una chiave contenuta in un file .cursor/mcp.json a livello di progetto; per i repository condivisi, usa il file globale oppure OAuth.

6. Collega Gemini

Gemini CLI. L'agente da terminale di Google accetta server remoti in ~/.gemini/settings.json (o in .gemini/settings.json all'interno di un progetto). Usa httpUrl, non url, in modo che selezioni il trasporto Streamable HTTP:

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

Per OAuth, sostituisci il blocco headers con "oauth": { "enabled": true }, avvia la CLI ed esegui /mcp auth listingsapi. Esegui /mcp in qualsiasi momento per visualizzare il server, il suo stato di connessione e gli strumenti rilevati.

App Gemini. L'app Gemini per utenti privati non dispone di un'impostazione per i connettori personalizzati. I server MCP personalizzati sono disponibili per gli amministratori dei team dell'edizione Business di Gemini Enterprise: accedi a business.gemini.google, apri Settings & help (impostazioni e assistenza), poi Manage team (gestisci team) e Connected apps (app collegate), quindi fai clic su Add MCP Server (aggiungi server MCP). Incolla https://listingsapi.com/mcp come URL. Il modulo richiede i dettagli OAuth: l'URL di autorizzazione è https://listingsapi.com/oauth/authorize, l'URL del token è https://listingsapi.com/oauth/token e gli scope sono read write. Richiede anche un client ID e un client secret. Questo server rilascia client PKCE pubblici senza segreto, quindi registrane uno con l'URL di reindirizzamento mostrato nel modulo e lascia vuoto il campo del segreto se il modulo lo consente:

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

La risposta contiene client_id. Se il modulo di Gemini richiede obbligatoriamente un segreto, usa la procedura per Gemini CLI descritta sopra oppure sviluppa una soluzione con la Gemini API.

Sviluppare con la Gemini API. L'SDK della Gemini API accetta una sessione client MCP come strumento, quindi uno script può fornire a un modello Gemini gli stessi strumenti:

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. Verifica la connessione

Prima di affidarti all'assistente, verifica che il server ti risponda direttamente. Il rilevamento degli strumenti non richiede una chiave, quindi questa chiamata riesce con qualsiasi client in grado di raggiungere l'URL:

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

Poi, nell'assistente, chiedi qualcosa che richieda l'accesso al tuo account:

Usa gli strumenti listingsapi per mostrare il mio piano, contare le mie sedi e riportare il mio utilizzo dell'API nel mese corrente.

Una connessione funzionante restituisce il tuo piano e lo stato di accesso da whoami, i dati delle sedi da locations_all e i conteggi di utilizzo da get_usage. Una chiave errata o scaduta genera un errore Unauthenticated alla prima chiamata a uno strumento, non durante il rilevamento degli strumenti.

Alcuni prompt iniziali utili quando la connessione funziona:

• "Elenca le mie sedi con errori nelle schede e riassumi ogni errore."
• "Mostra le recensioni ricevute negli ultimi 7 giorni che non hanno una risposta e prepara una bozza di risposta per ciascuna. Non inviare ancora le risposte."
• "Confronta i dati di analisi del profilo Google della sede 1800289 tra gli ultimi due mesi."
• "Leggi il contratto dell'endpoint create-location, poi aggiungi questa sede: ..."

Aggiungi le skill listingsAPI per gli agenti

Le skill sono istruzioni che un agente carica quando sono pertinenti a un'attività, così da seguire un flusso di lavoro collaudato invece di definirne uno. Funzionano insieme al server MCP: il server esegue le chiamate e la skill decide quali chiamate effettuare e in quale ordine. Cinque skill listingsAPI sono pubblicate su skills.sh a partire dal repository pubblico listingsapi-mcp:

Installa tutte e cinque le skill nel tuo progetto con la CLI Skills:

npx skills add listings-api/listingsapi-mcp

Oppure installane una specificandone il nome e scegli l'agente con -a:

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

Usa -a cursor o -a codex per quegli agenti e aggiungi -g per installare le skill per tutti i progetti invece che per quello corrente.

Trova listingsAPI nei cataloghi di strumenti di IA

Lo stesso server è presente in questi cataloghi, insieme alla skill listingsAPI per gli agenti. Esegui l'installazione dal catalogo che il tuo client usa già. Ogni voce relativa al server MCP rimanda a https://listingsapi.com/mcp.

Risoluzione dei problemi

Passaggi successivi

• Scegli come integrare: quando MCP è adatto e quando REST o un SDK è la scelta migliore.
• Effettua la tua prima chiamata API: ottieni una chiave e scopri la struttura delle risposte restituite dagli strumenti.
• Reagisci agli eventi con i webhook: fai in modo che la piattaforma invii notifiche al tuo agente invece di ricorrere al polling.
• Autenticazione e Codici di errore per i codici che l'assistente ti comunicherà.