Agents

Perché collegarsi tramite StarReview

Un agente può scrivere una risposta, ma non può mai pubblicare direttamente a nome dell'attività. StarReview detiene l'accesso approvato al Profilo dell'attività su Google e applica le Sue impostazioni esistenti di approvazione e pubblicazione automatica. TripAdvisor, Booking.com, Expedia e HolidayCheck non dispongono di API per le risposte, quindi il titolare pubblica tramite un link fornito. Collegato tramite StarReview, il Suo agente ottiene:

• Pubblicazione sul Profilo dell'attività su Google tramite l'infrastruttura di StarReview, a nome dell'attività
• Per TripAdvisor, Booking.com, Expedia e HolidayCheck (che non dispongono di API per le risposte), una risposta pronta da pubblicare più un link diretto tramite cui il titolare la pubblica
• La voce propria dell'attività, appresa dalle risposte passate e dalle modifiche del titolare
• I testi dell'agente e le risposte modificate o trattenute dai controlli di sicurezza restano sempre in attesa
• Un controllo del sentiment su ogni bozza, così non esce nulla che non dovrebbe uscire
• Una tracciabilità completa di ogni azione dell'agente

Guide per il Suo agente

Guide passo per passo per ogni agente, dal collegamento alla prima approvazione:

Preferisce la riga di comando? La CLI StarReview (@starreview/cli) stampa JSON su stdout ed è costruita per agenti e script.

Provare senza account

Tre strumenti non richiedono alcuna credenziale. Punti un qualsiasi client MCP all'endpoint senza header Authorization e ottiene:

• get_service_info: che cosa fa StarReview, quanto costa e come ci si autentica
• search_business: trovare un'attività su Google Maps per nome e città
• check_response_rate: la quota di recensioni Google recenti di un'attività che ha ricevuto una risposta del titolare, confrontata con due concorrenti vicini

Di sola lettura e con un limite per IP. Dopo l'autenticazione riceve invece i sette strumenti per l'attività; i due insiemi sono separati, quindi un client autenticato non vede più questi.

Endpoint

https://mcp.starreview.ch/

MCP HTTP streamable. Si colleghi via OAuth (consigliato, vedi sotto) oppure si autentichi con una chiave Bearer del titolare valida per l'intero account nell'header Authorization: Bearer. Invii Accept: application/json, text/event-stream a ogni richiesta. Lo stesso server è raggiungibile anche su https://api.starreview.ch/api/agent/mcp. L'informativa corrente sulla privacy per Agenti e MCP descrive come vengono trattati i dati degli agenti.

La discovery OAuth segue la RFC 9728: recuperi https://mcp.starreview.ch/.well-known/oauth-protected-resource per trovare il server di autorizzazione, si registri dinamicamente ed esegua il flusso authorization code con PKCE. Una richiesta senza credenziali risponde 401 con un header WWW-Authenticate che punta allo stesso documento, così un client conforme trova la strada da solo.

Tool

• list_locations: le sedi dell'attività per cui sta agendo
• list_unanswered_reviews: le recensioni Google, TripAdvisor, Booking.com, Expedia e HolidayCheck ancora senza risposta, ognuna contrassegnata con la sua piattaforma
• get_review_stats: indicatori delle recensioni di sola lettura: media, tasso di risposta, arretrato e ripartizione per piattaforma
• get_review_context: la recensione completa con le bozze esistenti
• draft_reply: generare una risposta nella voce dell'attività
• submit_reply_for_approval: inviare una variante StarReview alle regole di approvazione e pubblicazione automatica, con testo modificato e orario preferito opzionali. Il testo modificato resta in attesa; le piattaforme senza API per le risposte restituiscono un link per la pubblicazione manuale
• submit_own_reply: mettere il testo di risposta del suo agente nella coda di approvazione, senza bozza StarReview; sempre con approvazione umana, mai programmato automaticamente

Il flusso

1. Il suo agente elenca le recensioni senza risposta e ne legge il contesto.
2. Sottopone una risposta, con la bozza di StarReview o con testo proprio, con orario di pubblicazione preferito opzionale.
3. StarReview valuta la risposta in base al Suo consenso, alle impostazioni e ai controlli di sicurezza. I testi dell'agente e le risposte modificate o trattenute dai controlli di sicurezza restano in attesa.
4. Una bozza StarReview idonea e non modificata può essere programmata automaticamente. Le piattaforme senza API per le risposte restituiscono un link per la pubblicazione manuale.

Collegarsi via OAuth (consigliato)

