> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mattone.co/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Mattone: la porta unica per gli strumenti del team

> Cos'è l'MCP Mattone, come collegarlo su Claude Desktop e su Claude Code, la prima prova per verificare che funzioni, come si aggiorna, le regole e gli errori più comuni.

<Note>
  Questa pagina serve a **collegarti**. Per l'elenco completo di cosa puoi chiedere una volta collegato, vedi [MCP Mattone Platform](/riferimenti/mcp-delivery).
</Note>

## Cos'è

L'**MCP Mattone** è una porta sola: da lì il tuo Claude arriva alla Mattone Platform (studenti, voci, richieste ai fornitori) e, mano a mano che vengono collegati, agli altri sistemi del gruppo — HQ, Wise, GHL, i connettori degli studenti. Non installi uno strumento diverso per ognuno: è sempre lo stesso indirizzo.

**Ognuno vede solo gli strumenti che il proprio token abilita.** È il token a decidere cosa puoi fare, non la pagina che stai leggendo: due persone collegate allo stesso indirizzo possono vedere cose diverse.

## Come collegarlo

Ti serve un indirizzo, consegnato in `#mattone-team`. Ha questa forma:

```text theme={null}
https://mcp.mattone.co/api/mcp/team/<il-tuo-token>
```

<Warning>
  L'ultima parte è **il tuo token**: l'indirizzo intero vale come una password. Le regole per trattarlo sono più sotto — leggile prima di incollarlo da qualche parte.
</Warning>

Scegli il modo giusto per come lavori: non serve farli entrambi.

### Claude Desktop (o Claude sul web)

<Steps>
  <Step title="Apri Personalizza → Connettori">
    Vai su **Personalizza → Connettori**, clicca **+**, poi **Aggiungi connettore personalizzato**.

    <Note>
      Il nome del menu cambia ogni tanto con gli aggiornamenti di Claude. Se il tuo Claude è su un piano Team/Enterprise e non vedi questa voce, il connettore va prima aggiunto da chi amministra l'organizzazione (**Impostazioni organizzazione → Connettori**) — chiedilo in `#mattone-team`. Se non lo trovi comunque, cerca "connettori" nelle impostazioni.
    </Note>
  </Step>

  <Step title="Incolla l'indirizzo">
    Incolla l'indirizzo con il tuo token, dai un nome al connettore (per esempio `Mattone`) e salva. Non ti chiede né utente né password: il riconoscimento è già dentro l'indirizzo.
  </Step>
</Steps>

### Claude Code

<Steps>
  <Step title="Aggiungi il server dal terminale">
    ```bash theme={null}
    claude mcp add --transport http mattone https://mcp.mattone.co/api/mcp/team/<il-tuo-token> --scope user
    ```

    Sostituisci `<il-tuo-token>` con quello che ti è stato consegnato. `mattone` è solo il nome con cui lo vedi tu nell'elenco: puoi chiamarlo come vuoi. `--scope user` lo rende disponibile in ogni cartella in cui apri Claude Code, non solo nel progetto in cui l'hai aggiunto.
  </Step>

  <Step title="Verifica che sia in elenco">
    ```bash theme={null}
    claude mcp list
    ```

    Deve comparire `mattone` come collegato. Se non c'è, chiudi e riapri il terminale e riprova.
  </Step>
</Steps>

## Prima prova

Chiedi al tuo Claude:

> chi sono?

Deve risponderti con il tuo nome, la versione dell'MCP che stai usando e cosa può fare per te. Se ti risponde così, sei collegato **davvero**: comparire nell'elenco dei connettori vuol dire che il programma parte, non che ti riconosce.

### Esempio di risposta corretta

Un token con permessi di delivery (voci, richieste ai fornitori, group call) risponde più o meno così — i nomi qui sotto sono d'esempio, non un token vero:

> Sei **Mario Rossi**. Stai usando la versione `2026-09-16` dell'MCP Mattone, connettore `2.0.0`. Hai **12 strumenti** disponibili: puoi leggere studenti, voci, richieste, brand e group call; aprire, aggiornare e chiudere voci; aprire e aggiornare richieste ai fornitori.

Dentro, la risposta grezza che il tuo Claude legge (non serve leggerla tu, è qui solo per chi vuole controllare) è un JSON come questo:

