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. The assistant can look at what you can already see in Trackberry and cannot create, change or delete anything.

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 #

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.
4. Choose the organization this connection may read and click Approve. If you belong to several, none is picked for you.
5. In a conversation, open the + menu, then Connectors, and switch Trackberry on.

Connect ChatGPT #

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 every hour; 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 Settings → API tokens (/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 Settings → API tokens, 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 needs attention. “Anything wrong with my shipments today?” “Are there failed checks on the grapes coming into Rotterdam?”

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 summarise it badly.

The tools #

The assistant sees eight tools and picks between them. Each one maps to a part of the API and returns the same fields.

Shipments are named shp_ plus a number and documents doc_ plus a number, the same ids as in the API. The assistant finds them itself; you can also quote one in a question.

Security #

• Read-only. There are no tools that write. A connection cannot change a shipment, send an email or delete a document.
• 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. Delete a token under Settings → API tokens, 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 audit 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 recognise 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. 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 support@trackberry.com with the assistant you use and the error it shows.