{
  "markdown": "# TracePass MCP Server\n\n[![Listed on Glama](https://glama.ai/mcp/servers/malinoto/tracepass-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/malinoto/tracepass-mcp-server)\n[![smithery badge](https://smithery.ai/badge/malinoto/tracepass-mcp-server)](https://smithery.ai/servers/malinoto/tracepass-mcp-server)\n\nA [Model Context Protocol](https://modelcontextprotocol.io) server for\n**[TracePass](https://www.tracepass.eu)** — the EU Digital Product\nPassport platform. It lets AI assistants (Claude, Cursor, IDE agents)\nmanage products, Digital Product Passports, economic-operator parties,\nand GS1 EPCIS 2.0 supply-chain events.\n\nIt speaks the full MCP protocol — **tools**, **resources**, **resource\ntemplates**, and **prompts**.\n\n## Two ways to use it\n\nThe same server core ships two ways:\n\n1. **Hosted** — point your MCP client at `https://ai.tracepass.eu/mcp`.\n   Nothing to install; always current.\n2. **Local (npm)** — run `tracepass-mcp-server` via `npx`. The MCP\n   client launches it as a subprocess and speaks MCP over stdio.\n\n## Authentication\n\nThe server accepts **either** of TracePass's two v1 auth methods on the\nsame `Authorization: Bearer …` header — it forwards whatever you send to\nthe API, which decides. Pick the one that fits how you're connecting:\n\n| | **API key** | **OAuth 2.0** |\n|---|---|---|\n| Best for | A single user, scripts, server-to-server | AI assistants / apps acting **on a user's behalf** |\n| What you send | A static `tp_…` key as a Bearer token | A scoped access token obtained via the OAuth flow |\n| Setup | Mint at **Developer → API Keys** | The user clicks **Connect** and approves scopes |\n| Scope | All-or-nothing (the whole workspace) | Exactly the scopes the user granted; revocable |\n| Works with | Hosted **and** local (npx) | Hosted endpoint only (needs a browser consent step) |\n\n**Which should an AI assistant use?** If your MCP client supports OAuth\n(Claude.ai, ChatGPT, and others), prefer **OAuth** — the user authorizes\nthe connection once on a TracePass consent screen, you never handle a\nsecret, and access is least-privilege and revocable. If your client only\ntakes a header/token, use an **API key**.\n\n### OAuth 2.0 (recommended for hosted clients)\n\nNo config beyond pointing your client at the hosted endpoint — discovery\nis automatic. On the first unauthenticated request the server returns a\n`401` whose `WWW-Authenticate` header carries a `resource_metadata` URL\n(RFC 9728) pointing at `/.well-known/oauth-protected-resource`, which\nnames the TracePass authorization server. The client runs the standard\n**authorization-code flow with PKCE** (`/api/oauth/authorize` →\n`/api/oauth/token`), the user approves scopes, and the client stores +\nrefreshes the token. If you distribute your own client, register an app\nunder **Developer → OAuth Apps** to get a `client_id`; many hosted\nclients self-register via Dynamic Client Registration automatically.\n\nRequest only the scopes you need, e.g. `passports:read passports:write\noffline_access`. Users manage connected apps (and revoke) under\n**Developer → OAuth Apps → Connected Apps**.\n\n### API key\n\nMint a `tp_…` key under **Developer → API Keys** and send it as a Bearer\ntoken.\n\n**Hosted:**\n\n```json\n{\n  \"mcpServers\": {\n    \"tracepass\": {\n      \"url\": \"https://ai.tracepass.eu/mcp\",\n      \"headers\": { \"Authorization\": \"Bearer tp_YOUR_KEY\" }\n    }\n  }\n}\n```\n\n**Local (npx / stdio)** — the local subprocess can't do an interactive\nOAuth consent step, so it's API-key only, via the `TRACEPASS_API_KEY` env:\n\n```json\n{\n  \"mcpServers\": {\n    \"tracepass\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"tracepass-mcp-server\"],\n      \"env\": {\n        \"TRACEPASS_API_KEY\": \"tp_YOUR_KEY\"\n      }\n    }\n  }\n}\n```\n\nOptional env var: `TRACEPASS_BASE_URL` (defaults to\n`https://app.tracepass.eu`) — point the tools at a different\nTracePass deployment.\n\n## Tools\n\nThe TracePass v1 API operations are grouped into **6 tools**.\nEach takes an action enum plus action-specific arguments. The tools are:\n\n- `tracepass_products` - manage the product catalogue (list, get, create, create_batch, update, archive products).\n- `tracepass_passports` - manage Digital Product Passports (list, get, compliance check, registry-readiness check, create, suspend, archive, get QR), by id or by serial.\n- `tracepass_passport_fields` - update a passport's category-specific data fields, by id or by serial.\n- `tracepass_passport_parties` - set or remove a passport's economic-operator parties (manufacturer, importer, etc.).\n- `tracepass_epcis` - export, capture, and query a passport's GS1 EPCIS 2.0 supply-chain events.\n- `tracepass_templates` - list and get the DPP category field schemas, each field traced to the EU instrument that mandates it.\n\nEach tool's full action set:\n\n| Tool | Actions |\n|------|---------|\n| `tracepass_products` | `list`, `get`, `create`, `create_batch`, `update`, `archive` |\n| `tracepass_passports` | `list`, `get`, `get_by_serial`, `compliance`, `registry_readiness`, `create`, `suspend`, `suspend_by_serial`, `archive`, `archive_by_serial`, `get_qr`, `get_qr_by_serial` |\n| `tracepass_passport_fields` | `update`, `update_by_serial` |\n| `tracepass_passport_parties` | `set`, `remove` |\n| `tracepass_epcis` | `export`, `export_by_serial`, `capture`, `capture_job`, `query` |\n| `tracepass_templates` | `list`, `get` |\n\nThe **`*_by_serial`** actions address a passport by the customer's own serial\nnumber instead of its TracePass id. A serial is unique only *within a GTIN*, so\nif the same serial exists under two GTINs in your account a serial-only call\nreturns **409 `ambiguous_serial`** — pass the optional `gtin` arg to disambiguate\n(or use the by-id action). The same `gtin` disambiguator applies to every\n`*_by_serial` action.\n\nThe **`tracepass_passports` `compliance`** action returns a three-tier\ncompliance verdict (`compliant` / `compliant_with_warnings` /\n`incomplete`) with regulation-cited findings — missing required fields,\nmissing economic-operator parties, format issues, and per-category\nconditional rules. Read-only; use it to gap-check a passport, fix the\ncited gaps, then re-check.\n\nA **`compliant` verdict means this passport satisfies the rules encoded here**,\nnot *this product may be placed on the market*. The field specifications are\nhand-authored from the regulations, not an official EU artefact, and delegated\nacts are still landing. It is not legal advice.\n\n### A note on writes\n\nSome actions **cost money or are irreversible** — the server's tool\ndescriptions tell the model so:\n\n- **`tracepass_passports` `create`** consumes a billable DPP slot on\n  the account's plan. Over-quota creation incurs a per-passport\n  overage charge; the tool surfaces a 402-style message and only\n  proceeds with `args.confirmOverage: true` after the user agrees.\n- **`tracepass_passports` `archive`** is irreversible — the public QR\n  permanently 404s. Use `suspend` (reversible) when a change might be\n  undone.\n- **`tracepass_epcis` `capture` / `query`** require the paid EPCIS\n  add-on; `export` is included on Starter plans and up.\n\n## Resources\n\nRead-only entity data you can attach as conversation context:\n\n- `tracepass://products` — the product catalogue\n- `tracepass://product/{id}` — one product\n- `tracepass://passport/{id}` — one passport, full field detail\n- `tracepass://passport/{id}/epcis` — a passport's EPCIS 2.0 events\n- `tracepass://passport/{id}/compliance` — a passport's compliance verdict\n- `tracepass://passport/{id}/registry-readiness` — a mechanical pre-submission check modelled on the EU DPP Registry's formal gate: mandatory-field presence, formatting, a resolvable public link, item-level granularity, a well-formed commodity code. Not the substantive compliance verdict, and not a prediction of the real registry's response — its registration API has no published spec. Battery only.\n- `tracepass://templates` — all 13 DPP category field schemas\n- `tracepass://template/{category}` — one category's full field schema\n\n## Prompts\n\nReusable DPP workflows the client surfaces as slash-commands:\n\n- `audit_passport` — review a passport for completeness and\n  compliance readiness\n- `onboard_product` — create a product and its first passport\n- `explain_dpp_requirements` — explain what a category's compliant DPP\n  must contain, and the regulation behind each field\n- `compliance_gap_check` — produce a prioritised, regulation-cited list\n  of what's blocking a passport's compliant publication\n- `review_epcis_events` — summarise a passport's supply-chain trail\n\n## Development\n\n```bash\nnpm install\nnpm run build        # tsc -> dist/\nnpm run typecheck\nnpm test             # vitest\nnpm run lint\nnpm start            # run the hosted HTTP service locally (:8080)\nnpm run start:stdio  # run the stdio server locally\n```\n\nThe hosted service is a plain Node HTTP server (`dist/http.js`),\nstateless — each request carries its own API key and builds a fresh\nMCP session. It is containerised via the `Dockerfile` and deployed to\nHetzner; see `tracepass-environment/docker-mcp.yml`.\n\n## Listed on Glama\n\nThis server is published in the [official MCP Registry](https://registry.modelcontextprotocol.io)\nas `eu.tracepass/tracepass` and listed on [Glama](https://glama.ai/mcp/servers/malinoto/tracepass-mcp-server):\n\n[![TracePass MCP server](https://glama.ai/mcp/servers/malinoto/tracepass-mcp-server/badges/card.svg)](https://glama.ai/mcp/servers/malinoto/tracepass-mcp-server)\n\n## License\n\nMIT\n",
  "bytes": 9444,
  "sha": "b4a204748261acf9b3ad8e9b2b6e29bd8a7e5c550b2362d3fc89a3c05f991f36",
  "repo_slug": "malinoto/tracepass-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_eu_tracepass_tracepass_f7736450/readme"
}