> ## Documentation Index
> Fetch the complete documentation index at: https://terminal49-codex-update-typescript-sdk-cli-current.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Terminal49 MCP Server

> Connect the Terminal49 MCP server to Claude Desktop or Cursor so AI tools can query, search, and answer questions with live shipment tracking data.

# Terminal49 MCP Server

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

## TL;DR – get started in 5 minutes

<Steps>
  <Step title="Get your API token">
    Go to the [Terminal49 dashboard](https://app.terminal49.com/developers/api-keys) → Settings → API Tokens and create a `T49_API_TOKEN`.
  </Step>

  <Step title="Pick your MCP client">
    * **Claude Desktop** (macOS / Windows / Linux)
    * **Cursor IDE**
  </Step>

  <Step title="Paste this config (Claude Desktop)">
    Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "terminal49": {
          "url": "https://mcp.terminal49.com",
          "headers": {
            "Authorization": "Token <T49_API_TOKEN>"
          }
        }
      }
    }
    ```

    <Accordion title="Cursor IDE config">
      ```json theme={null}
      {
        "mcp": {
          "servers": {
            "terminal49": {
              "url": "https://mcp.terminal49.com",
              "headers": {
                "Authorization": "Token <T49_API_TOKEN>"
              }
            }
          }
        }
      }
      ```
    </Accordion>
  </Step>

  <Step title="Ask Claude">
    > "Using the Terminal49 MCP server, track container CAIU1234567 with Maersk."
  </Step>

  <Step title="Explore tools">
    Ask Claude:

    > "List the tools available in the Terminal49 MCP server and what they're for."
  </Step>
</Steps>

<Note>
  Need test container numbers? See [Test Numbers](/api-docs/useful-info/test-numbers) for containers you can use during development.
</Note>

For the full walkthrough (including local stdio dev, deployment, and SDK examples), see [MCP Server Quickstart](/api-docs/in-depth-guides/mcp).

***

## Transports

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

**Authentication**:

* API token only (OAuth not required for this release)
* Header: `Authorization: Token <T49_API_TOKEN>`. Use the `Token` scheme for API keys.
* The `Bearer` scheme is reserved for WorkOS OAuth access tokens. Once OAuth is enabled, `Bearer` accepts only WorkOS tokens, so authenticate API keys with `Token`.
* Or set `T49_API_TOKEN` environment variable when self-hosting

<Tip>
  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.
</Tip>

The same [rate limits](/api-docs/in-depth-guides/rate-limiting) apply to MCP endpoints as the REST API.

***

## Monitoring

Self-hosted deployments can enable [Sentry MCP Monitoring](https://docs.sentry.io/ai/monitoring/mcp/) by setting `SENTRY_DSN`. This captures MCP tool calls, resource reads, prompt usage, performance spans, and errors in Sentry.

<Warning>
  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.
</Warning>

***

## Tools reference

<Note>
  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.
</Note>

### `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

<Accordion title="Example MCP request">
  ```json theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "search_container",
      "arguments": {
        "query": "CAIU1234567"
      }
    }
  }
  ```
</Accordion>

<Accordion title="Example response">
  ```json theme={null}
  {
    "containers": [
      {
        "id": "abc-123-uuid",
        "containerNumber": "CAIU1234567",
        "status": "in_transit",
        "shippingLine": "Maersk",
        "podTerminal": "APM Terminals",
        "destination": "Los Angeles"
      }
    ],
    "shipments": [],
    "totalResults": 1
  }
  ```
</Accordion>

**Good for**

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

