PingPoint — 화물 추적 MCP 서버 및 SDK

물류 소프트웨어와 AI 에이전트를 위한 실시간 화물 추적 및 화물 가시성: MCP 서버와 TypeScript SDK로, 모든 에이전트가 미국 트럭 운송의 트럭 적재 화물에 대한 실시간 운전자 GPS 위치를 얻을 수 있습니다. API로 화물을 생성하면 운전자가 약 1분 만에 SMS 링크로 연결되고, 그 이후로 위치, ETA, 정차 타임라인, 운행 후 통계를 한 번의 호출로 확인할 수 있습니다. ELD 제공업체 통합, 기업 계약, 영업 전화가 필요 없습니다.

전체 API 문서: https://pingpoint.suverse.io/docs · OpenAPI 3.1 스펙: /docs/openapi.json

문제

미국 트럭 운송의 대부분 운송사는 트럭 1~2대를 보유한 회사입니다. 기업용 텔레매틱스 스택도, 가시성 계약도, IT 부서도 없습니다. 트럭이 곧 회사입니다. 브로커가 화물의 위치를 알아야 할 때, 믿을 수 있는 유일한 수단은 운전자에게 전화하는 것입니다.

그래서 오늘날 대부분 공급업체의 "AI track & trace"는 사람에게 전화를 걸어 묻는 로봇을 의미합니다. 위치 데이터 자체는 결코 기계 판독이 가능해지지 않습니다. 한 번에 한 통화씩, 한 운전자의 머릿속에만 존재하기 때문입니다. PingPoint는 위치 자체를 API로 제공합니다. 운전자가 SMS 링크에서 앱 하나를 설치하면, 그 순간부터 어떤 소프트웨어든 — 또는 MCP를 통한 어떤 AI 에이전트든 — 누군가에게 전화를 걸어 묻는 대신 실시간 GPS를 읽습니다.

Related MCP server: ThinAir Geo

작동 방식

1. API로 화물 생성

POST /v1/agent/loads에 운전자 전화번호와 정차지를 포함합니다. 필수: driverPhone(E.164 — 운전자 링크가 이 번호로 문자 전송됨) 및 pickups / deliveries 배열; 각 정차지에는 address, city, state, zip이 필요합니다. 다중 정차지 화물이 지원됩니다 — 배열 순서대로 여러 픽업과 여러 배송.

응답에는 loadNumber(이후 모든 호출에서 사용), 고객용 공개 trackingLink, 운전자 웹/앱 링크가 포함됩니다. 이중 청구를 방지하는 두 가지 안전장치가 있습니다:

• customerRef는 중복 제거 키(dedup key) 역할을 합니다 — 동일한 참조를 다시 보내면 중복을 생성하는 대신 기존 화물을 반환합니다(deduplicated: true);

• Idempotency-Key 헤더는 네트워크 오류 후 재시도를 안전하게 만듭니다 — 잔액이 차감되고 화물이 최대 한 번만 생성됩니다.

2. 운전자가 SMS 링크로 연결

PingPoint는 운전자에게 링크를 자동으로 문자로 보냅니다. 링크를 열면 온보딩이 시작됩니다: 앱 설치, 동의 화면 통과, 완료 — 운전자 시간 약 1분, 한 번만. 내부적으로 링크는 일회용 화물 토큰을 담고 있으며, 앱이 이 토큰을 영구 기기 토큰으로 교환합니다. 따라서 같은 전화번호로 오는 다음 화물은 별도 설정 없이 연결됩니다.

3. 두 개의 독립적인 채널로 위치 유입

• 운전자의 휴대폰 — 앱의 백그라운드 위치 정보.

• 트럭 진단 포트의 ELD 동글 — 차량 데이터를 Bluetooth로 앱에 스트리밍하고, 앱이 이를 중계합니다. IOSiX 및 Pacific Track PT30 하드웨어로 테스트되었습니다. 동글은 1Hz로 프레임을 내보내며, 앱은 업로드 전에 프레임을 줄여서 저장된 트랙이 파이프라인을 과부하시키지 않으면서 지오펜싱에 충분히 조밀하게 유지되도록 합니다.

휴대폰은 두 채널 모두의 게이트웨이로 유지됩니다 — 동글은 네트워크가 아닌 앱과 통신합니다. 두 소스를 사용하는 이유는 실패 방식이 다르기 때문입니다: 휴대폰의 GPS가 위치를 잡지 못하거나 OS가 백그라운드 위치 정보를 제한해도, 동글은 엔진이 작동하는 한 위치를 계속 제공합니다. 동글 프레임은 또한 업로드 시점이 아닌 프레임 자체에서 가져온 자체 타임스탬프를 담고 있습니다. 따라서 오프라인 구간 후 버퍼링된 백로그가 플러시될 때 기록된 시간은 실제 시간입니다.

4. 상태는 키보드가 아닌 지오펜스로 진행

