--- title: MCP server description: MCP server — AI assistants (Claude, Cursor, IDE agents) manage products, passports, EPCIS events directly. Hosted endpoint or local npm package. canonical: "https://www.tracepass.eu/docs/mcp" locale: en source: "https://www.tracepass.eu/docs/mcp" --- # MCP server > MCP server — AI assistants (Claude, Cursor, IDE agents) manage products, passports, EPCIS events directly. Hosted endpoint or local npm package. The TracePass MCP server lets an AI assistant drive the TracePass platform directly — list and create products, build and audit Digital Product Passports, set economic-operator parties, and read or capture GS1 EPCIS supply-chain events. It speaks the full Model Context Protocol: tools, resources, and prompts. Connect a hosted `endpoint` or run it locally via `npx` — both authenticate with the same `tp_` API keys as the v1 API. Source on [GitHub](https://github.com/malinoto/tracepass-mcp-server), published as [tracepass-mcp-server](https://www.npmjs.com/package/tracepass-mcp-server) on npm. Listed in the official [MCP Registry](https://registry.modelcontextprotocol.io) as `eu.tracepass/tracepass`. ## What it is MCP is an open protocol that lets an AI assistant call external tools and read external data through a single, standard interface. The TracePass MCP server is a thin, stateless adapter in front of the TracePass v1 API — it has no database of its own; every tool call and resource read goes straight through to the same API your other integrations use, so authentication, plan gating, and rate limits all behave identically. There are two ways to connect it. The **hosted** server runs at `https://ai.tracepass.eu/mcp` over HTTP — nothing to install, always current. The **local** server is the `tracepass-mcp-server` npm package, launched as a subprocess by your MCP client and speaking MCP over stdio. ## Connecting (hosted) Point your MCP client at the hosted endpoint and pass your API key as a `Bearer` token. Mint a key in the dashboard under **Developer → API Keys** — it is the same `tp_` key the v1 API uses. Add this block to your client's MCP configuration: ```json { "mcpServers": { "tracepass": { "url": "https://ai.tracepass.eu/mcp", "headers": { "Authorization": "Bearer tp_YOUR_KEY" } } } } ``` ## Connecting (local / npx) For a local setup, your MCP client launches the npm package as a subprocess and talks to it over stdio. There is nothing to install ahead of time — `npx` fetches `tracepass-mcp-server` on first run. The API key is passed through the `TRACEPASS_API_KEY` environment variable instead of a header: ```json { "mcpServers": { "tracepass": { "command": "npx", "args": ["-y", "tracepass-mcp-server"], "env": { "TRACEPASS_API_KEY": "tp_YOUR_KEY" } } } } ``` ## Tools The TracePass v1 API operations are grouped into six tools. Each takes an `action` plus action-specific `args`, so the assistant picks the tool by domain and the operation by action: | Tool | Actions | | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | tracepass\_products | list, get, create, updateCatalog operations — browse, read, and create or update products. | | tracepass\_passports | list, get, get\_by\_serial, compliance, create, suspend, suspend\_by\_serial, archive, archive\_by\_serial, get\_qrThe passport lifecycle — list and read passports, look one up by serial number, create, suspend, archive, and fetch the QR code. | | tracepass\_passport\_fields | update, update\_by\_serialUpdate individual template fields on a passport. | | tracepass\_passport\_parties | set, removeSet or remove economic-operator parties (manufacturer, importer, recycler, and so on) on a passport. | | tracepass\_epcis | export, export\_by\_serial, capture, capture\_job, queryRead and write GS1 EPCIS 2.0 supply-chain events — export a passport's event history, capture new events, run a capture job, and query the event store. | | tracepass\_templates | list, getRead the regulatory schema for each DPP category — what a compliant passport must contain and the EU regulation behind each required field. Lets the assistant advise on requirements before you create anything. | **Some write actions cost money or are irreversible.** The server's tool descriptions tell the model this, but you should know it too: `tracepass_passports` with action `create` consumes a billable DPP slot on your plan — over-quota creation incurs a per-passport overage charge and only proceeds once the user agrees via `confirmOverage`. Action `archive` is irreversible; use `suspend` when you may need the passport back. The `tracepass_epcis` actions (`capture`, `query`, `export`) are included on every paid plan and metered by events-per-month per the plan table on [/pricing](https://www.tracepass.eu/pricing). ## Resources Resources are read-only entity data the user attaches as conversation context, addressed by a `tracepass://` URI. Two are static resources, the rest are resource templates the client completes with an id: * `tracepass://products` * `tracepass://product/{id}` * `tracepass://passport/{id}` * `tracepass://passport/{id}/epcis` * `tracepass://passport/{id}/compliance` * `tracepass://templates` * `tracepass://template/{category}` ## Prompts Prompts are reusable DPP workflows the MCP client surfaces to the user, typically as slash-commands. Each seeds the conversation so the assistant carries out the task the way TracePass intends — for example, always confirming before it creates a billable passport: * `audit_passport` * `onboard_product` * `review_epcis_events` * `explain_dpp_requirements` * `compliance_gap_check` ## The compliance copilot in action Put together, the templates tool and the prompts turn the assistant into a DPP **compliance copilot** — it knows what each category's regulation requires, not just how to push data. Here is a representative session for a battery manufacturer: ```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 —** Representative example. The assistant's answers come from the live category schema and your own passport data via the tools above — exact wording varies by model and client.