MCP

La stessa API, rivolta a un assistente anziché a uno scenario. Un client MCP sceglie cosa chiamare mentre gira, dalle descrizioni degli strumenti, quindi raggiunge esattamente ciò che raggiungono le sue credenziali, e sotto ogni strumento c’è una chiamata all’API pubblica.

Un solo endpoint

Tutto va a POST /v1/mcp. Non c’è sessione da aprire né flusso da tenere: GET e DELETE rispondono 405, e ogni messaggio è una richiesta a sé.

POST https://api.mosaqo.app/v1/mcp
Authorization: Bearer $MOSAQO_KEY
MCP-Protocol-Version: 2026-07-28

Le revisioni del protocollo da 2025-03-26 a 2026-07-28 sono servite tutte. Un client che apre con initialize ottiene la stretta di mano che si aspetta; quello che dichiara la versione a ogni richiesta è servito così.

Collegare con una chiave API

La via più rapida, e quella giusta per uno strumento che gestisci tu. Qualsiasi chiave funziona come token bearer, e gli strumenti offerti sono ridotti agli ambiti di quella chiave.

La maggior parte dei client accetta un blocco come questo:

{
  "mcpServers": {
    "mosaqo": {
      "type": "http",
      "url": "https://api.mosaqo.app/v1/mcp",
      "headers": { "Authorization": "Bearer $MOSAQO_KEY" }
    }
  }
}

curl -X POST https://api.mosaqo.app/v1/mcp \
  -H "Authorization: Bearer $MOSAQO_KEY" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: tools/list" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }'

Collegare via OAuth

Per un connettore nella directory di qualcun altro, dove la persona non tocca mai una chiave. La scoperta segue RFC 9728 e RFC 8414, i client si registrano da soli con RFC 7591, e ogni autorizzazione usa PKCE con S256.

curl https://api.mosaqo.app/.well-known/oauth-protected-resource
curl https://api.mosaqo.app/.well-known/oauth-authorization-server

Una chiamata non autorizzata dice da sé dove andare e cosa chiedere:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="Mosaqo MCP",
  resource_metadata="https://api.mosaqo.app/.well-known/oauth-protected-resource",
  scope="qr:read analytics:read reviews:read exports:read"

Chi approva ha effettuato l’accesso a Mosaqo, sceglie lo spazio a cui si applica e può farlo solo dove è proprietario o amministratore — la stessa linea che decide chi può emettere una chiave API. Dopo si scollega da Bulk & API.

Cosa può fare un assistente

Gli ambiti che già conosci, invariati. Uno strumento che le credenziali non consentono non compare in tools/list e non si chiama nemmeno nominandolo: la risposta viva per ogni connessione è tools/list stesso.

Scope	Consente
`qr:read`	Elencare e leggere codici QR, cartelle e modelli
`qr:write`	Creare, modificare, riorientare, pubblicare, archiviare ed eliminare
`exports:read`	Scaricare le card renderizzate
`analytics:read`	Analitiche aggregate e singole scansioni
`bulk:write`	Creare e leggere job in blocco
`webhooks:write`	Gestire le sottoscrizioni ai webhook
`reviews:read`	Luoghi, sondaggi e come stanno andando — mai le risposte stesse

Cosa non raggiungerà mai

Ciò che le persone hanno scritto in un sondaggio. reviews:read apre i tuoi luoghi, i tuoi sondaggi e come stanno andando: i conteggi, i punteggi, la distribuzione per domanda. Le frasi digitate da un visitatore non sono restituite qui più che altrove dove arrivino delle credenziali, per la stessa ragione per cui gli eventi feedback.* portano un punteggio e mai le parole.

Cancellare un codice. La rotta REST chiede una conferma digitata perché distruggere il reindirizzamento di un codice stampato non si annulla, e non è una conferma che un assistente dà al posto di qualcuno. Al suo posto c’è l’archiviazione, che è reversibile.

La scrittura è marcata come scrittura. Uno strumento che cambia qualcosa porta readOnlyHint: false, e archiviare porta destructiveHint: true: è questo che fa fermare un client a chiedere a una persona prima di agire.