TracePass

TracePass MCP Server

A Model Context Protocol server for [TracePass](https://www.tracepass.eu) — the EU Digital Product Passport platform. It lets AI assistants (Claude, Cursor, IDE agents) manage products, Digital Product Passports, economic-operator parties, and GS1 EPCIS 2.0 supply-chain events.

It speaks the full MCP protocol — tools, resources, resource templates, and prompts.

Two ways to use it

The same server core ships two ways:

1. Hosted — point your MCP client at https://ai.tracepass.eu/mcp. Nothing to install; always current.
2. Local (npm) — run tracepass-mcp-server via npx. The MCP client launches it as a subprocess and speaks MCP over stdio.

Authentication

The server accepts either of TracePass's two v1 auth methods on the same Authorization: Bearer … header — it forwards whatever you send to the API, which decides. Pick the one that fits how you're connecting:

Which should an AI assistant use? If your MCP client supports OAuth (Claude.ai, ChatGPT, and others), prefer OAuth — the user authorizes the connection once on a TracePass consent screen, you never handle a secret, and access is least-privilege and revocable. If your client only takes a header/token, use an API key.

OAuth 2.0 (recommended for hosted clients)

No config beyond pointing your client at the hosted endpoint — discovery is automatic. On the first unauthenticated request the server returns a 401 whose WWW-Authenticate header carries a resource_metadata URL (RFC 9728) pointing at /.well-known/oauth-protected-resource, which names the TracePass authorization server. The client runs the standard authorization-code flow with PKCE (/api/oauth/authorize → /api/oauth/token), the user approves scopes, and the client stores + refreshes the token. If you distribute your own client, register an app under Developer → OAuth Apps to get a client_id; many hosted clients self-register via Dynamic Client Registration automatically.

Request only the scopes you need, e.g. passports:read passports:write offline_access. Users manage connected apps (and revoke) under Developer → OAuth Apps → Connected Apps.

API key

Mint a tp_… key under Developer → API Keys and send it as a Bearer token.

Hosted:

{

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

Local (npx / stdio) — the local subprocess can't do an interactive OAuth consent step, so it's API-key only, via the TRACEPASS_API_KEY env:

{

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

Optional env vars:

The hosted endpoint accepts POST only on /mcp, /compliance/mcp, and the supplier paths. GET and DELETE are rejected with 405 to prevent the SDK's stateless transport from opening an unbounded SSE stream.

Tools

The TracePass v1 API operations are grouped into 8 tools. Each takes an action enum plus action-specific arguments. The tools are:

• tracepass_products - manage the product catalogue (list, get, create, create_batch, update products).
• tracepass_passports - manage Digital Product Passports (list, get, compliance check, registry-readiness check, prepare an EU DPP Registry registration, record an acceptance test, get/set condition flags, create, get QR, list snapshots, get snapshot), by id or by serial. Passports are identified via GS1 or four additional EN 18219 schemes (iso15459, iec61406, did, doi); battery passports accept only gs1 and iso15459 (Art. 77(3)). Condition flags are approved yes/no facts (e.g. battery: hasBMS, rechargeable, externalStorageOnly, isStationaryBess) that gate conditional legal duties — setting an approved flag may make additional fields required and block publishing if those fields are empty.
• tracepass_passport_fields - update a passport's category-specific data fields, by id or by serial.
• tracepass_passport_parties - set or remove a passport's economic-operator parties (manufacturer, importer, etc.).
• tracepass_epcis - export, capture, and query a passport's GS1 EPCIS 2.0 supply-chain events.
• tracepass_templates - list and get the DPP category field schemas, each field traced to the EU instrument that mandates it.
• tracepass_scope - check whether a product type needs a Digital Product Passport (check), read the company's catalogue-wide scope report (catalogue_report), and trigger or poll a catalogue refresh run (catalogue_run, catalogue_run_status).
• tracepass_passport_lifecycle - irreversible and public-facing passport and product lifecycle actions (record_registration, undo_registration, place_on_market, suspend, archive, archive_product); the assistant must confirm with the user before each call.

Each tool's full action set:

Changed in 1.24.0: archive, archive_by_serial, suspend, suspend_by_serial, and place_on_market moved from tracepass_passports to tracepass_passport_lifecycle; archive on products moved there as archive_product. This separates irreversible and public-facing actions so a client's "always allow" on the read-only passport tool no longer also allows them. Calls to the old names on the old tools return an error naming the new tool.

The ***_by_serial** actions address a passport by the customer's own serial number instead of its TracePass id. A serial is unique only *within a GTIN*, so if the same serial exists under two GTINs in your account a serial-only call returns 409 `ambiguous_serial` — pass the optional gtin arg to disambiguate (or use the by-id action). The same gtin disambiguator applies to every *_by_serial action.

The `tracepass_passports` `compliance` action returns a three-tier compliance verdict (compliant / compliant_with_warnings / incomplete) with regulation-cited findings — missing required fields, missing economic-operator parties, format issues, and per-category conditional rules. Read-only; use it to gap-check a passport, fix the cited gaps, then re-check.

A `compliant` verdict means this passport satisfies the rules encoded here, not *this product may be placed on the market*. The field specifications are hand-authored from the regulations, not an official EU artefact, and delegated acts are still landing. It is not legal advice.

Second-life batteries

A repurposed, remanufactured or reused battery needs a new passport linked to the original one(s) (Battery Regulation Art. 77(7)). Pass a lineage block to tracepass_passports create:

{ "predecessors": [ { "internalPassportId": "<your original passport id>", "trigger": "repurposing" } ] }

A predecessor is named by internalPassportId (one of your own passports) or by its resolvable identifier. trigger is one of preparation_for_reuse, preparation_for_repurposing, repurposing or remanufacturing. The platform derives batteryStatus from the triggers, stores the block immutably, and links your own originals back to the new passport (successors). A battery placed on the market before 18 Feb 2027 has no original passport: send an empty list with noPredecessorReason. Rule violations return 422 with the rule code.

Battery measurements (living record)

capture_measurements pushes over-life data from your own equipment into a published battery passport: state of health, fades, cycle counts, dynamic values, state of charge, negative events, temperature history (Battery Regulation Annex XIII point 4). Every measurement is kept; the newest per field becomes the passport's current value and sets dynamicDataAsOf. list_measurements and latest_measurements read them back.

They are metered against the plan's monthly measurement allowance, not the daily write budget. Paid plans keep counting past the allowance at no charge; the Free plan stops at its allowance. Reading a passport is never metered.

Registering a battery passport in the EU DPP Registry

The economic operator registers a battery passport itself, on the EU DPP Registry website under its own EU Login. TracePass prepares what the operator submits and records what the operator reports; it never submits to the Registry and never verifies the outcome.

1. tracepass_passports registry_readiness — would the Registry's formal checks pass?
2. tracepass_passports prepare_registry_upi returns the exact address (upi) to paste into the Registry's online form. For several passports, prepare_registry_upload_file ({ passportIds }, up to 100) returns xml to upload unchanged under filename; passports that would fail are left out and listed in excluded with a reason, because the Registry fails a whole file on one bad entry.
3. The Registry's acceptance environment is for testing and has no legal effect: tracepass_passports record_acceptance_test records its result and changes nothing else.
4. After registering in production, tracepass_passport_lifecycle record_registration records