Terminal49 MCP Server

Use the Terminal49 MCP server to let Claude, ChatGPT, Cursor, Microsoft Copilot, or any MCP client answer questions with live container and shipment data—without writing custom glue code.

TL;DR – get started in 5 minutes

Pick your MCP client

Follow the setup guide for your tool:

Claude (claude.ai, Claude Desktop — available in the Claude Directory)
Claude Code
ChatGPT
Cursor
Microsoft Copilot (Copilot Studio)
VS Code (GitHub Copilot)
Agent plugins (Claude Code, Cursor, Codex, GitHub Copilot CLI)
Other MCP clients

Add the connector URL

For Claude, add Terminal49 from the Claude Directory. For other clients, point the client at https://mcp.terminal49.com. No API key needed.

The server supports OAuth 2.1: your client opens a browser window, you sign in with your Terminal49 credentials and approve access. That’s it.

Ask a question

“Using the Terminal49 MCP server, search for container CAIU1234567 and summarize its status.”

Explore tools

“List the tools available in the Terminal49 MCP server and what they’re for.”

Need test container numbers? See Test Numbers for containers you can use during development.

For the full walkthrough (including local stdio dev, deployment, and SDK examples), see MCP Server Quickstart.

Transports

Transport	Endpoint	Best For
HTTP (streamable)	`POST https://mcp.terminal49.com`	Serverless, short-lived requests

Authentication:

OAuth 2.1 (recommended) – no API key needed. Add the connector URL, sign in with your Terminal49 credentials in the browser window your client opens, and approve access. Clients discover the authorization server (https://auth.terminal49.com) automatically and use authorization code with PKCE and Dynamic Client Registration.
API key (for clients without OAuth support) – create a key in the developer portal and pass Authorization: Token YOUR_API_KEY. Use the Token scheme for API keys; the Bearer scheme is used for OAuth access tokens, which OAuth clients obtain automatically.
The local stdio server reads the T49_API_TOKEN environment variable instead.

Connector URL: https://mcp.terminal49.com. It is the canonical OAuth resource identifier, so OAuth clients (ChatGPT, Claude connectors) bind to the correct token audience.

Setup guides

Claude

Add Terminal49 from the Claude Directory

Claude Code

One claude mcp add command from your terminal

ChatGPT

Install from the ChatGPT Plugins Directory

Cursor

mcp.json or Cursor Settings → MCP

Microsoft Copilot

Copilot Studio agent tools

VS Code

GitHub Copilot agent mode

Agent plugins

Terminal49 plugin for Claude Code, Cursor, Codex, and Copilot CLI

Other MCP clients

Generic OAuth or API-key configuration

Any MCP client

Use the same hosted Streamable HTTP endpoint in any MCP-compatible client. With an OAuth-capable client, no credentials are needed — just the URL:

{
  "url": "https://mcp.terminal49.com"
}

If your client can’t run a browser OAuth flow, pass an API key instead:

{
  "url": "https://mcp.terminal49.com",
  "headers": {
    "Authorization": "Token YOUR_API_KEY"
  }
}

See Other MCP clients for details on OAuth discovery and verification. The same rate limits apply to MCP endpoints as the REST API.

Monitoring

Self-hosted deployments can enable Sentry MCP Monitoring by setting SENTRY_DSN. This captures MCP tool calls, resource reads, prompt usage, performance spans, and errors in Sentry.

Input and output recording is disabled by default. Leave SENTRY_MCP_RECORD_INPUTS=false and SENTRY_MCP_RECORD_OUTPUTS=false unless your Sentry project is approved to store shipment identifiers, references, and customer data.

Tools reference

Every tool is read-only except track_container, which creates a tracking request. If a container for the number is already in your account, track_container returns it instead of creating a new request; otherwise it creates a tracking request, so repeated calls before a container links can create additional requests.

`search_container`

Find containers by container number, BL, booking, or your own reference. This is the fastest way to locate containers. Parameters

query (string, required) – container number, BL, booking, or reference

Example MCP request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_container",
    "arguments": {
      "query": "CAIU1234567"
    }
  }
}

Example response

{
  "containers": [
    {
      "id": "abc-123-uuid",
      "containerNumber": "CAIU1234567",
      "status": "in_transit",
      "shippingLine": "Maersk",
      "podTerminal": "APM Terminals",
      "destination": "Los Angeles"
    }
  ],
  "shipments": [],
  "totalResults": 1
}

Good for