모든 픽업 및 배송 정차지에는 지오펜스가 설정됩니다. 픽업 구역에 진입하면 화물이 AT_PICKUP으로 전환되고, 벗어나면 IN_TRANSIT으로, 배송 구역에 진입하면 AT_DELIVERY로 전환됩니다. 그리고 DELIVERED는 트럭이 최종 배송 구역에 도착할 때가 아니라 출발할 때 설정됩니다. 유일한 지름길은 명시적인 (무료) delivery-confirm 호출(BOL 확보)로, 트럭이 배송 정차지에 도착하면 화물을 완료 처리합니다. 정차지의 arrivedAt / departedAt 타임스탬프는 동일한 지오펜스 이벤트에서 생성됩니다.

외부 상태 쓰기는 의도적으로 차단되어 있습니다: PATCH …/status는 항상 410 STATUS_DOOR_CLOSED로 응답합니다. 이는 누락된 기능이 아니라 데이터 무결성 보장입니다 — 읽은 상태는 누구도 수동으로 설정한 적이 없으며, 그 뒤에는 기록된 위치가 있습니다.

5. 다시 읽기

GET /v1/agent/loads/{loadNumber}는 실시간 상태를 반환합니다: 상태, GPS 트랙(최근 최대 500개 지점), 도착/출발 타임스탬프가 포함된 정차 타임라인, 이동 거리, 체류 시간, 정시 여부 플래그, 저장된 경로 지오메트리와 최신 위치로 계산된 ETA 블록. 운행 후 GET …/trip-stats는 기록된 모든 핑을 기준으로 계산된 집계 요약을 반환합니다. 웹훅은 화물 이벤트가 발생하는 즉시 엔드포인트로 푸시할 수 있습니다(문서 참조).

 SMS link          +---------------------+
 (sent by  ------> |  Driver phone app   |--- background GPS ---+
  PingPoint)       +---------------------+                      |
                                                                v
                   +---------------------+   1 Hz frames   +--------------------+
                   |  ELD dongle on the  |---------------->| ingest (thinning)  |
                   |  diagnostic port,   |   via the app   +--------------------+
                   |  BLE (IOSiX, PT30)  |                      |
                   +---------------------+                      v
                                                       +-----------------+
                                                       |  position store |
                                                       +-----------------+
                                                            |        |
                                     geofence engine <------+        |
                                            |                        |
        PLANNED -> AT_PICKUP -> IN_TRANSIT -> AT_DELIVERY -> DELIVERED
                                            |                        |
                                            v                        v
                  webhooks -> your endpoint      GET /v1/agent/loads/{n}   (position, ETA)
                                                 GET .../trip-stats        (post-trip summary)

빠른 시작

키 발급

1. pingpoint.suverse.io에서 가입합니다(이메일 또는 Google/GitHub).

2. 대시보드에서 Integrations → Agent API를 열고 Issue key를 누릅니다.

3. sup_agent_… 키가 이메일로 도착합니다. PingPoint는 비밀 키를 저장하지 않습니다 — 분실한 경우 같은 페이지에서 새 키를 재발급하세요.

첫 번째 호출

curl -X POST https://api.suverse.io/v1/agent/loads \
  -H "Authorization: Bearer sup_agent_…" \
  -H "Content-Type: application/json" \
  -d '{
    "driverPhone": "+15551234567",
    "pickups":    [{ "address": "6492 Tower Lane", "city": "Claremore", "state": "OK", "zip": "74017" }],
    "deliveries": [{ "address": "6499 Caldwell Park Dr", "city": "Charlotte", "state": "NC", "zip": "28269" }],
    "customerRef": "PO-483920"
  }'

{
  "success": true,
  "loadId": "3b9f6a2e-1c47-4d8a-9e02-7f5b1c8d4a63",
  "loadNumber": "LD-2026-042317",
  "trackingLink": "https://pingpoint.suverse.io/track/trk_…",
  "driverWebLink": "https://pingpoint.suverse.io/driver/drv_…",
  "driverAppLink": "pingpoint://driver/drv_…",
  "driverResolution": "none"
}

운전자 링크는 이미 SMS로 +15551234567에 발송되었습니다. 이제 GET /v1/agent/loads/LD-2026-042317로 실시간 위치를 읽을 수 있습니다.

MCP 서버 연결

Claude Code, 한 줄:

claude mcp add pingpoint --env PINGPOINT_AGENT_KEY=sup_agent_… -- npx -y @suverselabs/pingpoint-mcp

Claude Desktop(claude_desktop_config.json) 또는 MCP 지원 에이전트:

{
  "mcpServers": {
    "pingpoint": {
      "command": "npx",
      "args": ["-y", "@suverselabs/pingpoint-mcp"],
      "env": {
        "PINGPOINT_AGENT_KEY": "sup_agent_…"
      }
    }
  }
}

에이전트를 다시 시작하면 도구가 나타납니다.

MCP 도구

전체 요청/응답 예시가 포함된 도구별 상세 참조: docs/tools/.

도구 설명은 호출하는 모델을 위해 작성되었습니다. 각 도구는 비용, 사용 시기, 사용하지 말아야 할 시기를 명시합니다(예: get_load_position은 "트럭이 지금 어디에 있는가"에 답하고, get_trip_stats는 "완료된 운행이 어땠는가"에 답하며, 두 도구 모두 모든 호출에 비용이 청구되므로 루프에서 폴링하지 말라고 경고합니다).

