PingPoint — servidor MCP y SDK de seguimiento de carga

Seguimiento de carga en tiempo real y visibilidad de envíos para software logístico y agentes de IA: un servidor MCP y un SDK de TypeScript que proporcionan a cualquier agente la posición GPS en vivo del conductor para un envío de carga completa en el transporte por carretera de EE. UU. — crea una carga a través de la API, el conductor se conecta desde un enlace SMS en aproximadamente un minuto, y a partir de entonces la posición, la hora estimada de llegada (ETA), el cronograma de paradas y las estadísticas posteriores al viaje están a una sola llamada de distancia. Sin integración con proveedores de ELD, sin contrato corporativo, sin llamada de ventas.

Documentación completa de la API: https://pingpoint.suverse.io/docs · Especificación OpenAPI 3.1: /docs/openapi.json

El problema

La mayoría de los transportistas en el transporte por carretera de EE. UU. son empresas de uno o dos camiones. No tienen una plataforma telemática corporativa, ni contrato de visibilidad, ni departamento de TI: el camión es la empresa. Cuando un bróker necesita saber dónde está una carga, el único instrumento fiable es una llamada telefónica al conductor.

Por eso, el «seguimiento y localización con IA» de la mayoría de los proveedores actuales significa un robot que llama a un humano y pregunta. Los datos de posición en sí nunca se vuelven legibles por máquina: viven en la cabeza de un conductor, una llamada a la vez. PingPoint hace que la propia posición esté disponible a través de una API: el conductor instala una aplicación desde un enlace SMS y, desde ese momento, cualquier software —o cualquier agente de IA a través de MCP— lee el GPS en vivo en lugar de pedirle a alguien que marque un número.

Related MCP server: ThinAir Geo

Cómo funciona

1. Una carga se crea a través de la API

POST /v1/agent/loads con el teléfono del conductor y las paradas. Obligatorios: driverPhone (E.164 — el enlace del conductor se envía por SMS a este número) y los arrays pickups / deliveries; cada parada necesita address, city, state, zip. Se admiten cargas de múltiples paradas: varias recogidas y varias entregas, en el orden del array.

La respuesta incluye el loadNumber (utilizado en todas las llamadas posteriores), un trackingLink público para el cliente y los enlaces web/aplicación del conductor. Dos redes de seguridad contra la doble facturación:

• customerRef actúa también como clave de deduplicación: reenviar la misma referencia devuelve la carga existente (deduplicated: true) en lugar de crear un duplicado;

• una cabecera Idempotency-Key hace que los reintentos tras un fallo de red sean seguros: el saldo se debita y la carga se crea como máximo una vez.

2. El conductor se conecta desde un enlace SMS

PingPoint envía automáticamente un enlace al conductor por SMS. El enlace abre la incorporación: instala la aplicación, acepta el consentimiento, listo: aproximadamente un minuto del tiempo del conductor, una sola vez. Internamente, el enlace lleva un token de carga de un solo uso que la aplicación intercambia por un token de dispositivo persistente, de modo que la siguiente carga al mismo número de teléfono se vincula sin ninguna configuración nueva.

3. La posición llega a través de dos canales independientes

• El teléfono del conductor — geolocalización en segundo plano desde la aplicación.

• Un dongle ELD en el puerto de diagnóstico del camión — transmite datos del vehículo por Bluetooth a la aplicación, que los retransmite. Probado con hardware IOSiX y Pacific Track PT30. El dongle emite tramas a 1 Hz; la aplicación las reduce antes de la subida para que la pista almacenada siga siendo lo bastante densa para la geocerca sin saturar el canal.

El teléfono sigue siendo la puerta de enlace para ambos canales: el dongle habla con la aplicación, no con la red. La idea de tener dos fuentes es que fallan de forma distinta: el dongle sigue proporcionando posiciones mientras el motor esté en marcha, incluso cuando el GPS del teléfono no puede obtener una señal o el sistema operativo ha limitado la geolocalización en segundo plano. Las tramas del dongle también llevan sus propias marcas de tiempo, tomadas de la propia trama en lugar del momento de la subida, de modo que cuando se vacía un backlog almacenado tras un periodo sin conexión, los tiempos registrados son los reales.

4. Los estados avanzan mediante geocercas, nunca desde un teclado

Cada parada de recogida y entrega tiene una geocerca. Entrar en la zona de recogida mueve la carga a AT_PICKUP, salir de ella la mueve a IN_TRANSIT, entrar en la zona de entrega a AT_DELIVERY — y DELIVERED se establece cuando el camión sale de la zona de entrega final, no cuando llega. El único atajo es la llamada explícita (gratuita) delivery-confirm (con el BOL en mano), que completa la carga una vez que el camión está en su parada de entrega. Las marcas de tiempo arrivedAt / departedAt de las paradas provienen de los mismos eventos de geocerca.

Las escrituras externas de estado están cerradas a propósito: PATCH …/status siempre responde 410 STATUS_DOOR_CLOSED. Esto es una garantía de integridad de datos, no una función ausente: un estado que lees nunca fue establecido manualmente por nadie; hay posición registrada detrás de él.

5. Leer los datos

GET /v1/agent/loads/{loadNumber} devuelve el estado en vivo: estado, la pista GPS (hasta los 500 puntos más recientes), el cronograma de paradas con marcas de tiempo de llegada/salida, distancia recorrida, tiempos de permanencia, indicador de puntualidad y un bloque ETA calculado a partir de la geometría de ruta almacenada y la posición más reciente. Después del viaje, GET …/trip-stats devuelve un resumen agregado calculado sobre cada ping registrado. Los webhooks pueden enviar eventos de carga a tu endpoint a medida que ocurren (consulta la documentación).

 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)

Inicio rápido

Obtener una clave

1. Regístrate en pingpoint.suverse.io (correo electrónico o Google/GitHub).

2. En el panel, abre Integraciones → Agent API y pulsa Emitir clave.

3. La clave sup_agent_… llega por correo electrónico. PingPoint nunca almacena el secreto: si se pierde, emite una nueva desde la misma página.

Primera llamada

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"
}

El enlace del conductor ya está de camino a +15551234567 por SMS. Desde aquí, GET /v1/agent/loads/LD-2026-042317 lee la posición en vivo.

Conectar el servidor MCP

Claude Code, una línea:

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

Claude Desktop (claude_desktop_config.json) o cualquier agente compatible con MCP:

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

Reinicia el agente y las herramientas aparecerán.

Herramientas MCP

Referencia detallada por herramienta con ejemplos completos de solicitud/respuesta: docs/tools/.

Las descripciones de las herramientas están escritas para el modelo que las invoca: cada una indica cuánto cuesta, cuándo usarla y cuándo no (p. ej., get_load_position responde «dónde está el camión ahora», get_trip_stats responde «cómo fue el viaje terminado», y ambas advierten contra el sondeo en bucle porque cada llamada se factura).

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

Métodos: createLoad(input, { idempotencyKey? }), getPosition(loadNumber), getTripStats(loadNumber), updateStatus(loadNumber, status) (documentado para lanzar el 410 intencional), confirmDelivery(loadNumber, { bolReceivedAt? }), getPricing(), getBalance(). Referencia completa: docs/sdk.md.

Toda respuesta que no sea 2xx lanza una subclase tipada de PingPointAgentError que lleva .status y el .body sin procesar:

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 (usa fetch global), ESM + CJS, cero dependencias en tiempo de ejecución.

Modelo de datos

Posición (get_load_position / getPosition)

Estadísticas del viaje (get_trip_stats / getTripStats)

Códigos de error