“Find this container and tell me where it is”
“Show all containers with reference PO-12345”

REST equivalent: GET /containers with filters

`track_container`

Start tracking a new container. Creates a tracking request and returns container details. Parameters

number (string, required) – container number, BL, or booking number
numberType (string, optional) – override inference (container, bill_of_lading, booking_number)
scac (string, optional) – shipping line code, e.g., MAEU for Maersk
refNumbers (string[], optional) – your reference numbers

Example MCP request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "track_container",
    "arguments": {
      "number": "CAIU1234567",
      "scac": "MAEU"
    }
  }
}

Good for

“Track container CAIU1234567 with Maersk”
“Start tracking this new shipment”

REST equivalent: POST /tracking_requests

`get_container`

Get detailed container information with flexible data loading. Choose what to include based on your question. Parameters

id (uuid, required) – Terminal49 container UUID
include (string[], optional) – what to load:
- shipment – routing, BOL, line, ref numbers (lightweight)
- pod_terminal – terminal name, location (lightweight)
- transport_events – adds events.count, events.rail_events_count, and events.latest_event; use get_container_transport_events for the full timeline
- custom_fields – account-defined fields such as PO number or project manager (lightweight; needs a signed-in user, not an API key)

The response may also include _metadata with factual details such as includes_loaded.

Example MCP request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_container",
    "arguments": {
      "id": "abc-123-uuid",
      "include": ["shipment", "pod_terminal"]
    }
  }
}

Example response (mapped)

{
  "id": "abc-123-uuid",
  "number": "CAIU1234567",
  "status": "available_for_pickup",
  "equipment": {
    "type": "40HC",
    "length": "40",
    "height": "high_cube"
  },
  "location": {
    "currentLocation": "APM Terminals",
    "availableForPickup": true,
    "podArrivedAt": "2025-01-15T08:30:00Z",
    "podDischargedAt": "2025-01-16T14:20:00Z"
  },
  "demurrage": {
    "pickupLfd": "2025-01-22",
    "holds": [],
    "fees": []
  },
  "shipment": {
    "id": "shipment-uuid",
    "billOfLading": "MAEU123456789",
    "shippingLineScac": "MAEU"
  }
}

Good for

“What’s the status of this container?”
“Is it available for pickup? Any holds?”
“When does demurrage start?”

REST equivalent: GET /containers/

`get_container_transport_events`

Get the full event timeline for a container’s journey. Parameters

id (uuid, required) – Terminal49 container UUID

Example response

{
  "totalEvents": 47,
  "eventCategories": {
    "vesselEvents": 8,
    "railEvents": 12,
    "terminalEvents": 18
  },
  "milestones": {
    "vesselLoadedAt": "2024-12-08T10:30:00Z",
    "vesselDepartedAt": "2024-12-09T14:00:00Z",
    "vesselArrivedAt": "2024-12-22T08:30:00Z",
    "dischargedAt": "2024-12-23T11:15:00Z"
  },
  "timeline": [
    {
      "event": "container.transport.vessel_loaded",
      "timestamp": "2024-12-08T10:30:00Z",
      "location": { "name": "Shanghai", "locode": "CNSHA" }
    }
  ]
}

Good for

“Show me the journey timeline”
“What happened to this container?”
“How long was the rail portion?”

REST equivalent: GET /containers//transport_events

`get_shipment_details`

Get shipment-level information including routing, BOL, and all containers. Parameters

id (uuid, required) – Terminal49 shipment UUID
include_containers (boolean, optional) – include container list (default: true)
include_custom_fields (boolean, optional) – include account-defined custom fields such as PO number or project manager (default: false; needs a signed-in user, not an API key)

Good for

“Tell me about this shipment”
“What containers are on this BL?”
“Show me the routing”

REST equivalent: GET /shipments/

`get_supported_shipping_lines`

List carriers supported by Terminal49 with their SCAC codes. Parameters

search (string, optional) – filter by name or SCAC

Good for

“What carriers do you support?”
“What’s the SCAC code for CMA CGM?”

REST equivalent: GET /shipping_lines

`get_container_route`

Get detailed multi-leg routing with vessel itinerary.

This is a paid feature. If not enabled for your account, use get_container_transport_events for historical movement data instead.See Entitlements and Paid Features for the related Routing Data entitlement.

Parameters

id (uuid, required) – Terminal49 container UUID

Good for

“What’s the routing for this container?”
“Which transshipment ports?”
“What vessel is it on?”

REST equivalent: GET /containers/ (route data is included with the container)

