---
title: "MCP Server"
description: "Connect Claude or any MCP client to the epc.is EPCIS 2.0 repository. Your agent queries and traces supply chain events, resolves GS1 Digital Links and checks identifiers, with your own sign-in and read-only."
canonical_url: "https://openepcis.io/docs/mcp-server"
last_updated: "2026-11-19T07:40:21.527Z"
---

`https://mcp.epc.is/mcp` connects Claude and any other MCP client to the
[epc.is](https://epc.is) EPCIS 2.0 repository. Your agent signs in with your
epc.is account and reads exactly what that account may read. It traces a
product, a lot or a container through every step, explains events in plain
language and resolves GS1 Digital Links to their master data and linksets.
Every answer names the eventIDs it rests on, so you can check it.

<mcp-connect client-id="epcis-mcp" name="epc.is Repository" url="https://mcp.epc.is/mcp">



</mcp-connect>

## What you need

- A free [epc.is account](https://epc.is). Every account may use the MCP server.
- Claude (Pro, Max, Team or Enterprise for custom connectors), Claude Code, or
any MCP client that speaks Streamable HTTP and OAuth 2.1 with PKCE.

## Connect

### Claude and Claude Desktop

1. Click **Add epc.is Repository to Claude** above, or open Settings,
Connectors, *Add custom connector*.
2. Name `epc.is Repository`, URL `https://mcp.epc.is/mcp`.
3. Under *Advanced settings*, enter the OAuth client ID `epcis-mcp`. Leave
the client secret empty.
4. Connect. The epc.is sign-in opens. Afterwards the tools appear in the
connector menu of every chat.

### Claude Code

```bash
claude mcp add --transport http epcis https://mcp.epc.is/mcp --client-id epcis-mcp --callback-port 8976
```

Run `/mcp` in a session to sign in through the browser. Claude Code keeps the
token in the system keychain and refreshes it on its own.

### Other MCP clients

The server follows the MCP authorization spec. Without a token it answers
`401` with `WWW-Authenticate: Bearer resource_metadata=...` (RFC 9728), which
names the authorization server `https://auth.epc.is/realms/platform`. Use the
public client `epcis-mcp` with PKCE (S256) and the scopes `openid` and
`offline_access`. Redirects are registered for Claude.ai and for
`http://localhost:8976/callback`.

## Tools

Every tool is read-only and carries `readOnlyHint`. The repository tools call
the EPCIS REST API with your own token, so tenant isolation applies exactly as
for any other client.

<table>
<thead>
  <tr>
    <th>
      Tool
    </th>
    
    <th>
      What it does
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        trace
      </code>
    </td>
    
    <td>
      Backward: what a serial, lot or SSCC was made from and packed in. Forward: what was made from it and where it went. For a returnable or individual asset (GRAI, GIAI) what it carries now and where it was last seen
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        query_events
      </code>
    </td>
    
    <td>
      EPCIS Query Language: event type, bizStep, disposition, identifier, read point, business location, time window and any further parameter, one page at a time
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        get_event
      </code>
    </td>
    
    <td>
      One event by its eventID, as the repository holds it
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        masterdata
      </code>
    </td>
    
    <td>
      What the GS1 Digital Link resolver knows about a product, place or party
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        links
      </code>
    </td>
    
    <td>
      The full linkset of a GS1 Digital Link: passport, master data, EPCIS events, instructions
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        validateIdentifier
      </code>
    </td>
    
    <td>
      A GS1 identifier checked, check digit included
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        urnToDigitalLink
      </code>
      
      , <code>
        digitalLinkToUrn
      </code>
    </td>
    
    <td>
      EPC URN and GS1 Digital Link converted both ways
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        listCbvTerms
      </code>
      
      , <code>
        findCbvTerms
      </code>
      
      , <code>
        describeCbvTerm
      </code>
      
      , <code>
        validateCbvTerm
      </code>
    </td>
    
    <td>
      The Core Business Vocabulary with its definitions
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        validateEpcisDocument
      </code>
      
      , <code>
        checkEpcisConformance
      </code>
      
      , <code>
        listDocumentIdentifiers
      </code>
    </td>
    
    <td>
      An EPCIS 2.0 document checked against schema and rules
    </td>
  </tr>
</tbody>
</table>

## Prompts

Clients that show MCP prompts offer three starting points:

<table>
<thead>
  <tr>
    <th>
      Prompt
    </th>
    
    <th>
      Asks for
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        trace_product
      </code>
    </td>
    
    <td>
      The history of a serial, lot or container, backward and forward, with every eventID
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        explain_event
      </code>
    </td>
    
    <td>
      One event explained along what, when, where, why and how
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        audit_lot
      </code>
    </td>
    
    <td>
      Origin, transformations, custody and gaps of a lot, optionally against EUDR, a Digital Product Passport or FSMA 204
    </td>
  </tr>
</tbody>
</table>

## Try it

- *Which events did my repository receive in the last hour?*
- *Trace this lot backward and tell me where its raw materials came from.*
- *Show me the links of https://id.epc.is/01/09523001010089.*
- *Convert urn:epc:id:sgtin:0614141.107346.2017 to a GS1 Digital Link and check it.*

Master data and linksets of the [OpenEPCIS Factory](https://mc-factory.epc.is)
products are public, so `masterdata` and `links` answer for them from any
account. Events stay with the tenant that captured them.

## Privacy and security

- **Your rights, nothing more.** The server passes your token through to
`api.epc.is` unchanged. It holds no service account and adds no rights.
- **Read-only by construction.** The server only sends GET requests. It cannot
capture, change or delete events.
- **Stateless.** Nothing is stored on the MCP server. Answers go to your client
and nowhere else.

## Troubleshooting

<table>
<thead>
  <tr>
    <th>
      Symptom
    </th>
    
    <th>
      Cause
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        401
      </code>
      
       after signing in
    </td>
    
    <td>
      The token was issued to another client than <code>
        epcis-mcp
      </code>
      
      , so it lacks the audience <code>
        https://mcp.epc.is/mcp
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        403
      </code>
    </td>
    
    <td>
      The account lacks the role <code>
        mcp
      </code>
      
      . Sign in again; write to <a href="mailto:info@benelog.com">
        info@benelog.com
      </a>
      
       if it persists
    </td>
  </tr>
  
  <tr>
    <td>
      Tools answer with no events
    </td>
    
    <td>
      Your account sees no events yet; the MCP server adds no rights to what api.epc.is shows you
    </td>
  </tr>
  
  <tr>
    <td>
      Claude Code asks to sign in again
    </td>
    
    <td>
      Sign in with <code>
        /mcp
      </code>
      
      ; the <code>
        offline_access
      </code>
      
       scope keeps the session alive
    </td>
  </tr>
</tbody>
</table>
