tracepass-mcp-server

TracePass EPCIS 2.0

tracepass_epcis

Export, capture, and query GS1 EPCIS 2.0 supply-chain events for Digital Product Passports; poll async capture jobs and retrieve event data by passport ID or serial.

Instructions

GS1 EPCIS 2.0 supply-chain events. export, capture, capture_job and query are on every plan, Free included. Captured events count against the plan's event allowance (10 a month on Free); over it, capture returns an overage or hard-block message.

Actions (pass via action, with args):

export — args: { id }. Export a passport's events as an EPCIS 2.0 JSON-LD document. Read-only.
export_by_serial — args: { serial, gtin? }. Same as export, addressed by your own serial. A serial is unique only WITHIN a GTIN — if it isn't unique in your account the call returns 409 ambiguous_serial; pass gtin (or use export by id). Read-only.
capture — args: { events }. events is an EPCISDocument, a single event, or an array of events (JSON-LD). Returns a 202 with a captureJobId.
capture_job — args: { jobId }. Poll an async capture job. Read-only.
query — args: { params? }. params is a key/value map of standard EPCIS query parameters (EQ_bizStep, GE_eventTime, MATCH_epc, …). Read-only.

Input Schema

Name	Required	Description	Default
`args`	No	Arguments for the chosen action; required fields depend on `action`.
`action`	Yes	EPCIS 2.0: export a passport's events (export \| export_by_serial), capture new events, poll a capture job, or query events.

Output Schema

Name	Required	Description
`id`	No	The resource's TracePass id, when the response is a single entity.
`page`	No	Current page number (list actions).
`error`	No	Machine-readable error code, when the API rejected the request.
`items`	No	The page of results, when the action is a list.
`limit`	No	Page size (list actions).
`total`	No	Total matching records across all pages (list actions).
`result`	No	Wraps a non-object response body (e.g. a QR code string).
`message`	No	Human-readable error or status detail, when present.
`totalPages`	No	Total number of pages (list actions).

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv1.23.2Oct 31, 2026

removedOutput schema / properties / error / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / error / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / message / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / message / type
```
Added value: +[
+  "string",
+  "null"
+]
```

Changed4 schema fields changedv1.19.1Oct 14, 2026
- addedOutput schema / properties / error / anyOf
```
Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
```
- removedOutput schema / properties / error / type
```
Removed value: -"string"
```
- addedOutput schema / properties / message / anyOf
```
Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
```
- removedOutput schema / properties / message / type
```
Removed value: -"string"
```

Changed7 schema fields changedv1.7.3Aug 7, 2026

addedInput schema / properties / action / description

Added value: +"EPCIS 2.0: export a passport's events (export | export_by_serial), capture new events, poll a capture job, or query events."

changedInput schema / properties / action / enum

Previous value: -[
-  "export",
-  "capture",
-  "capture_job",
-  "query"
-]New value: +[
+  "export",
+  "export_by_serial",
+  "capture",
+  "capture_job",
+  "query"
+]

removedInput schema / properties / args / additionalProperties
```
Removed value: -{}
```

changedInput schema / properties / args / description

Previous value: -"Action-specific arguments — see the description."New value: +"Arguments for the chosen action; required fields depend on `action`."

addedInput schema / properties / args / properties

Added value: +{
+  "events": {
+    "description": "EPCIS 2.0 event payload (an EPCISDocument or event list). Required for capture."
+  },
+  "gtin": {
+    "description": "GTIN disambiguator for export_by_serial when the serial isn't unique (else 409).",
+    "type": "string"
+  },
+  "id": {
+    "description": "Passport id. Required for export.",
+    "type": "string"
+  },
+  "jobId": {
+    "description": "Capture job id to poll. Required for capture_job.",
+    "type": "string"
+  },
+  "params": {
+    "additionalProperties": {
+      "type": "string"
+    },
+    "description": "EPCIS query parameters as key→value strings (query, optional).",
+    "propertyNames": {
+      "type": "string"
+    },
+    "type": "object"
+  },
+  "serial": {
+    "description": "Your serial. Required for export_by_serial.",
+    "type": "string"
+  }
+}

removedInput schema / properties / args / propertyNames
```
Removed value: -{
-  "type": "string"
-}
```

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "error": {
+      "description": "Machine-readable error code, when the API rejected the request.",
+      "type": "string"
+    },
+    "id": {
+      "description": "The resource's TracePass id, when the response is a single entity.",
+      "type": "string"
+    },
+    "items": {
+      "description": "The page of results, when the action is a list.",
+      "items": {},
+      "type": "array"
+    },
+    "limit": {
+      "description": "Page size (list actions).",
+      "type": "number"
+    },
+    "message": {
+      "description": "Human-readable error or status detail, when present.",
+      "type": "string"
+    },
+    "page": {
+      "description": "Current page number (list actions).",
+      "type": "number"
+    },
+    "result": {
+      "description": "Wraps a non-object response body (e.g. a QR code string)."
+    },
+    "total": {
+      "description": "Total matching records across all pages (list actions).",
+      "type": "number"
+    },
+    "totalPages": {
+      "description": "Total number of pages (list actions).",
+      "type": "number"
+    }
+  },
+  "type": "object"
+}

First observedv1.1.4Jun 9, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the top-level annotations (readOnlyHint=false with no per-action nuance) by labeling export, export_by_serial, capture_job and query individually as read-only. It also discloses quota behavior (10/month Free, overage or hard-block on capture), the 202 + captureJobId async pattern, and the 409 ambiguous_serial failure mode — none of which is derivable from annotations or schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the resource, the action list, and the plan/quota caveat, then a scannable per-action bullet block. Nearly every sentence earns its place; the plan-allowance sentence is the only one that leans informational rather than operational.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return shapes need not be described, and the description instead covers what the schema can't: quota enforcement, the async job-poll workflow, and the ambiguity error with its remedy. Nothing an agent needs in order to invoke an action correctly is absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so 3 is the floor, but the description adds real meaning: `events` may be an EPCISDocument, a single event, or an array; `params` is a standard EPCIS query map with concrete examples (EQ_bizStep, GE_eventTime, MATCH_epc); and `serial` uniqueness is scoped WITHIN a GTIN. That last point is the key semantic the schema only hints at.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States the resource precisely (GS1 EPCIS 2.0 supply-chain events) and enumerates five named actions with their argument shapes. No sibling tool covers EPCIS events, so the domain boundary is unambiguous from the name plus first sentence.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Each action carries its required args and a routing hint: export vs export_by_serial is disambiguated, and the 409 ambiguous_serial case explicitly redirects to passing `gtin` or using export by id. What's missing is guidance on when to pick `query` over `export`/`export_by_serial` for retrieving events.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server