Tessera — EPCIS 2.0 MCP Server

Tessera brings AI-native access to EPCIS 2.0 supply chain data. It is an open-source Model Context Protocol server that connects LLM-powered applications to a standards-compliant EPCIS repository, enabling natural-language capture, query, tracing, validation, and analytics across real supply chain events.

Contributed by NIRA, Version 1.0.0 · Apache 2.0 licensed

---

What Tessera Does

Tessera turns EPCIS 2.0 supply chain event data into an AI-ready traceability layer.

Modern supply chains generate EPCIS events whenever products are commissioned, packed, shipped, received, inspected, transformed, aggregated, or observed. These events are essential for product visibility, custody tracking, compliance, and recall analysis. However, working with EPCIS data typically requires specialized knowledge of EPCIS APIs, event structures, master data, and query patterns.

Tessera bridges that gap by exposing EPCIS repository operations as Model Context Protocol tools. Instead of building custom integrations for every AI application, developers can connect an LLM-powered agent to Tessera and let the agent interact with EPCIS data through structured tool calls.

Tessera enables AI applications to:

• Capture EPCIS events and master data into a standards-compliant repository.
• Query supply chain events by EPC, location, business step, disposition, action, event ID, or time window.
• Determine an item’s current location, current status, first-seen event, last-seen event, and full event timeline.
• Trace products forward and backward through the supply chain.
• Analyze custody chains, location history, recall scope, and operational throughput.
• Validate EPCIS event structure, EPC identifiers, business step URIs, and required data elements.
• Support repository administration tasks such as indexing, duplicate detection, encoding repair, and collection diagnostics.

This allows users to ask natural-language questions like “Where is this product now?”, “Trace this item backward,” or “Which products moved through this facility last week?” while Tessera handles the translation into EPCIS operations.

Under the hood, Tessera wraps the OLIOT EPCIS 2.0 implementation and provides a growing set of MCP tools across capture, query, traceability, analytics, validation, master data, and administration workflows.

Throughout this documentation, Claude Code is used as the example IDE to configure and use Tessera MCP Server. Tessera can be easily configured to other IDEs such as OpenAI Codex, cursor, Windsurf, etc.

---

Directory Structure

tessera-epcis/
├── docker-compose.yml              # starts the full stack (OLIOT + MongoDB + Tessera)
├── docker-compose.override.yml     # local dev overrides
├── wrapper/                        # Tessera MCP server (Python)
│   ├── Dockerfile
│   ├── pyproject.toml
│   ├── scripts/
│   │   └── run_stdio.sh            # launch script for Claude Desktop (stdio mode)
│   └── src/tessera/
│       ├── main.py                 # server entry point
│       ├── config.py               # settings
│       ├── lifecycle.py            # startup health checks
│       ├── normalizer.py           # response formatting
│       ├── request_mapper.py       # translates inputs to OLIOT format
│       ├── schemas/                # input/output schemas
│       └── tools/
│           └── phase1.py           # Phase 1 tools (live)
├── oliot/                          # OLIOT EPCIS backend config
├── tests/
│   └── test_phase1_e2e.py          # end-to-end test suite
├── docs/                           # additional documentation
├── CHANGELOG.md
└── README.md

---

Tools by Functional Groups

Functional Group 1 — Core Capture & Query (Live — 6 tools)

Health checks, event capture, and foundational queries.

ping_mongo · epcis_capture_masterdata · epcis_capture_events · epcis_query_events · epcis_query_by_epc · trace_forward

Functional Group 2 — Query Depth (Live — 9 tools)

Targeted lookups by EPC, location, disposition, action, and business step. Includes current-state queries and full event timelines.

epcis_query_latest_by_epc · epcis_get_current_location · epcis_get_current_status · epcis_query_by_bizstep · epcis_query_by_location · epcis_query_by_disposition · epcis_query_by_action · epcis_query_event_by_id · epcis_get_epc_timeline

Functional Group 3 — Analytics & Traceability (Live — 11 tools)

Backward tracing, recall scope, custody chains, location history, and throughput analytics across time windows.

trace_backward · epcis_trace_recall_scope · epcis_get_epc_first_seen · epcis_get_epc_last_seen · epcis_get_custody_chain · epcis_get_location_history · check_required_kdes · throughput_by_location · throughput_by_location_window · throughput_by_bizstep · throughput_by_bizstep_window

Functional Group 4 — Masterdata & Validation (Live — 7 tools)

Targeted masterdata registration and data quality validation for events, EPCs, and business step URIs.

epcis_capture_business_location · epcis_capture_trading_partner · epcis_capture_product_class · validate_epcis_event · validate_epc_format · validate_bizstep_uri · epcis_compliance_report

Functional Group 5 — Admin & Hygiene (Live — 5 tools)

MongoDB index management, duplicate detection, encoding repair, and collection diagnostics. Destructive operations require confirm_admin: true.

setup_indexes · epcis_dedupe_by_event_id · epcis_fix_encoding · mongo_collection_stats · mongo_list_indexes

---

Setup from Scratch

Prerequisites

Install the following before you begin:

• Docker Desktop — to run OLIOT EPCIS and MongoDB locally
• uv — to run the Python wrapper
• Claude Desktop — the local Claude app you will connect to

---

Step 1 — Clone the repository

git clone https://github.com/SupplyIQ-client/tessera-epcis.git
cd tessera-epcis


---

### Step 2 — Start the backend (OLIOT EPCIS + MongoDB)

This starts OLIOT and MongoDB in Docker but leaves the wrapper running locally (required for Claude Desktop's stdio transport):

```bash
docker compose up --build -d mongodb oliot-epcis

Wait about 20 seconds for OLIOT to finish starting up. You can check its logs with:

docker compose logs -f oliot-epcis

Once you see it accepting connections, you are ready.

---

Step 3 — Install the wrapper dependencies

cd wrapper
uv sync

This installs the Python dependencies into a local virtual environment.

---

Step 4 — Connect to Claude Desktop

Open your Claude Desktop configuration file:

Open Claude Desktop> Click on your Username icon (bottom right) > Settings (with a gear icon) > Developer > Edit Config (this automatically opens up the config file)

else, you can search in your local :

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Replace the paths below with the actual location where you cloned the repo.

macOS / Linux

{
  "mcpServers": {
    "tessera": {
      "command": "/Users/yourname/tessera-epcis/wrapper/.venv/bin/python",
      "args": ["-m", "tessera.main"],
      "cwd": "/Users/yourname/tessera-epcis/wrapper",
      "env": {
        "MCP_TRANSPORT": "stdio",
        "OLIOT_BASE_URL": "http://localhost:8080",
        "PYTHONPATH": "/Users/yourname/tessera-epcis/wrapper/src"
      }
    }
  }
}

Windows

{
  "mcpServers": {
    "tessera": {
      "command": "C:/Users/yourname/tessera-epcis/wrapper/.venv/Scripts/python.exe",
      "args": ["-m", "tessera.main"],
      "cwd": "C:/Users/yourname/tessera-epcis/wrapper",
      "env": {
        "MCP_TRANSPORT": "stdio",
        "OLIOT_BASE_URL": "http://localhost:8080",
        "PYTHONPATH": "C:/Users/yourname/tessera-epcis/wrapper/src"
      }
    }
  }
}

Platform differences to watch for:

• macOS/Linux venv Python is at .venv/bin/python
• Windows venv Python is at .venv\Scripts\python.exe — using bin/python on Windows causes an ENOENT (file not found) error
• macOS blocks Claude Desktop from executing shell scripts (run_stdio.sh) — use the venv Python directly
• uv run can resolve to the wrong Python environment and expose only Phase 1 tools — use the venv Python directly
• Always use absolute paths for both command and PYTHONPATH

Save the file, then fully quit and relaunch Claude Desktop.

NOTE : If you're on Windows, ensure to quit Claude using Task Manager > (right click) > End task. If you're on Mac, right click on the Claude icon in the dock and select "Quit".

Upon relaunch, you'd be asked permission to access your local files (if this is the first time connecting to MCP server via Claude)

---

Once the MCP server is successfully identified by local Claude Desktop, you can identify the connector

Step 5 — Test the wrapper manually (optional)

If you want to verify the wrapper runs before connecting Claude Desktop:

cd wrapper
./scripts/run_stdio.sh

You should see it start and wait for input. Press Ctrl+C to stop.

---

Step 6 — Verify the connection

In Claude Desktop, open a new conversation and type:

"Check if the Tessera supply chain server is running."

Claude should call ping_mongo and confirm that both OLIOT and MongoDB are reachable. If it does, everything is working.

You can also click on the drop down, to check the tool calls that was run and its results

---

Step 7 — Try it out

Once connected, you can ask Claude things like:

• "Capture a shipping event for product EPC urn:epc:id:sgtin:0614141.107340.2017"
• "Show me all events from the last 30 days"
• "Trace item urn:epc:id:sgtin:0614141.107340.2017 forward through the supply chain"

Claude will use the Tessera tools to read and write data directly against your local OLIOT instance.

---

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before opening a pull request.

Requirements for all contributions:

• State which OLIOT version your change targets (currently tested against OLIOT EPCIS 2.2.0)
• Include or update tests where applicable
• Keep tool descriptions in the MCP tool decorator accurate — Claude uses them to decide which tool to call

Adding new tools:

• Place Phase 2–5 additions in the corresponding wrapper/src/tessera/tools/phaseN.py file
• Add the matching Pydantic schemas to wrapper/src/tessera/schemas/
• Update docs/tools-reference.md with the full argument and response documentation

---

Acknowledgements

Tessera is built on top of OLIOT EPCIS 2.0, the GS1 EPCIS 2.0 reference implementation developed by the Auto-ID Labs Korea at Sejong University, led by Jaewook Byun. OLIOT provides the standards-compliant EPCIS backend that Tessera wraps.

• OLIOT EPCIS repository: github.com/JaewookByun/epcis
• GS1 EPCIS 2.0 standard: ref.gs1.org/standards/epcis
• Model Context Protocol: modelcontextprotocol.io

Tessera is licensed under Apache 2.0. See LICENSE for details.