Terminal49 MCP Server Quickstart

This guide covers everything you need to connect Claude or Cursor to Terminal49’s container tracking data via MCP.

Just want to get started fast? See MCP Overview for a 5-minute setup.

Prerequisites

Before you begin, make sure you have:

Terminal49 account

A Terminal49 account with API access

API key

An API key from the developer portal

Node.js 24.x

Required if running the MCP server locally

MCP client

Claude Desktop or Cursor IDE

Technical Details:

MCP SDK: @modelcontextprotocol/sdk ^1.29.0
TypeScript SDK: @terminal49/sdk 0.3.0
Sentry MCP Monitoring: @sentry/node ^10.55.0 (optional)
Runtime: Node.js 24.x

Transports

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

Authentication: API key only (OAuth not required for this release). Pass Authorization: Token YOUR_API_KEY. Use the Token scheme for API keys. The Bearer scheme is reserved for WorkOS OAuth access tokens — it currently accepts API keys for backward compatibility, but once OAuth is enabled, Bearer accepts only WorkOS tokens. The hosted endpoint always requires the Authorization header. Only the local stdio server reads the T49_API_TOKEN environment variable instead of a header.

Claude Desktop and Cursor use the HTTP transport. For hosted production usage, connect to https://mcp.terminal49.com — the root origin is the canonical connector URL.

Observability

The MCP server supports optional Sentry MCP Monitoring. Set SENTRY_DSN to capture MCP server connections, tool executions, resource access, prompts, performance spans, and errors in Sentry.

SENTRY_DSN=___PUBLIC_DSN___
SENTRY_TRACES_SAMPLE_RATE=1.0
SENTRY_MCP_RECORD_INPUTS=false
SENTRY_MCP_RECORD_OUTPUTS=false
SENTRY_SEND_DEFAULT_PII=false

SENTRY_MCP_RECORD_INPUTS and SENTRY_MCP_RECORD_OUTPUTS are disabled by default because MCP payloads can include shipment identifiers, references, and customer data. Enable them only if your Sentry project is approved for that data.

Configure your MCP client

Claude Desktop

macOS
Windows
Linux

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Edit %APPDATA%\Claude\claude_desktop_config.json:

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

Edit ~/.config/Claude/claude_desktop_config.json:

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

Cursor IDE

Add to your Cursor settings:

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

Local stdio (development)

For local development without a hosted server:

{
  "mcpServers": {
    "terminal49": {
      "command": "node",
      "args": ["/path/to/API/packages/mcp/dist/index.js"],
      "env": {
        "T49_API_TOKEN": "YOUR_API_KEY"
      }
    }
  }
}

Build the MCP server first: cd packages/mcp && npm install && T49_SDK_SOURCE=published npm run sdk:setup && npm run build

Contributor mode: switch SDK source

Use published SDK by default:

cd packages/mcp
T49_SDK_SOURCE=published npm run sdk:setup

Use local SDK build during development:

cd packages/mcp
T49_SDK_SOURCE=local npm run sdk:setup

Test your setup

Once configured, verify everything works:

Restart your MCP client

Close and reopen Claude Desktop or Cursor to load the new config.

Ask Claude to list tools

“List the tools available in the Terminal49 MCP server.”

Claude should respond with a list of 10 tools including search_container, track_container, and list tools.

Search for a test container

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

If configured correctly, Claude will call search_container and return container details.

Try a multi-step query

“Using Terminal49, find container CAIU1234567, check its demurrage risk, and tell me if I need to pick it up urgently.”

Claude should chain multiple tools together to answer.

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

Troubleshooting

Symptom	Likely Cause	How to Fix
”Cannot connect to MCP server”	Wrong URL or config path	Confirm URL is `https://mcp.terminal49.com` and config file path matches your OS
`401 Unauthorized`	Missing or invalid API key	Create a new API key in the developer portal; ensure the `Authorization: Token YOUR_API_KEY` header is set
`429 Too Many Requests`	Rate limit exceeded	See Rate Limiting; use webhooks instead of polling
Tools list is empty	Config not loaded	Restart Claude/Cursor; check MCP inspector for errors
”Tool not found”	Typo in tool name	Use exact names: `search_container`, `get_container`, etc.
Slow responses	Large data requests	Use `include` parameter to load only what you need

Check MCP server logs

If using the hosted server, check your Terminal49 dashboard for API logs.If running locally:

cd packages/mcp
T49_API_TOKEN=YOUR_API_KEY npm run mcp:stdio 2>&1 | head -20

MCP capabilities

Tools

Tool	Description	Parameters
`search_container`	Find containers by number, BL, booking, or ref	`query: string`
`track_container`	Start tracking a container	`number`, `numberType?`, `scac?`, `refNumbers?`
`get_container`	Get container with optional includes	`id: uuid`, `include?: ['shipment', 'pod_terminal', 'transport_events']`
`get_shipment_details`	Get shipment and containers	`id: uuid`, `include_containers?: boolean`
`get_container_transport_events`	Get event timeline	`id: uuid`
`get_supported_shipping_lines`	List carriers with SCAC codes	`search?: string`
`get_container_route`	Get multi-leg routing (paid feature)	`id: uuid`
`list_shipments`	List shipments with filters + pagination	`status?`, `port?`, `carrier?`, `updated_after?`, `include_containers?`, `page?`, `page_size?`
`list_containers`	List containers with filters + pagination	`status?`, `port?`, `carrier?`, `updated_after?`, `include?`, `page?`, `page_size?`
`list_tracking_requests`	List tracking requests with filters	`filters?`, `status?`, `request_type?`, `page?`, `page_size?`

