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. 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:

{
  "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:

{
  "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ù argsspecifici dell'azione, così l'assistente sceglie il tool per dominio e l'operazione per action:

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://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:

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 has 94 required fields. By
  access level:

    • Public (consumer-facing): manufacturer identity, battery
      category, weight, capacity, expected lifetime, recycled-content
      shares (Co, Pb, Li, Ni). — Art. 77, Annex VI
    • Restricted (authorised parties): full material composition,
      hazardous-substance breakdown, dismantling info.
    • Authority-only: conformity test reports, due-diligence data.

  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 VI)
    ✗ 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.