# Integrazione MCP

TrueScreen supporta integrazioni MCP oltre alla REST Public API. Questo permette a client AI come Cursor o Claude Desktop di chiamare operazioni TrueScreen curate, senza costruire manualmente richieste HTTP grezze.

TrueScreen espone **due server MCP**:

- un **server MCP remoto** per operazioni testuali e JSON,
- un **server MCP locale** per le stesse operazioni più le procedure che richiedono upload di file dalla tua macchina.


```mermaid
flowchart LR
    Client[Client AI]
    Remote[Server MCP remoto]
    Local[Server MCP locale]
    API[TrueScreen Public API]
    Files[Filesystem locale]

    Client --> Remote
    Client --> Local
    Remote --> API
    Local --> API
    Local --> Files
```

## Scegliere il server corretto

| Caso d'uso | MCP remoto | MCP locale |
|  --- | --- | --- |
| Ottenere i crediti | Sì | Sì |
| Elencare i template disponibili | Sì | Sì |
| Creare un True Flow senza upload locale di file | Sì | Sì |
| Creare una certificazione hash | Sì | Sì |
| Creare una certificazione dati | Sì | Sì |
| Consultare lo stato di una certificazione | Sì | Sì |
| Attendere il completamento di una certificazione | Sì | Sì |
| Creare una certificazione file partendo da file su disco | No | Sì |
| Caricare un allegato True Flow partendo da file su disco | No | Sì |


In pratica:

- usa il **server MCP remoto** quando il workflow e interamente basato su testo o JSON;
- usa il **server MCP locale** quando il workflow include un file da leggere dalla tua macchina e caricare.


## Cosa può fare ciascun server

### Disponibile su entrambi i server MCP

Questi tool sono disponibili sia sul server remoto sia su quello locale:

- `truescreen_get_credits`
- `truescreen_list_templates`
- `truescreen_create_true_flow`
- `truescreen_create_hash_certification`
- `truescreen_create_data_certification`
- `truescreen_get_certification`
- `truescreen_wait_for_certification`


### Disponibile solo sul server MCP locale

Questi tool sono disponibili solo sul server locale:

- `truescreen_create_file_certification_attachments`
- `truescreen_upload_file`
- `truescreen_create_file_certification`
- `truescreen_create_true_flow_attachment`


Usa il server locale quando ti serve:

- la **certificazione file**, perche il flusso include l'upload di file,
- l'**upload di allegati True Flow**, perche il file deve essere letto localmente prima del caricamento.


## Mappatura MCP -> REST

Ogni tool MCP corrisponde a una o più chiamate della Public API. Usa questa tabella per passare dalla superficie MCP al punto corrispondente della documentazione REST.

