Collega un agente AI con MCP

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

La Listings API ospita un server Model Context Protocol (MCP) all'indirizzo https://listingsapi.com/mcp. Non c'è nulla da installare o eseguire. Un assistente AI che supporta MCP si collega a quell'URL, individua uno strumento per ogni endpoint REST più alcuni strumenti di documentazione e li chiama sul tuo account. Questa guida illustra come collegare ciascuno dei principali client e poi verificare il collegamento.

1. Scopri quali strumenti ha a disposizione l'agente

Il server espone poco più di 60 strumenti, di cui circa due terzi sono di sola lettura. I nomi seguono quelli delle 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 di documentazione, search_docs, get_doc e get_endpoint, permettono all'assistente di consultare una pagina o il contratto di un endpoint anziché ipotizzare la struttura di un 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 lato server, quindi i limiti di frequenza e i report sull'utilizzo sono identici.

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

3. Collega 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 (Collega). Claude esegue il flusso OAuth, tu approvi gli scope 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 i membri fanno successivamente clic su Connect (Collega) per quel connettore. Claude si collega dai server di Anthropic, non dal tuo computer, ed è per questo che l'URL 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, ometti il flag --header ed esegui /mcp all'interno di Claude Code. Usa --scope project per includere in un commit la configurazione del server in un .mcp.json condiviso da tutto il team; 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.

Codex CLI. L'agente da terminale di OpenAI legge i server MCP da ~/.codex/config.toml. Codex avvia autonomamente 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 apre il flusso nel browser. Non includere mai in un commit una chiave all'interno di 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 (oppure 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 elencare 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), e 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 inoltre un client ID e un client secret. Questo server rilascia client PKCE pubblici senza secret, quindi registrane uno con l'URL di reindirizzamento mostrato nel modulo e lascia vuoto il campo del secret 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 secret, segui la procedura con Gemini CLI descritta sopra oppure sviluppa 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, all'interno dell'assistente, chiedi qualcosa che richieda necessariamente l'accesso al tuo account:

Usa gli strumenti listingsapi per dirmi con quale account sono connesso, quante sedi contiene e qual è il mio utilizzo dell'API questo mese.

Una connessione corretta restituisce risposte da whoami, locations_all e get_usage con l'ID e i conteggi effettivi del tuo account. Una chiave errata o scaduta genera un errore Unauthenticated alla prima chiamata a uno strumento, non durante il rilevamento.

Ecco alcuni prompt iniziali utili quando la connessione funziona:

• "Elenca le mie sedi con errori nelle schede e riepiloga ciascun errore."
• "Mostra le recensioni ricevute negli ultimi 7 giorni che non hanno una risposta e prepara una bozza di risposta per ciascuna. Non inviarle ancora."
• "Confronta i dati analitici 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 per agenti di listingsAPI

Le skill sono istruzioni che un agente carica quando un'attività corrisponde al loro ambito, così da seguire un flusso di lavoro collaudato invece di elaborarne uno. Funzionano insieme al server MCP: il server esegue le chiamate e la skill decide quali chiamate effettuare e in quale ordine. Cinque skill di 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 i rispettivi agenti e aggiungi -g per installare la skill per tutti i progetti invece che solo per quello corrente.

Trova listingsAPI nelle directory di strumenti di IA

Lo stesso server è presente in queste directory, insieme alla skill per agenti di listingsAPI. Esegui l'installazione dalla directory 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 effettuare il polling.
• Autenticazione e Codici di errore per i codici che l'assistente ti segnalerà.