Connect Trackberry to your AI assistant

Goal #

Ask your AI assistant questions about your own shipments and get answers from live Trackberry data: “which containers will cost us demurrage this week?”, “has the ETA on the Rotterdam shipment moved?”, “which shipments are missing a certificate of origin?”.

Trackberry runs a Model Context Protocol (MCP) server for this. MCP is the standard way an assistant such as Claude, ChatGPT or Cursor calls tools in another product. The assistant decides which Trackberry tool to call, reads the answer, and explains it in plain language.

The connection is read-only unless you decide otherwise. The assistant can look at what you can already see in Trackberry. If you allow it when you connect, it can also pre-allocate boxes to your customers, add notes, label and archive shipments and tidy up checks and alerts, and nothing else. See What it can change.

What you need #

• A Trackberry account with access to the organization you want to ask about. Every Trackberry plan includes the MCP server.
• An assistant that supports remote MCP servers: Claude (web, desktop or Claude Code), ChatGPT or Cursor. Custom connectors depend on the assistant’s own plan; the steps below say where.
• The server address, which is the same for everyone:

https://trackberry.com/mcp

There are two ways to sign in. Claude, ChatGPT, Claude Code and Cursor send you to Trackberry to approve the connection, and you choose the organization there. Nothing needs copying: the assistant registers itself with Trackberry the first time it connects. If you would rather not sign in through a browser, or you run the assistant on a server without one, use an API token instead, the same tb_ token described in The Trackberry API.

Connect Claude or Claude Desktop #

Trackberry is listed in Claude’s connector directory. The quickest way in is Trackberry in the Claude directory: add it from there, then approve on the Trackberry page as in steps 3 and 4 below. To add it by hand as a custom connector instead:

1. Open Customize → Connectors and click Add custom connector. The web app and the desktop app work the same way. On the Free plan you can add one custom connector.
   • On a Team or Enterprise plan only an Owner can add it, under Organization settings → Connectors (Add → Custom). Members then find Trackberry under Customize → Connectors and click Connect.
2. Enter the server address, https://trackberry.com/mcp. Leave the OAuth client ID and secret empty. If Claude asks how it should identify itself, choose Register automatically.
3. Your browser opens a Trackberry page headed with the address you will be sent back to: claude.ai wants to read data from one of your organizations. The desktop app shows claude.ai too. Sign in if you are not already. If the address is not claude.ai, deny the request.
4. Choose the organization this connection may read and click Approve. If you belong to several, none is picked for you. The page also asks whether the assistant may make changes. Allow this app to make changes is ticked; untick it to keep the connection read-only.
5. In a conversation, open the + menu, then Connectors, and switch Trackberry on.

Connect ChatGPT #

Trackberry is also listed in ChatGPT’s plugin directory. The quickest way in is Trackberry in the ChatGPT directory: add it from there, then approve on the Trackberry page as in steps 3 and 4 above. To add it by hand in developer mode instead:

1. In ChatGPT on the web, turn on Developer mode under Settings → Security and login. On a Business, Enterprise or Edu workspace an admin may need to allow it first. Which plans offer developer mode is up to OpenAI, so check yours if the switch is missing.
2. Open Plugins, click +, give the connection a name and enter https://trackberry.com/mcp. If it asks how to authenticate, choose OAuth.
3. Approve on the Trackberry page as in steps 3 and 4 above. The address shown is chatgpt.com; deny if it is anything else.
4. In a conversation, choose Developer mode from the + menu and pick Trackberry.

The approval stays in place while you use it. The assistant renews its access in the background; if it goes unused for 30 days, connect again.

Connect Claude Code #

Add the server, then sign in from inside Claude Code:

claude mcp add --transport http trackberry https://trackberry.com/mcp

Start Claude Code, type /mcp, choose trackberry and select Authenticate. Your browser opens the same Trackberry approval page as above, and returns you to Claude Code on your own machine (the address shown is localhost or 127.0.0.1). If the browser cannot reach Claude Code after you approve, paste the full address from the address bar back into Claude Code.

To use a token instead, for example on a server with no browser, create one under Organization settings → API & webhooks (/your-slug/settings/api) and pass it as a header:

claude mcp add --transport http trackberry https://trackberry.com/mcp \
  --header "Authorization: Bearer tb_your_token"

Run claude mcp list to check that it is connected.

Connect Cursor #

With Cursor installed, click Add to Cursor. Cursor asks you to confirm, then adds the server for you.

