malinoto/tracepass-mcp-server

A Model Context Protocol server for
**TracePass** — 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:
| | **API key** | **OAuth 2.0** |
|---|---|---|
| Best for | A single user, scripts, server-to-server | AI assistants / apps acting **on a user's behalf** |
| What you send | A static tp_… key as a Bearer token | A scoped access token obtained via the OAuth flow |
| Setup | Mint at **Developer → API Keys** | The user clicks **Connect** and approves scopes |
| Scope | All-or-nothing (the whole workspace) | Exactly the scopes the user granted; revocable |
| Works with | Hosted **and** local (npx) | Hosted endpoint only (needs a browser consent step) |
**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:**
**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:
Optional env var: TRACEPASS_BASE_URL (defaults to
https://app.tracepass.eu) — point the tools at a different
TracePass deployment.
Tools
The TracePass v1 API operations are grouped into **7 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, archive products).
- tracepass_passports - manage Digital Product Passports (list, get, compliance check, registry-readiness check, get/set condition flags, create, suspend, archive, 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.