Prompts

Prompt	Description	Arguments
`track-shipment`	Quick tracking workflow	`container_number`, `carrier?`
`check-demurrage`	Demurrage risk analysis	`container_id`
`analyze-delays`	Journey delay analysis	`container_id`

Resources

URI	Description
`terminal49://container/{id}`	Container data as resource
`terminal49://docs/milestone-glossary`	Event/milestone reference

For detailed examples and response formats, see MCP Overview → Tools Reference.

SDK usage

The TypeScript SDK provides the same capabilities as MCP tools, plus additional APIs not yet exposed via MCP.

npm install @terminal49/sdk

import { Terminal49Client } from '@terminal49/sdk';

const client = new Terminal49Client({
  apiToken: process.env.T49_API_TOKEN!,
  defaultFormat: 'mapped'
});

// Get container with shipment and terminal
const container = await client.containers.get(
  'container-uuid',
  ['shipment', 'pod_terminal']
);

// Search for containers
const results = await client.search('CAIU1234567');

// List shipments with filters (not available via MCP)
const shipments = await client.shipments.list({
  status: 'in_transit',
  carrier: 'MAEU'
});

Response formats

Format	Description
`raw`	JSON:API response with `data`, `attributes`, `relationships`
`mapped`	Simplified, camelCase objects with IDs resolved
`both`	`{ raw, mapped }` for debugging

Raw vs Mapped example

Raw format:

{
  "data": {
    "type": "container",
    "id": "abc-123",
    "attributes": {
      "container_number": "CAIU1234567",
      "available_for_pickup": true
    }
  }
}

Mapped format:

{
  "id": "abc-123",
  "containerNumber": "CAIU1234567",
  "availableForPickup": true
}

Deployment

Vercel (production)

The vercel.json configures the MCP server (excerpt):

{
  "installCommand": "npm ci",
  "buildCommand": "npm run build --workspace @terminal49/sdk && npm run build --workspace @terminal49/mcp",
  "functions": {
    "api/mcp.ts": { "maxDuration": 30 }
  },
  "rewrites": [
    { "source": "/mcp", "destination": "/api/mcp" },
    { "source": "/", "destination": "/api/mcp" }
  ]
}

Environment variables

Variable	Required	Description
`T49_API_TOKEN`	For local stdio	Terminal49 API key. The hosted HTTP endpoint authenticates callers via the `Authorization` header instead
`T49_API_BASE_URL`	No	Override API URL (default: `https://api.terminal49.com/v2`)
`T49_MCP_ALLOWED_HOSTS`	No	Comma-separated host allowlist for request Host validation
`T49_MCP_ALLOWED_ORIGINS`	No	Comma-separated origin allowlist for request Origin validation
`SENTRY_DSN`	No	Enables Sentry MCP Monitoring
`SENTRY_ENVIRONMENT`	No	Sentry environment name; defaults to `NODE_ENV`
`SENTRY_RELEASE`	No	Sentry release identifier; defaults to `VERCEL_GIT_COMMIT_SHA`
`SENTRY_TRACES_SAMPLE_RATE`	No	Trace sampling rate from `0` to `1`; defaults to `1.0`
`SENTRY_MCP_RECORD_INPUTS`	No	Records MCP inputs in Sentry when set to `true`; defaults to `false`
`SENTRY_MCP_RECORD_OUTPUTS`	No	Records MCP outputs in Sentry when set to `true`; defaults to `false`
`SENTRY_SEND_DEFAULT_PII`	No	Enables Sentry default PII behavior; defaults to `false`

Testing locally

# Build the MCP server
cd packages/mcp
npm install
npm run build

# Test tools/list
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | T49_API_TOKEN=YOUR_API_KEY npm run mcp:stdio

# Test search_container
echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"search_container","arguments":{"query":"CAIU1234567"}},"id":2}' | T49_API_TOKEN=YOUR_API_KEY npm run mcp:stdio

# Test the hosted endpoint
curl -X POST https://mcp.terminal49.com \
  -H "Authorization: Token $T49_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

MCP Overview – Quick start and tools reference
Rate Limiting – API limits (same for MCP)
Test Numbers – Containers for testing
Webhooks – Real-time updates
API Data Sources – Data freshness and coverage

​Prerequisites

Terminal49 account

API key

Node.js 24.x

MCP client

​Transports

​Observability

​Configure your MCP client

​Claude Desktop

​Cursor IDE

​Local stdio (development)

​Test your setup

​Troubleshooting

​MCP capabilities

​Tools

​Prompts

​Resources

​SDK usage

​Response formats

​Deployment

​Vercel (production)

​Environment variables

​Testing locally

​Related guides

Prerequisites

Transports

Observability

Configure your MCP client

Claude Desktop

Cursor IDE

Local stdio (development)

Test your setup

Troubleshooting

MCP capabilities

Tools

Prompts

Resources

SDK usage

Response formats

Deployment

Vercel (production)

Environment variables

Testing locally

Related guides