```json theme={null}
{
  "modalita": "piattaforma",
  "versione_api": "2026-09-16",
  "chi": "Mario Rossi",
  "email": "mario.rossi@mattone.co",
  "scopes": ["read", "write_tasks", "write_requests"],
  "puo_scrivere": true,
  "tool_disponibili": 12,
  "connettore": { "nome": "MCP Mattone", "versione": "2.0.0" }
}
```

<Info>
  Il numero di strumenti cambia da persona a persona: dipende dagli scope del token, non da questa pagina. Chi ha anche `write_group_calls` o `read_payments` ne vede di più; chi ha solo `read` ne vede meno.
</Info>

Su Claude Code, `claude mcp list` conferma solo che il collegamento parte — non che il token è valido:

```text theme={null}
mattone: https://mcp.mattone.co/api/mcp/team/<token> (HTTP) - ✓ Connected
```

## Aggiornamento

Il connettore è **remoto**: non è un programma installato sul tuo computer, quindi non lo reinstalli e non lo aggiorni a mano — chi lo gestisce lo aggiorna dal suo lato. Se un giorno gli strumenti che ti aspetti non compaiono più, **scollega e ricollega**: rimuovi il connettore e aggiungilo di nuovo con lo stesso indirizzo. Non serve altro, e non perdi niente.

## Regole

* **Ogni problema è una voce.** Se qualcosa non va, apri una voce invece di scriverlo solo in chat — in chat si perde. Quando la chiudi, scrivi l'esito. Procedura completa: [La coda Voci](/delivery/coda-voci).
* **Mai chiavi o token in chat.** Neanche per farli vedere a qualcuno, neanche in un messaggio privato: è lo stesso rischio di scriverli in un canale pubblico. Le chiavi degli studenti (PMS, Conduit, GHL...) non passano **mai** dall'MCP: nessuno strumento le legge né le scrive da qui, restano solo nel registro chiavi del repo interno (sotto).
* **Il token non si condivide.** È tuo e vale come una password. Non te lo crei da solo e non lo revochi da solo: lo fa **Francesco**. Se pensi che qualcuno l'abbia visto, dillo subito in `#mattone-team`.

## Le voci e la memoria dello studente

Le voci che apri e chiudi da qui non sono l'unico posto dove vive il lavoro su uno studente — si incastrano con la sua **scheda**, che sta in un repo interno separato (`mattone-delivery-private`, non pubblico: lo vedono solo Mattia e Simone).

* Le **voci** (qui, o `/admin/voci`) sono il lavoro **aperto**: cosa c'è da fare, per chi, con che priorità.
* La **scheda dello studente**, sezione **Storia**, è la memoria di **lungo periodo**: una riga per intervento — configurazioni cambiate, trappole scoperte, decisioni prese — con la voce collegata quando c'è. Ci scrive a mano solo chi lavora in profondità su uno studente.
* **Non devi copiare nulla a mano.** Un giro automatico sul server porta ogni voce che chiudi (da qui o da `/admin/voci`) dentro la Storia dello studente giusto, entro una decina di minuti, con chi l'ha chiusa e l'esito che hai scritto.

Se il tuo lavoro sono solo voci, ticket e script, non hai bisogno di aprire quel repo: quello che fai ci arriva comunque. Chi ci scrive a mano lo fa per le cose che non nascono da una voce — una configurazione toccata, una trappola capita sul campo.

## Errori comuni

| Cosa leggi | Cosa vuol dire | Cosa fai |
| - | - | - |
| Token non valido | il token è scaduto, sbagliato, o è stato revocato | chiedi a Francesco un token nuovo — quello vecchio non è recuperabile, ed è voluto |
| Ti manca il permesso X | il token è buono ma quell'azione non è nel tuo ruolo | chiedi in `#mattone-team` di allargare il permesso: non serve rifare il collegamento |
| Risposta tagliata a metà | la richiesta ha fatto tornare troppi dati insieme | restringi la domanda con un filtro — per data, per stato, per persona — invece di chiedere tutto insieme |

<Info>
  Se qualcosa in questa pagina non torna con quello che vedi, scrivilo in `#mattone-team`: vuol dire che la pagina va corretta. Vedi [Manutenzione docs](/riferimenti/manutenzione-docs).
</Info>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.