Terminal49 MCP Server Quickstart

This guide covers everything you need to connect an MCP client to Terminal49’s container tracking data.

Just want to get started fast? See the per-tool setup guides for Claude, Claude Code, ChatGPT, Cursor, Microsoft Copilot, and VS Code, or the MCP Overview for a 5-minute setup.

Prerequisites

Before you begin, make sure you have:

Terminal49 account

You sign in with your Terminal49 credentials during the OAuth flow — no API key needed

API key (optional)

Only needed for clients without OAuth support or the local stdio server — create one in the developer portal

Node.js 24.x

Required if running the MCP server locally

MCP client

Claude, ChatGPT, Cursor, Microsoft Copilot, VS Code, or any MCP-compatible client

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: OAuth 2.1 (recommended) or API key.

OAuth 2.1 – no API key needed. Add https://mcp.terminal49.com to your client; it discovers the authorization server (https://auth.terminal49.com) via protected resource metadata, registers itself with Dynamic Client Registration, and opens your browser so you can sign in with your Terminal49 credentials. Tokens are stored and refreshed by the client.
API key – for clients that can’t run a browser OAuth flow, 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.

Only the local stdio server reads the T49_API_TOKEN environment variable instead of a header.

For hosted production usage, connect to https://mcp.terminal49.com — the root origin is the canonical connector URL and OAuth resource identifier.

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

OAuth setup (recommended)

Most clients connect with just the server URL and a browser sign-in — no API key. Follow the guide for your tool:

Claude – claude.ai and Claude Desktop
Claude Code – one claude mcp add command
ChatGPT – custom connector with Developer mode
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 GitHub Copilot CLI
Other MCP clients – generic configuration

The manual configurations below use an API key instead. Use them for clients or environments where the browser OAuth flow isn’t practical.

claude.ai and Claude Desktop cannot send a static API-key header — they always authenticate through the OAuth connector flow. Follow the Claude setup guide to connect them. For API-key-based local development in Claude Desktop, use the local stdio server below instead.

Cursor IDE (manual, API key)

Add to .cursor/mcp.json in your project (or ~/.cursor/mcp.json for all projects):

{
  "mcpServers": {
    "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`	Expired OAuth session, or missing/invalid API key	Disconnect and reconnect the connector to re-run the OAuth sign-in. If using an API key, create a new one in the developer portal and 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" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

MCP Overview – Quick start and tools reference
Setup guides: Claude, Claude Code, ChatGPT, Cursor, Microsoft Copilot, VS Code, Agent plugins, Other clients
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 (optional)

Node.js 24.x

MCP client

​Transports

​Observability

​Configure your MCP client

​OAuth setup (recommended)

​Cursor IDE (manual, API key)

​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

OAuth setup (recommended)

Cursor IDE (manual, API key)

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