Server MCP

Il server MCP di TracePass consente a un assistente IA di guidare direttamente la piattaforma TracePass — elencare e creare prodotti, costruire e verificare passaporti digitali di prodotto, impostare gli operatori economici e leggere o acquisire eventi della catena di approvvigionamento GS1 EPCIS. Parla l'intero Model Context Protocol: tools, resources e prompts. Collegate un endpoint ospitato oppure eseguitelo localmente tramite npx — entrambi si autenticano con le stesse chiavi API tp_dell'API v1. Codice sorgente su GitHub, pubblicato come tracepass-mcp-server su npm.

Che cos'è

MCP è un protocollo aperto che consente a un assistente IA di chiamare tools esterni e leggere dati esterni attraverso un'unica interfaccia standard. Il server MCP di TracePass è un adattatore leggero e senza stato davanti all'API v1 di TracePass — non ha un database proprio; ogni chiamata di tool e ogni lettura di resource passa direttamente attraverso la stessa API usata dalle vostre altre integrazioni, quindi autenticazione, gating per piano e limiti di frequenza si comportano in modo identico. Ci sono due modi per collegarlo. Il server ospitato gira su https://ai.tracepass.eu/mcp su HTTP — niente da installare, sempre aggiornato. Il server locale è il pacchetto npm tracepass-mcp-server, avviato come sottoprocesso dal vostro client MCP e che parla MCP su stdio.

Collegamento (ospitato)

Puntate il vostro client MCP all'endpoint ospitato e passate la vostra chiave API come token Bearer. Generate una chiave nella dashboard sotto Developer → API Keys — è la stessa chiave tp_usata dall'API v1. Aggiungete questo blocco alla configurazione MCP del vostro client:

json

{
  "mcpServers": {
    "tracepass": {
      "url": "https://ai.tracepass.eu/mcp",
      "headers": { "Authorization": "Bearer tp_YOUR_KEY" }
    }
  }
}

Collegamento (locale / npx)

Per una configurazione locale, il vostro client MCP avvia il pacchetto npm come sottoprocesso e comunica con esso su stdio. Non c'è nulla da installare in anticipo — npx scarica tracepass-mcp-serveralla prima esecuzione. La chiave API viene passata tramite la variabile d'ambiente TRACEPASS_API_KEY invece che tramite un header:

json

{
  "mcpServers": {
    "tracepass": {
      "command": "npx",
      "args": ["-y", "tracepass-mcp-server"],
      "env": {
        "TRACEPASS_API_KEY": "tp_YOUR_KEY"
      }
    }
  }
}

Tools

Le operazioni dell'API v1 di TracePass sono raggruppate in cinque tools. Ognuno accetta un' action più argsspecifici dell'azione, così l'assistente sceglie il tool per dominio e l'operazione per action:

Tool	Azioni
`tracepass_products`	`list, get, create, update` Operazioni sul catalogo — sfogliare, leggere e creare o aggiornare prodotti.
`tracepass_passports`	`list, get, get_by_serial, create, suspend, archive, get_qr` Il ciclo di vita del passaporto — elencare e leggere passaporti, cercarne uno per numero di serie, creare, sospendere, archiviare e recuperare il codice QR.
`tracepass_passport_fields`	`update` Aggiornare singoli campi del template su un passaporto.
`tracepass_passport_parties`	`set, remove` Impostare o rimuovere gli operatori economici (fabbricante, importatore, riciclatore e così via) su un passaporto.
`tracepass_epcis`	`export, capture, capture_job, query` Leggere e scrivere eventi della catena di approvvigionamento GS1 EPCIS 2.0 — esportare la cronologia degli eventi di un passaporto, acquisire nuovi eventi, eseguire un job di acquisizione e interrogare l'archivio degli eventi.

Alcune azioni di scrittura costano denaro o sono irreversibili. Le descrizioni dei tools del server lo dicono al modello, ma dovreste saperlo anche voi: tracepass_passports con azione createconsuma uno slot DPP fatturabile del vostro piano — la creazione oltre la quota comporta un addebito di overage per passaporto e procede solo dopo che l'utente acconsente tramite confirmOverage. L'azione archive è irreversibile; usate suspend quando potreste aver bisogno di recuperare il passaporto. Le azioni di tracepass_epcis (capture, query, export) sono incluse in ogni piano a pagamento e misurate per eventi al mese secondo la tabella dei piani su /pricing.

Resources

Le resources sono dati di entità in sola lettura che l'utente allega come contesto della conversazione, indirizzati da un URI tracepass://. Una è una resource statica, le altre sono resource templates che il client completa con un id:

tracepass://products
tracepass://product/{id}
tracepass://passport/{id}
tracepass://passport/{id}/epcis

Prompts

I prompts sono flussi di lavoro DPP riutilizzabili che il client MCP propone all'utente, tipicamente come comandi slash. Ognuno avvia la conversazione in modo che l'assistente svolga il compito come TracePass prevede — per esempio confermando sempre prima di creare un passaporto fatturabile:

audit_passport
onboard_product
review_epcis_events