| Tool MCP | Chiamata REST | Documentazione REST |
|  --- | --- | --- |
| `truescreen_get_credits` | `GET /v1/credits` | [Certificazione - Panoramica - Crediti](/it/certification-overview#crediti) |
| `truescreen_list_templates` | `GET /v1/templates` | [Flusso di chiamate True Flow - Flow template token](/it/true-flow-workflow#flow-template-token) |
| `truescreen_create_true_flow` | `POST /v1/true-flows` | [Flusso di chiamate True Flow - Casi d'uso](/it/true-flow-workflow#casi-duso) |
| `truescreen_create_hash_certification` | `POST /v1/hash-certifications` | [Flusso di chiamate Certificazione - Certificazione hash](/it/certification-workflow#1-certificazione-hash) |
| `truescreen_create_data_certification` | `POST /v1/data-certifications` | [Flusso di chiamate Certificazione - Certificazione dati](/it/certification-workflow#2-certificazione-dati) |
| `truescreen_get_certification` | `GET /v1/certifications/{reportId}` | [Flusso di chiamate Certificazione - Consultare lo stato della certificazione](/it/certification-workflow#4-consultare-lo-stato-della-certificazione) |
| `truescreen_wait_for_certification` | Polling su `GET /v1/certifications/{reportId}` | [Certificazione - Panoramica - Processo asincrono](/it/certification-overview#processo-asincrono) |
| `truescreen_create_file_certification_attachments` | `POST /v1/file-certifications-attachments` | [Flusso di chiamate Certificazione - Certificazione file](/it/certification-workflow#3-certificazione-file) |
| `truescreen_upload_file` | `PUT upload_url` sull'URL presigned restituito dall'API | [Flusso di chiamate Certificazione - Passo 2 caricare i file](/it/certification-workflow#passo-2-caricare-i-file) |
| `truescreen_create_file_certification` | `POST /v1/file-certifications` | [Flusso di chiamate Certificazione - Certificazione file](/it/certification-workflow#3-certificazione-file) |
| `truescreen_create_true_flow_attachment` | `POST /v1/true-flows-attachments` e `PUT upload_url` prima di `POST /v1/true-flows` | [Flusso di chiamate True Flow - Creazione True Flow con allegati](/it/true-flow-workflow#3-creazione-true-flow-con-allegati) |


Se ti serve il contratto a livello di schema per una di queste chiamate, usa anche la [specifica OpenAPI](/it/openapi) insieme alle guide operative.

## Installare il server MCP remoto

Il server remoto è l'opzione più semplice quando non ti serve accesso a file locali. Configuri il tuo client MCP con l'URL MCP di TrueScreen e la stessa API key che usi per la REST API.

### Requisiti

- Una API key TrueScreen valida
- Un client MCP che supporti **Streamable HTTP**


### Esempio Cursor

Aggiungi questo al tuo `mcp.json`:

```json
{
  "mcpServers": {
    "truescreen": {
      "url": "https://mcp.truescreen.app/mcp",
      "headers": {
        "Authorization": "Bearer abc..."
      }
    }
  }
}
```

### Note

- La API key viene inviata nell'header `Authorization` come token Bearer.
- Non e richiesto alcun processo locale Node.js.
- Qualsiasi client MCP con configurazione equivalente di URL e header può usare lo stesso server remoto.


## Installare il server MCP locale

Il server locale gira come processo Node.js sulla tua macchina. E la scelta corretta quando il workflow richiede file presenti su disco.

### Requisiti

- Una API key TrueScreen valida
- **Node.js 20 o successivo**


### Esempio Cursor

Aggiungi questo al tuo `mcp.json`:

```json
{
  "mcpServers": {
    "truescreen-local": {
      "command": "npx",
      "args": ["-y", "@truescreen/mcp"],
      "env": {
        "TRUESCREEN_API_KEY": "abc..."
      }
    }
  }
}
```

### Selezione opzionale dell'ambiente

Se ti serve un ambiente non di produzione, puoi impostare anche `MCP_ENV` a `stg`.

```json
{
  "mcpServers": {
    "truescreen-local": {
      "command": "npx",
      "args": ["-y", "@truescreen/mcp"],
      "env": {
        "TRUESCREEN_API_KEY": "abc...",
        "MCP_ENV": "stg"
      }
    }
  }
}
```

### Note

- Usa il server locale come pacchetto eseguito dal client MCP, tipicamente con `npx -y @truescreen/mcp`.
- Nell'uso normale non devi installarlo nel progetto applicativo con `npm i @truescreen/mcp`.
- Il nome del pacchetto locale e `@truescreen/mcp`.
- Il client avvia il processo per te; non devi eseguire manualmente un demone separato.
- Puoi configurare nello stesso client MCP sia il server remoto sia quello locale.


## Scelta tipica

Usa **MCP remoto** quando vuoi la configurazione più rapida e il tuo workflow non deve caricare file.

Usa **MCP locale** quando vuoi:

- creare certificazioni file partendo da documenti locali,
- caricare allegati per un True Flow,
- tenere nello stesso client MCP sia le operazioni testuali sia quelle con upload.


## Guide collegate

- [Certificazione - Panoramica](/it/certification-overview)
- [Flusso di chiamate Certificazione](/it/certification-workflow)
- [Flusso di chiamate True Flow](/it/true-flow-workflow)