Da Claude o da qualsiasi client MCP compatibile con OAuth, aggiunga StarReview come connettore e acceda con il suo account StarReview. Approva una volta su una schermata di consenso, poi l'agente può redigere e sottoporre risposte per le attività di sua proprietà. Nessun token da copiare o gestire, e può scollegarlo in qualsiasi momento dalle sue impostazioni StarReview. Il collegamento è limitato alle sue attività: un agente non può mai toccare un'attività che non le appartiene, e continua a non pubblicare mai una risposta da sé.

Se possiede più attività, una connessione OAuth identifica Lei e non una singola attività, quindi l'agente deve indicare quale intende. Chiami uno strumento senza businessId e riceve un selettore invece del lavoro svolto:

{
  "businesses": [
    { "businessId": "...", "name": "Restaurant Adler" },
    { "businessId": "...", "name": "Cafe Baur" }
  ],
  "hint": "You manage multiple businesses. Call again with businessId set to one of these."
}

Questo è un risultato riuscito, non un errore: lo verifichi prima di trattare una risposta come il risultato. Richiami impostando businessId. Gli strumenti che accettano un reviewId non restituiscono mai un selettore: la recensione determina già l'attività. Le chiavi del titolare valide per l'intero account seguono le stesse regole di selezione di OAuth. Solo le credenziali legacy o amministrative esplicitamente limitate fissano un'attività senza selettore.

Collegarsi dal suo codice

Per l'accesso programmatico, o un client senza OAuth, usi invece una chiave Bearer del titolare valida per l'intero account. StarReview è un server MCP standard (HTTP streamable). Dall'API Claude lo aggiunga a mcp_servers e passi la chiave del titolare come authorization_token:

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "messages": [
    { "role": "user", "content": "Prepara le risposte per le mie recensioni senza risposta." }
  ],
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.starreview.ch/",
      "name": "starreview",
      "authorization_token": "sragt_your_business_token"
    }
  ],
  "tools": [
    { "type": "mcp_toolset", "mcp_server_name": "starreview" }
  ]
}

Il connettore MCP è in beta, quindi invii l'header beta attuale del connettore MCP (si veda la documentazione MCP di Anthropic). Gli altri client MCP si collegano allo stesso modo: li punti all'endpoint e imposti l'header Authorization: Bearer.

Esempio di sessione

Un flusso tipico. Ogni chiamata di tool restituisce JSON; le forme qui sotto sono rappresentative.

1. Elencare cosa attende una risposta. Chiamata di list_unanswered_reviews:

[
  {
    "reviewId": "a1b2c3d4-...",
    "starRating": 5,
    "text": "Super Service, sehr freundlich!",
    "reviewerName": "M. Keller",
    "reviewDate": "2026-07-01",
    "sentiment": "positive",
    "provider": "google",
    "hasDraft": false
  }
]

2a. Lasciare che StarReview rediga nella voce dell'attività. Chiamata di draft_reply con il reviewId:

{
  "variants": [
    { "variant": 1, "text": "Vielen Dank fuer die netten Worte, Herr Keller ...", "riskFlags": [] }
  ],
  "language": "de",
  "sentiment": { "bucket": "positive", "confidence": 0.95 },
  "approvalReason": "agent_draft",
  "wouldAutoPublish": true
}

Poi confermi una variante con submit_reply_for_approval ({ "reviewId": "...", "variant": 1 }), con testo modificato opzionale.

2b. Oppure porti il suo testo. Salti la redazione e chiami submit_own_reply:

// request
{ "reviewId": "a1b2c3d4-...", "finalText": "Danke vielmals, Herr Keller!" }

// response
{ "submitted": true, "autoScheduled": false }

autoScheduled è sempre false per il testo proprio: attende sempre un essere umano.

3. StarReview applica le Sue regole. I testi scritti dall'agente e le bozze modificate o trattenute dai controlli di sicurezza restano nella coda di approvazione. Una bozza StarReview idonea e non modificata può essere programmata secondo il Suo consenso e le impostazioni di pubblicazione automatica. Sulle piattaforme senza API per le risposte, il risultato restituisce awaitingManualPost: true e un platformListingUrl; il titolare pubblica manualmente.

Piani

Se un'attività ha già un piano StarReview, il suo agente lavora entro quel piano. Se gestisce un'agenzia con molte attività clienti, o sta costruendo un prodotto su StarReview, ci contatti e configureremo il piano adatto al suo volume.

Ottenere un token

Collegarsi via OAuth non richiede alcuna chiave: accede con il Suo account StarReview e approva. Le chiavi Bearer del titolare valide per l'intero account sono l'alternativa self-service per l'accesso programmatico e coprono le attività possedute da quell'account. Le credenziali legacy o amministrative possono essere esplicitamente limitate a un'attività. Se come agenzia o prodotto di agenti vuole collegare attività clienti, ci scriva e la configureremo.

FAQ