To add it by hand, put this in ~/.cursor/mcp.json, or in .cursor/mcp.json inside a project:

{
  "mcpServers": {
    "trackberry": {
      "url": "https://trackberry.com/mcp"
    }
  }
}

Cursor opens the Trackberry approval page and returns to localhost on your computer. To use a token instead, create one under Organization settings → API & webhooks, put it in an environment variable and add it as a header, so the token itself stays out of the file:

{
  "mcpServers": {
    "trackberry": {
      "url": "https://trackberry.com/mcp",
      "headers": { "Authorization": "Bearer ${env:TRACKBERRY_TOKEN}" }
    }
  }
}

Claude Desktop with a token #

Claude Desktop is best connected through Customize → Connectors, as above. If you must use a token instead, the community mcp-remote helper can bridge a local configuration entry to the server. Anthropic does not support this set-up, and it needs Node.js. Open Settings → Developer → Edit Config and add:

{
  "mcpServers": {
    "trackberry": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://trackberry.com/mcp", "--header", "Authorization: Bearer ${TRACKBERRY_TOKEN}"],
      "env": { "TRACKBERRY_TOKEN": "tb_your_token" }
    }
  }
}

Quit Claude Desktop completely and start it again after saving the file.

What to ask #

The assistant works best with a specific question about your own shipments. Some that work well:

• Free time. “Which containers are at risk of demurrage this week, and how many days does each one have left?” “Which shipments have no free-time terms set?”
• ETAs. “Which shipments arriving next week have had their ETA pushed back, and by how much?” “What happened to shipment shp_123 since it left Callao?”
• Missing paperwork. “Which shipments in transit have no commercial invoice attached?” “What is the consignee on the bill of lading of shp_123?”
• What you can still sell. “How many size 14 avocados for Rotterdam are not pre-allocated yet, with a QC score of at least 6?” “Which mango sizes are still unsold on the water?”

• What needs attention. “Anything wrong with my shipments today?” “Are there failed checks on the grapes coming into Rotterdam?”

• Pre-allocations and notes, if you allowed changes. “Who are the pallets on MSCU1234567 allocated to?” “Set 40 boxes of the size 14 line on pallet 12 aside for Acme at 12.50 EUR a box.” “Add a note to that shipment: the buyer wants delivery before Friday.”

You can also ask it to combine answers, for example to draft a short status email for a customer from the timeline of one shipment. Check figures that matter before you act on them: the assistant reads the data correctly but can still summarize it badly.

The tools #

The assistant sees thirty-seven tools and picks between them. Twenty-one only read. Sixteen change data, and work only on a connection you allowed to make changes. All but query_stock map to a part of the API and return the same fields, except that search results are short by default, with each shipment’s latest event, so an overview of many shipments stays quick.

Shipments are named shp_ plus a number, documents doc_, packing lines pln_ and pre-allocations pre_, the same ids as in the API (products are prd_, purchase orders por_ and expected containers exs_). The assistant finds them itself; you can also quote one in a question. Answers about a shipment link to it in Trackberry, and you need to be signed in to open the link. If you ask for a tracking link to send to a customer, the assistant gives you the shipment’s public tracking page instead, which needs no login. That link is only available when your organization has public tracking pages on and the shipment is not archived or still awaiting validation; see The Trackberry API.

When you ask where a shipment is or how its journey is going, assistants that support MCP Apps also show a map inside the conversation. It is the same map as the shipment’s page in Trackberry. It shows the sea route, marked as traveled or still to sail, and the ports of loading, transshipment and discharge. It also shows the vessel pointing the way it is heading, and the track it has recorded. Above it are the container or air waybill number, linked to the shipment, its status, the vessel and carrier, and the ETA with how far it has moved. The map appears once per answer, with the tracking timeline, even when the assistant also looks the shipment up.

Which assistants show the map. Claude on the web, in the desktop app and in the iOS app, and ChatGPT, draw it. Claude Code and other assistants without MCP Apps support give the same answer as text. The map shows only positions the carrier has reported, so a shipment that has not moved yet reads “No position yet”.

The map’s background tiles are loaded from OpenStreetMap. Your assistant fetches the tiles for the area on screen from the OpenStreetMap Foundation’s servers. This shows the Foundation roughly which part of the world you are looking at, but no shipment details are sent to it.

What it can change #

Only what you approve. When you connect Claude, ChatGPT or another assistant that signs in through the browser, the Trackberry approval page asks Do you also want it to make changes? The box is ticked. Untick it, and the connection is read-only, as every connection made before November 2026 is.