`list_shipments`

Return one page of shipments with verified API filters. Common inputs include exact shipment number, tracking_stopped, actively_tracked, voyage_status, pod_code, pol_code, pod_arrival, created_at, and tags. Use the typed advanced_filters object for the full shipment filter catalog. Use sort for server ordering, include_containers for container relationships, and page and page_size for pagination. Container relationships default to excluded. Pages default to 25 rows and cannot exceed 25. Parameters

number (string or string[], optional) - exact shipment number. Arrays match any supplied number.
tracking_stopped (boolean, optional) - shipping-line tracking stopped state.
actively_tracked (boolean, optional) - active tracking state.
voyage_status (string, optional) - arrived or on_ship.
pod_code (string or string[], optional) - Port of Discharge UN/LOCODE.
pol_code (string or string[], optional) - Port of Lading UN/LOCODE.
pod_arrival (string or string[], optional) - arrival date expressions or bounds.
created_at (string or string[], optional) - creation timestamps with a timezone offset.
tags (string or string[], optional) - account shipment tags.
advanced_filters (object, optional) - complete typed shipment filter catalog.
sort (string, optional) - supported server sort token or tokens.
include_containers (boolean, optional) - include related containers. Default false.
include_stopped_tracking (boolean, optional) - include records whose tracking stopped. Default false: like the dashboard, only actively tracked records are returned unless actively_tracked is set. Set true for history over a past period.
page (number, optional) - page number, starting at 1.
page_size (number, optional) - page size. Default 25, maximum 25.

Good for

“Show actively tracked shipments arriving at Los Angeles this week.”
“Find shipments by an exact Bill of Lading number.”

Filter usage, values, and pagination explains the inputs and result metadata. REST equivalent: GET /shipments

`list_containers`

Return one page of containers with verified API filters. Common inputs include number, current_status, pod_code, pol_code, shipping_line_scac, has_holds, has_fees, requires_attention, actively_tracked, arrival, pickup_lfd, and tags. Use the typed advanced_filters object for the full container filter catalog. Use sort for server ordering and include to add shipment, pod_terminal, or both. Pages default to 25 rows and cannot exceed 25. Parameters

number (string or string[], optional) - exact container number. Comma-separated numbers match any; arrays require all.
current_status (string or string[], optional) - container status from the schema’s finite vocabulary.
pod_code (string or string[], optional) - Port of Discharge UN/LOCODE.
pol_code (string or string[], optional) - Port of Lading UN/LOCODE.
shipping_line_scac (string or string[], optional) - carrier Standard Carrier Alpha Code.
has_holds (boolean, optional) - reported terminal hold state.
has_fees (boolean, optional) - reported terminal fees.
requires_attention (boolean, optional) - attention selection. False is not the exact complement of true.
actively_tracked (boolean, optional) - related shipment tracking state.
arrival (string or string[], optional) - arrival date expressions or bounds.
pickup_lfd (string or string[], optional) - pickup Last Free Day date expressions or bounds.
tags (string or string[], optional) - related shipment tags.
advanced_filters (object, optional) - complete typed container filter catalog.
sort (string, optional) - supported server sort token or tokens.
include (string[], optional) - shipment, pod_terminal, or both.
include_stopped_tracking (boolean, optional) - include records whose tracking stopped. Default false: like the dashboard, only actively tracked records are returned unless actively_tracked is set. Set true for history over a past period.
view (string, optional) - compact (default) returns number, status, availability, POD terminal, key dates, LFD, holds, fees and the shipment’s BL, carrier and POD ETA; full returns every attribute.
page (number, optional) - page number, starting at 1.
page_size (number, optional) - page size. Default 25, maximum 25.

Good for

“Show available containers at Los Angeles with reported terminal holds.”
“List actively tracked containers approaching their pickup Last Free Day.”

Filter usage, values, and pagination explains the inputs and result metadata. REST equivalent: GET /containers

`summarize_containers`

Count containers grouped by one dimension, using the same filters as list_containers. Use it for “how many” and “break down by” questions; use list_containers for “which ones”. Like the dashboard, only actively tracked containers are counted unless include_stopped_tracking is true. Parameters

The filters accepted by list_containers (including advanced_filters and include_stopped_tracking).
group_by (string, required) - pod_terminal, current_status, shipping_line, port_of_discharge, hold_type, pickup_lfd_date or pod_arrival_date.

