# Server MCP

> Colleghi Claude, Cursor, Codex o qualsiasi client MCP ai registri di conformità di un ristorante con un URL e la sua chiave API.

Source: https://developers.backresto.com/it/docs/mcp

BackResto gestisce un server **Model Context Protocol** all'indirizzo
`https://api.backresto.com/mcp`. Vi colleghi il suo strumento di IA con la sua
chiave API e potrà interrogare i registri di un ristorante direttamente
dall'interfaccia dello strumento: niente codice, nulla da installare da parte
nostra, nulla da ospitare da parte sua.

Legge attraverso la stessa API Partner di tutto il resto, con la stessa chiave.
**Non può vedere nulla che la chiave non potesse già vedere**: le concessioni
per ristorante e per scope sono applicate dall'API, non dallo strumento che
collega.

## Colleghi il suo strumento

Prima le serve una chiave; veda [Ottenere una chiave](https://developers.backresto.com/it/docs/access). Poi scelga
il suo strumento:

### Claude

1. **Aggiungere un connettore personalizzato**: In Claude, nell'app desktop o su claude.ai, apra Personalizza, poi Connettori, e clicchi su Aggiungi connettore personalizzato. Con un piano Team o Enterprise, un proprietario lo aggiunge prima una volta nelle impostazioni dell'organizzazione.

2. **Dargli un nome e incollare l'indirizzo**: Lo chiami BackResto e incolli questo URL. In Autenticazione e Client OAuth, Claude rileva il nostro server e preseleziona Accedi ora e Registrati automaticamente: mantenga queste due scelte. Non inserisca client ID né secret. Poi clicchi su Aggiungi.

```
https://api.backresto.com/mcp
```

3. **Collegarsi con la chiave**: Clicchi su Connetti. Si apre una pagina BackResto: incolli la sua chiave, che inizia con brp_, e clicchi su Connetti. Claude torna con il connettore attivo e i suoi cinque strumenti.

4. **Fatto**: Chieda con parole normali quello che il ristorante ha registrato. La chiave sa già qual è il suo ristorante.

### Claude Code

1. **Registrare il server**: Apra un terminale ed esegua questo comando, con la sua chiave al posto di brp_YOUR_KEY.

```sh
claude mcp add --transport http --scope user backresto \
  https://api.backresto.com/mcp \
  --header "Authorization: Bearer brp_YOUR_KEY"
```

2. **Verificare la connessione**: Avvii Claude Code e digiti /mcp. backresto risulta connesso, con cinque strumenti.

3. **Fatto**: Chieda con parole normali quello che il ristorante ha registrato. La chiave sa già qual è il suo ristorante.

### Cursor

1. **Aprire le impostazioni MCP**: In Cursor, vada in Settings, poi Tools & MCP, e clicchi su New MCP Server. Si apre mcp.json.

2. **Aggiungere il server**: Incolli questo in mcp.json, con la sua chiave al posto di brp_YOUR_KEY. Il server compare nell'elenco con cinque strumenti.

```json
{
  "mcpServers": {
    "backresto": {
      "type": "http",
      "url": "https://api.backresto.com/mcp",
      "headers": {
        "Authorization": "Bearer brp_YOUR_KEY"
      }
    }
  }
}
```

3. **Fatto**: Chieda con parole normali quello che il ristorante ha registrato. La chiave sa già qual è il suo ristorante.

### Codex

1. **Mettere la chiave nell'ambiente**: Codex legge un token bearer da una variabile d'ambiente anziché dal suo file di configurazione. Aggiunga questa riga al suo profilo della shell, con la sua chiave al posto di brp_YOUR_KEY.

```sh
export BACKRESTO_API_KEY="brp_YOUR_KEY"
```

2. **Registrare il server**: Poi esegua questo una volta. Codex invierà il valore della variabile come header Authorization.

```sh
codex mcp add backresto \
  --url https://api.backresto.com/mcp \
  --bearer-token-env-var BACKRESTO_API_KEY
```

3. **Fatto**: Chieda con parole normali quello che il ristorante ha registrato. La chiave sa già qual è il suo ristorante.

### Altro

1. **Aprire le impostazioni MCP del suo strumento**: Trovi la sezione MCP o integrazioni e aggiunga un server remoto con Streamable HTTP. Se lo strumento chiede solo un URL, apre una pagina BackResto dove incollare la chiave, e l'header non serve.

2. **Inserire l'indirizzo**: Questo è l'URL del server.

```
https://api.backresto.com/mcp
```

3. **Aggiungere la chiave come header**: La invii con ogni richiesta come header Authorization.

```
Authorization: Bearer brp_YOUR_KEY
```

4. **Fatto**: Chieda con parole normali quello che il ristorante ha registrato. La chiave sa già qual è il suo ristorante.

## Gli strumenti

Cinque strumenti: uno che trova il ristorante, e quattro che ne leggono le
[collezioni](https://developers.backresto.com/it/docs/collections).

| Strumento | Cosa fa |
| --- | --- |
| `backresto_list_restaurants` | Elenca i ristoranti che la chiave raggiunge, con i suoi scope su ciascuno. |
| `backresto_list_collections` | Elenca le collezioni concesse a questa chiave, con lo scope che ha aperto ciascuna. È la prima chiamata giusta quando non sa cosa raggiunge la chiave. |
| `backresto_list_records` | Legge una pagina di record da una collezione, tombstone compresi. Accetta `collection`, e facoltativamente `limit` (1-100, predefinito 50) e `cursor`. |
| `backresto_get_record` | Recupera un record tramite `collection` e `recordId`. |
| `backresto_list_record_assets` | Elenca i file allegati a un record (`cleaning-task-pictures`, `delivery-pictures`, `traceability-labels` o `drive-files`) come URL firmati, e mostra le fotografie al modello come immagini che può guardare. |

Le consegne sono due di quelle collezioni, `deliveries` e `delivery-pictures`,
lette con gli stessi strumenti di tutto il resto. Veda [Consegne](https://developers.backresto.com/it/docs/deliveries)
per il significato dei loro campi.

`restaurantId` è facoltativo ovunque. Se lo omette, viene usato il ristorante
della chiave: un ristorante con una sola chiave non ha mai bisogno di
conoscerne l'identificativo. Solo una chiave che raggiunge più ristoranti deve
scegliere, e l'errore elenca le possibilità.

Tutti e cinque sono dichiarati in sola lettura e idempotenti, quindi un client ben
fatto non le chiederà il permesso a ogni chiamata come fa con uno strumento che
scrive.

Due limiti pratici. Le fotografie vengono incorporate per il modello fino a
**dieci immagini e circa 7,5 MB** per chiamata a `backresto_list_record_assets`; tutto ciò che va oltre compare
comunque nel riepilogo, con il suo URL e il motivo per cui non è stato mostrato.
E l'intero endpoint attinge al [budget](https://developers.backresto.com/it/docs/rate-limits) dell'API Partner di
300 richieste al minuto per chiave: una chiamata a uno strumento è una
richiesta, cosa che una conversazione non sfiorerà mai e un ciclo sì.

## Proteggere la chiave

La chiave è tutto il suo accesso, e la configurazione di un client MCP è un file
qualunque su un portatile.

- **Non faccia mai commit di quel file.** Se il suo strumento tiene la
  configurazione in un repository, faccia riferimento a una variabile d'ambiente
  o all'archivio di secret del sistema operativo, come fa la configurazione di
  Codex qui sopra.
- **Dia a ogni macchina la sua chiave.** Una chiave per portatile significa che
  un portatile perso costa una revoca, non una rotazione su tutte le sue
  integrazioni.
- **Ci chieda quando una chiave è stata usata l'ultima volta** se sospetta che
  una copia sia ancora attiva da qualche parte. Vediamo l'ultima autenticazione
  di ogni chiave, e una revoca è la stessa email.

## Collegarsi con il solo URL

Claude (app desktop e claude.ai), ChatGPT e gli altri strumenti che chiedono
solo l'URL di un server si collegano tramite OAuth: si registrano da soli presso
BackResto, poi aprono una pagina BackResto dove incolla la sua chiave una volta.
Niente da installare, nessun file di configurazione. Lo strumento conserva la
chiave e la invia per lei: raggiunge esattamente ciò che la chiave raggiunge, e
revocare la chiave lo scollega.

L'accesso con un account BackResto non esiste ancora: la chiave resta la
credenziale. Se è questo che si frappone tra lei e un'integrazione, ce lo dica:
sale nella lista.

## In cosa è bravo

In concreto, con gli strumenti collegati, un responsabile operativo può
chiedere:

- *«Quali consegne sono state rifiutate il mese scorso, e perché?»*
- *«Mostrami tutte le consegne di pollo sopra i 4 °C in questo trimestre.»*
- *«Mostrami le foto della consegna rifiutata martedì: il danno si vede?»*
- *«Quali frigoriferi sono usciti dai limiti più spesso, e in quale area?»*
- *«I cicli di raffreddamento sono scesi tutti in tempo la settimana scorsa?»*
- *«Quali compiti di pulizia sono stati saltati, e quali non hanno una fotografia?»*

Le prime tre leggono le collezioni `deliveries` e `delivery-pictures`, le
altre leggono altre [collezioni](https://developers.backresto.com/it/docs/collections), e ognuna solo ciò che è
stato concesso alla sua chiave. Le
risposte provengono dagli stessi registri che leggerebbe un ispettore,
attraverso le stesse concessioni che il ristorante ha rilasciato.

A un modello che legge le collezioni va detto cosa sta leggendo: uno snapshot
di ciò che l'API ha ricevuto, non uno storico garantito come completo. Se mette
questo davanti a un cliente, ci metta accanto quella frase.