Server MCP — collega assistenti IA ai dati DPP

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. Presente nel registro MCP ufficiale come eu.tracepass/tracepass.

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-server alla 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 sei tools. Ognuno accetta un' action più args specifici 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, compliance, registry_readiness, get_condition_flags, get_condition_flags_by_serial, set_condition_flags, set_condition_flags_by_serial, create, suspend, suspend_by_serial, archive, archive_by_serial, get_qr, get_qr_by_serial, list_snapshots, get_snapshot, capture_measurements, capture_measurements_by_serial, list_measurements, list_measurements_by_serial, latest_measurements, latest_measurements_by_serial` Il ciclo di vita del passaporto — elencare e leggere passaporti, cercarne uno per numero di serie, creare, sospendere, archiviare, recuperare il codice QR o un Data Matrix e leggere la cronologia delle istantanee, inclusa la versione valida a una certa data.
`tracepass_passport_fields`	`update, update_by_serial` 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, export_by_serial, 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.
`tracepass_templates`	`list, get` Leggere lo schema normativo di ogni categoria di DPP — cosa deve contenere un passaporto conforme e quale Regolamento UE sta dietro ogni campo obbligatorio. Permette all'agente IA di consigliare sui requisiti prima che tu crei qualcosa.

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 create consuma 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, Free compreso, e misurate per eventi al mese secondo la tabella dei piani su /pricing.

Chi ha scritto un valore resta registrato. Un aggiornamento tramite tracepass_passport_fields viene scritto con i diritti di chi ha collegato l'assistente: una chiave API o un amministratore lo scrive come approvato, mentre un'app collegata che agisce per un editor lo invia in revisione, come farebbe la dashboard. Quando l'assistente ha trovato o dedotto un valore da solo (ricerca sul web, lettura di un documento) invece di riceverlo, passa source: "ai_suggested" e il valore attende nella coda di revisione della dashboard l'approvazione di una persona. I campi che solo l'operatore economico può dichiarare, o che devono essere misurati, rifiutano un valore di questo tipo. Ogni modifica è registrata nella cronologia del passaporto con la credenziale e il canale. La pubblicazione non è disponibile per l'assistente: resta nella dashboard.

Resources

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

tracepass://products
tracepass://product/{id}
tracepass://passport/{id}
tracepass://passport/{id}/epcis
tracepass://passport/{id}/compliance
tracepass://passport/{id}/registry-readiness
tracepass://passport/{id}/snapshots
tracepass://templates
tracepass://template/{category}

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
explain_dpp_requirements
compliance_gap_check

Il copilot di conformità in azione

Insieme, lo strumento dei template e i prompt trasformano l'assistente in un copilot di conformità per i DPP — sa cosa richiede il Regolamento per ciascuna categoria, non solo come inserire i dati. Ecco una sessione rappresentativa per un fabbricante di batterie:

text

You  ▸  What does a compliant battery passport need, and which fields will be hardest to source?

TracePass copilot  ▸  Calling tracepass_templates(get, battery)…

  A battery DPP is governed by the EU Battery Regulation (EU) 2023/1542,
  mandatory from 18 Feb 2027. The template covers the Annex XIII field set. By
  access level:

    • Public (consumer-facing): manufacturer identity, battery
      category, weight, capacity, hazardous substances, recycled-
      content shares (Co, Pb, Li, Ni), carbon footprint, due-
      diligence report. — Art. 77, Annex XIII
    • Restricted (legitimate interest): cell materials (cathode,
      anode, electrolyte), dismantling and removal info, state of
      health, expected lifetime.
    • Authority-only: test reports, third-party audit results,
      recycled-content documentation.

  Hardest to source up front: the recycled-content shares and the
  carbon-footprint declaration — those usually live with your cell
  supplier. Want me to draft a supplier request for them?

You  ▸  Yes — and gap-check passport SN-2026-00042 before I publish it.

TracePass copilot  ▸  Running the compliance_gap_check prompt…

  Against the battery schema, SN-2026-00042 is NOT publishable yet:

    ✗ carbonFootprintDeclaration — empty (required, Art. 7)
    ✗ recycledContentCobalt — empty (required, Annex XIII)
    ✗ recycler party — not set
    ⚠ stateOfHealth — present but pending review

  Everything else is approved. Fix the two empty required fields and
  add the recycler party, and it's ready. Most important first:
  the carbon-footprint declaration — it blocks publishing and takes
  the longest to obtain.