If you leave Allow this app to make changes ticked, the assistant can:

• pre-allocate boxes of a packing line to a customer, with a tentative price;
• change or remove a pre-allocation;
• add a paragraph to the end of a shipment’s notes;
• put a label on a shipment or take one off;
• run a shipment’s checks again, or ask for fresh tracking (a shipment’s tracking can be refreshed once every 5 minutes);
• accept a failing check, with a reason you give, or withdraw that (admins and owners only);
• snooze, dismiss or bring back an alert;
• archive or unarchive a shipment;
• mark a shipment as received at the warehouse (admins and owners only).

That is the whole list. It cannot edit or delete the notes already there, create labels, edit a shipment’s data, approve or delete a shipment, upload, replace or delete a document, send an email, invite anyone or touch your settings.

What to know before you approve:

• It acts as you. Each change is recorded in the organization’s Activity Log under your name, marked as made through the assistant and naming the app, so a colleague can tell it from one you made by hand.
• Your assistant asks first, if you let it. Trackberry marks these tools as tools that change data, and changing or removing a pre-allocation, and marking a shipment as received, as destructive. Claude and ChatGPT use that to ask for your confirmation before they call one. Keep that confirmation on, and read what it is about to do: the customer, the boxes, the price, the shipment.
• Read-only members stay read-only. If your role is Viewer, the page does not ask: the assistant can read, and cannot make changes for you. If an admin later makes you a member, the same connection can, without connecting again.
• The same limits as the app. A line cannot be allocated beyond its box count, notes are limited to 20,000 characters, only admins and owners can accept a check or mark a shipment as received, and a shipment’s tracking is refreshed at most once every 5 minutes.
• To change your mind, connect the app again. Approve with the box unticked and the app can no longer make changes anywhere: its earlier connections that could are disconnected, on every device, and need connecting again. Approve with it ticked and nothing else changes, so the same assistant on your phone and your computer keeps working on both. A read-only connection never gains the right to make changes on its own.

With an API token instead of the browser sign-in, the token decides: one created as Read and write lets the assistant make these changes, a Read only token does not.

If the assistant says the connection is read-only when you ask for a change, disconnect Trackberry in the assistant, connect it again and leave the box ticked.

Security #

• Changes need your approval. A connection changes nothing unless you approved it with Allow this app to make changes ticked, or gave it a read-and-write token. Even then it can only make the changes listed above: it cannot edit a shipment’s data, send an email or delete a document. Connected apps shows which of your connections can make changes.
• Documents and notes can carry instructions. An assistant reads text that other people wrote: a supplier’s document, a colleague’s note. Such text can try to tell the assistant what to do. If you allow changes, keep your assistant’s confirmation prompts on, so a change never happens without you seeing it.
• One organization per connection. A token or an approval belongs to you and to one organization, and every answer comes from that organization only. To ask about another one, connect again and choose it. The list_organizations tool tells the assistant which organization it is reading.
• Only what you can see. A connection reads what you can read in Trackberry. If you leave the organization, or your membership is removed, it stops working immediately.
• Revoke at any time. Click Revoke next to a token under Organization settings → API & webhooks (API for members), or click Disconnect next to the app under Connected apps on the same page, and the connection stops on its next request. Admins see and can disconnect every member’s apps. Approvals and disconnections are recorded in the organization’s Activity Log.
• Check where you are sent back to. Any app can call itself “Claude”. The approval page leads with the address it returns you to, which is the part that cannot be faked, and warns you in red when it does not recognize that address. Deny if it is not the assistant you started from.
• Treat a token like a password. Anyone who holds it can read your organization’s shipments through any assistant, and make the changes listed above if it is a read-and-write token. Keep it out of shared config files and repositories.
• Your assistant sees the answers. What a tool returns is sent to the assistant’s provider as part of your conversation, under that provider’s own terms. Connect only the organizations whose data you are happy to discuss with that assistant.

Limits and errors #

Each token or connection can make 600 requests every 5 minutes, and the server shares the limits described in The Trackberry API. The assistant is told when a tool call fails and usually tries again or asks you for what is missing, for example a shipment id that does not exist in your organization.

Tool results are always in the latest shape. Unlike the API, they are not pinned to a version, and new fields can appear at any time. The assistant reads them by meaning, so that is rarely visible, but do not build a script on top of the MCP server. Use the API for that.

Troubleshooting #

If you are stuck, write to [email protected] with the assistant you use and the error it shows.