SDK

npm install @suverselabs/pingpoint-sdk

import { PingPointAgent, InsufficientFundsError, DeliveryNotReadyError } from "@suverselabs/pingpoint-sdk";

const pp = new PingPointAgent({ apiKey: process.env.PINGPOINT_AGENT_KEY! });

// $0.65 — driver gets the app link by SMS
const load = await pp.createLoad(
  {
    driverPhone: "+15551234567",
    pickups: [{ address: "6492 Tower Lane", city: "Claremore", state: "OK", zip: "74017" }],
    deliveries: [{ address: "6499 Caldwell Park Dr", city: "Charlotte", state: "NC", zip: "28269" }],
    customerRef: "PO-483920",
  },
  { idempotencyKey: "PO-483920" },
);

const pos = await pp.getPosition(load.loadNumber);   // $0.02
const trip = await pp.getTripStats(load.loadNumber); // $0.02, best after DELIVERED
await pp.confirmDelivery(load.loadNumber, { bolReceivedAt: new Date() }); // free

메서드: createLoad(input, { idempotencyKey? }), getPosition(loadNumber), getTripStats(loadNumber), updateStatus(loadNumber, status)(의도적인 410을 던지도록 문서화됨), confirmDelivery(loadNumber, { bolReceivedAt? }), getPricing(), getBalance(). 전체 참조: docs/sdk.md.

모든 2xx가 아닌 응답은 .status와 원시 .body를 담은 PingPointAgentError의 타입화된 하위 클래스를 던집니다:

try {
  await pp.createLoad(input);
} catch (err) {
  if (err instanceof InsufficientFundsError) {
    console.log(`balance $${err.balanceUsd}, need $${err.priceUsd} — nothing was charged`);
  } else if (err instanceof DeliveryNotReadyError) {
    // driver hasn't arrived yet — do NOT retry; the load completes automatically when the truck departs the delivery zone
  }
}

Node ≥ 18(전역 fetch 사용), ESM + CJS, 런타임 의존성 제로.

데이터 모델

Position (get_load_position / getPosition)

트립 통계 (get_trip_stats / getTripStats)

오류 코드

결제

선불 잔액, 호출당 과금, 구독 없음. 자세한 내용: docs/billing.md.

• 결제 아래의 대시보드에서 충전하세요. 무료 작업은 잔액이 0이어도 작동합니다.

• 402는 어떤 일이 발생하기 전에 호출이 거부되었음을 의미합니다: 생성된 것도, 청구된 것도 없습니다.

• 동일한 Idempotency-Key를 사용한 createLoad 재시도는 안전합니다 — 출금은 최대 한 번만 발생합니다. customerRef는 비즈니스 수준에서 중복을 제거합니다.

• 가격은 GET /v1/agent/pricing이 실시간으로 제공합니다 — 이를 진실의 원천으로 취급하고 절대 하드코딩하지 마세요.

이것이 아닌 것

• 인증된 ELD가 아닙니다. PingPoint는 가시성을 위해 GPS(및 동글을 통한 엔진 버스 데이터)를 읽습니다. FMCSA에 등록된 ELD가 아니며 HOS/RODS 규정 준수 기록을 생성하지 않습니다.

• 운송사 검증이 아닙니다. 실시간 위치는 트럭이 어디에 있는지 알려줄 뿐, 운송사가 안전한지, 보험에 가입했는지, 실재하는지는 알려주지 않습니다. 현재 수행 중인 온보딩 검증 절차를 유지하세요.

• 운전자가 앱을 설치해야 합니다. SMS 링크 하나, 설치 한 번, 약 1분이면 됩니다 — 하지만 운전자의 협조가 필요한 실제 단계입니다. 연결된 전화와 동글이 없는 화물은 위치를 생성하지 않습니다.

다른 솔루션과의 비교

엔터프라이즈 가시성 플랫폼은 운송사가 이미 텔레매틱스를 보유하고 있고 브로커가 이미 계약을 맺고 있다고 가정합니다. 통화 기반 추적 업체는 모든 확인마다 사람 또는 로봇의 전화 통화를 중간에 넣습니다. PingPoint의 거래 방식은 다릅니다: 운전자 측 설치 한 번으로 공개된 가격과 최소 금액이 없는 호출당 API를 제공합니다. 두 그룹 모두와의 사실적인 셀별 비교 — 키 발급, 공개 가격, API 표면, MCP/SDK 제공 여부 — 는 pingpoint.suverse.io/compare 에서 유지 관리됩니다.

링크

• API 문서: https://pingpoint.suverse.io/docs

• OpenAPI 3.1 스펙: https://pingpoint.suverse.io/docs/openapi.json

• 대안과의 비교: https://pingpoint.suverse.io/compare

• npm의 MCP 서버: https://www.npmjs.com/package/@suverselabs/pingpoint-mcp

• npm의 SDK: https://www.npmjs.com/package/@suverselabs/pingpoint-sdk

• 저장소 내 문서: architecture · billing · SDK reference · MCP tools

• 연락처: info@suverse.io

라이선스

MIT © 2026 Sudzik Group Inc.