--- title: Server MCP description: Server MCP — assistenti IA (Claude, Cursor, IDE) gestiscono prodotti, passaporti, eventi EPCIS. Endpoint ospitato o pacchetto npm locale. canonical: "https://www.tracepass.eu/it/docs/mcp" locale: it source: "https://www.tracepass.eu/it/docs/mcp" --- # Server MCP > Server MCP — assistenti IA (Claude, Cursor, IDE) gestiscono prodotti, passaporti, eventi EPCIS. Endpoint ospitato o pacchetto npm locale. 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](https://github.com/malinoto/tracepass-mcp-server), pubblicato come [tracepass-mcp-server](https://www.npmjs.com/package/tracepass-mcp-server) su npm. Presente nel [registro MCP ufficiale](https://registry.modelcontextprotocol.io) 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, updateOperazioni sul catalogo — sfogliare, leggere e creare o aggiornare prodotti. | | tracepass\_passports | list, get, get\_by\_serial, compliance, create, suspend, suspend\_by\_serial, archive, archive\_by\_serial, get\_qrIl 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, update\_by\_serialAggiornare singoli campi del template su un passaporto. | | tracepass\_passport\_parties | set, removeImpostare o rimuovere gli operatori economici (fabbricante, importatore, riciclatore e così via) su un passaporto. | | tracepass\_epcis | export, export\_by\_serial, capture, capture\_job, queryLeggere 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, getLeggere 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 a pagamento e misurate per eventi al mese secondo la tabella dei piani su [/pricing](https://www.tracepass.eu/pricing). ## 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: ```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 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. ``` **Tip —** Esempio rappresentativo. Le risposte dell'assistente provengono dallo schema di categoria in tempo reale e dai tuoi dati del passaporto tramite gli strumenti qui sopra — la formulazione esatta varia in base al modello e al client.