**REST equivalent**: [GET /containers](/api-docs/api-reference/containers/list-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

<Accordion title="Example MCP request">
  ```json theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "track_container",
      "arguments": {
        "number": "CAIU1234567",
        "scac": "MAEU"
      }
    }
  }
  ```
</Accordion>

**Good for**

* "Track container CAIU1234567 with Maersk"
* "Start tracking this new shipment"

**REST equivalent**: [POST /tracking\_requests](/api-docs/api-reference/tracking-requests/create-a-tracking-request)

***

### `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` – full event history (heavy, 50-100 events)

<Accordion title="Example MCP request">
  ```json theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_container",
      "arguments": {
        "id": "abc-123-uuid",
        "include": ["shipment", "pod_terminal"]
      }
    }
  }
  ```
</Accordion>

<Accordion title="Example response (mapped)">
  ```json theme={null}
  {
    "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"
    }
  }
  ```
</Accordion>

**Good for**

* "What's the status of this container?"
* "Is it available for pickup? Any holds?"
* "When does demurrage start?"

**REST equivalent**: [GET /containers/{id}](/api-docs/api-reference/containers/get-a-container)

***

### `get_container_transport_events`

Get the full event timeline for a container's journey.

**Parameters**

* `id` *(uuid, required)* – Terminal49 container UUID

<Accordion title="Example response">
  ```json theme={null}
  {
    "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" }
      }
    ]
  }
  ```
</Accordion>

**Good for**

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

**REST equivalent**: [GET /containers/{id}/transport\_events](/api-docs/api-reference/containers/get-a-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)

**Good for**

* "Tell me about this shipment"
* "What containers are on this BL?"
* "Show me the routing"

**REST equivalent**: [GET /shipments/{id}](/api-docs/api-reference/shipments/get-a-shipment)

***

### `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](/api-docs/api-reference/shipping-lines/shipping-lines)

***

### `get_container_route`

Get detailed multi-leg routing with vessel itinerary.

<Warning>
  This is a **paid feature**. If not enabled for your account, use `get_container_transport_events` for historical movement data instead.
</Warning>

**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/{id}](/api-docs/api-reference/containers/get-a-container) (route data is included with the container)

***

### `list_shipments`

List shipments with optional filters and pagination.

**Parameters**

* `status`, `port`, `carrier`, `updated_after` *(string, optional)*
* `include_containers` *(boolean, optional)*
* `page`, `page_size` *(number, optional)*

**Good for**

* "List recent shipments"
* "Show in-transit shipments for MAEU"

**REST equivalent**: [GET /shipments](/api-docs/api-reference/shipments/list-shipments)

***

### `list_containers`

List containers with optional filters and pagination.

**Parameters**

* `status`, `port`, `carrier`, `updated_after` *(string, optional)*
* `include` *(string, optional)* – comma-separated include list
* `page`, `page_size` *(number, optional)*

**Good for**

* "List containers updated in the last 24h"
* "Show containers at a specific POD port"

**REST equivalent**: [GET /containers](/api-docs/api-reference/containers/list-containers)

***

### `list_tracking_requests`

List tracking requests with optional filters and pagination.

**Parameters**

* `filters` *(object, optional)* – raw query filters
* `page`, `page_size` *(number, optional)*

**Good for**

* "Show failed tracking requests"
* "List latest tracking activity"

**REST equivalent**: [GET /tracking\_requests](/api-docs/api-reference/tracking-requests/list-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 |

<Accordion title="Example resources/read request">
  ```json theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "resources/read",
    "params": {
      "uri": "terminal49://docs/milestone-glossary"
    }
  }
  ```
</Accordion>

***

## Not yet supported

These Terminal49 API capabilities are available via the [SDK](/api-docs/in-depth-guides/mcp#sdk-usage) but not yet exposed as MCP tools:

| API                 | Description                      | Workaround                                                                     |
| ------------------- | -------------------------------- | ------------------------------------------------------------------------------ |
| `update_shipment`   | Update shipment ref numbers/tags | Use [REST API](/api-docs/api-reference/shipments/edit-a-shipment)              |
| `stop_tracking`     | Stop tracking a shipment         | Use [REST API](/api-docs/api-reference/shipments/stop-tracking-shipment)       |
| `resume_tracking`   | Resume tracking a shipment       | Use [REST API](/api-docs/api-reference/shipments/resume-tracking-shipment)     |
| `raw_events`        | Get raw EDI event data           | Use [REST API](/api-docs/api-reference/containers/get-a-containers-raw-events) |
| `refresh_container` | Force refresh container data     | Use [REST API](/api-docs/api-reference/containers/refresh-container)           |
| Webhooks            | Real-time event notifications    | Configure via [dashboard](/api-docs/in-depth-guides/webhooks)                  |

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

***

## Related guides

* [MCP Server Quickstart](/api-docs/in-depth-guides/mcp) – Full setup, local dev, deployment
* [Rate Limiting](/api-docs/in-depth-guides/rate-limiting) – Same limits apply to MCP
* [Test Numbers](/api-docs/useful-info/test-numbers) – Containers for testing
* [Webhooks](/api-docs/in-depth-guides/webhooks) – Real-time updates (use with MCP for best results)