Counts come from GET /v2/containers/summary in one request. hold_type counts each active hold, so a container with two holds counts twice; dates are UTC calendar days. Groups are ordered by count and capped at 200; truncated is true when there are more. Good for

“How many containers are at risk at each terminal?”
“Break down containers on hold by hold type.”

`list_parties`

Find the companies on the account’s shipments (customers, shippers, consignees, customs brokers, freight forwarders, dray carriers) by name and return their IDs. Pass an ID to list_containers or summarize_containers through advanced_filters.parties, keyed by role, such as { "customer": "<id>" }. Parameters

search (string, optional) - company name or part of one; case and punctuation are ignored.
limit (number, optional) - most parties to return. Default 25, maximum 50.

Good for

“How many containers does Acme have at the terminal?” (find Acme, then filter by customer)
“Which containers is Ray Drayage picking up?” (find the carrier, then filter by pickup_dray_carrier)

`list_tracking_requests`

List tracking requests with optional filters and pagination. Parameters

request_number (string, optional) – tracking request identifier
status (string, optional) – created, pending, succeeded, or failed
scac (string, optional) – four-letter shipping line SCAC
page (number, optional) – page number, starting at 1
page_size (number, optional) – results per page (default: 25; maximum: 25)

Good for

“Show failed tracking requests”
“List latest tracking activity”

REST equivalent: GET /tracking_requests

Prompts reference

Prompts are pre-built workflows that guide the AI through multi-step analysis.

`track-shipment`

Quick container tracking with optional carrier specification. Arguments

container_number (string, required) – e.g., CAIU1234567
carrier (string, optional) – SCAC code, e.g., MAEU

Try this in Claude:

“Using Terminal49, track container CAIU1234567 and show me its current status, location, and ETA.”

`check-demurrage`

Analyze demurrage/detention risk for a container. Arguments

container_id (uuid, required) – from search_container or get_container

Try this in Claude:

“Using Terminal49, check demurrage risk for container CAIU1234567 and explain which fees apply and when.”

`analyze-delays`

Identify delays and root causes in a container’s journey. Arguments

container_id (uuid, required) – Container UUID

Try this in Claude:

“Using Terminal49, analyze delays for container CAIU1234567 and tell me what caused them.”

Resources reference

Resources provide static or dynamic data that AI clients can read.

Resource URI	Description
`terminal49://container/{id}`	Container data in markdown format
`terminal49://docs/milestone-glossary`	Event/milestone reference documentation

Example resources/read request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "resources/read",
  "params": {
    "uri": "terminal49://docs/milestone-glossary"
  }
}

Not yet supported

These Terminal49 API capabilities are available via the SDK but not yet exposed as MCP tools:

API	Description	Workaround
`update_shipment`	Update shipment ref numbers/tags	Use REST API
`stop_tracking`	Stop tracking a shipment	Use REST API
`resume_tracking`	Resume tracking a shipment	Use REST API
`raw_events`	Get raw EDI event data	Use REST API
`refresh_container`	Force refresh container data	Use REST API
Webhooks	Real-time event notifications	Configure via the webhooks guide

Shipment/container list operations are available via MCP. Update/stop/resume tracking operations still require REST API or direct SDK usage.

MCP Server Quickstart – Full setup, local dev, deployment
Rate Limiting – Same limits apply to MCP
Test Numbers – Containers for testing
Webhooks – Real-time updates (use with MCP for best results)

​TL;DR – get started in 5 minutes

​Transports

​Setup guides

Claude

Claude Code

ChatGPT

Cursor

Microsoft Copilot

VS Code

Agent plugins

Other MCP clients

​Any MCP client

​Monitoring

​Tools reference

​search_container

​track_container

​get_container

​get_container_transport_events

​get_shipment_details

​get_supported_shipping_lines

​get_container_route

​list_shipments

​list_containers

​summarize_containers

​list_parties

​list_tracking_requests

​Prompts reference

​track-shipment

​check-demurrage

​analyze-delays

​Resources reference

​Not yet supported

​Related guides

TL;DR – get started in 5 minutes

Transports

Setup guides

Any MCP client

Monitoring

Tools reference

`search_container`

`track_container`

`get_container`

`get_container_transport_events`

`get_shipment_details`

`get_supported_shipping_lines`

`get_container_route`

`list_shipments`

`list_containers`

`summarize_containers`

`list_parties`

`list_tracking_requests`

Prompts reference

`track-shipment`

`check-demurrage`

`analyze-delays`

Resources reference

Not yet supported

Related guides