io.github.sudzikcoin/pingpoint

Official

by sudzikcoin · TypeScript

Live truck GPS: create loads, read position, ETA, driver state, trip stats. API key or USDC x402.

io.github.sudzikcoin/pingpoint — PingPoint MCP Server

This MCP server provides a live truck GPS data interface for an AI agent. It can create a freight load, send the driver an app link, read live position, GPS track, stop timeline, ETA, and driver state/trip stats, and cancel a load when it’s no longer needed.

🛠️ Key Features

Create freight loads
Read live truck GPS position and GPS track
Provide stop timeline and ETA
Driver state and trip stats
Cancel a load

🚀 Use Cases

Freight tracking and freight visibility
Supply-chain logistics workflows
Geofencing-related operations using live location (as supported by GPS tracking)
Load lifecycle management (create → track → cancel)

⚡ Developer Benefits

Model Context Protocol (MCP) server for tooling integration
TypeScript-focused SDK/library ecosystem (topic-listed)
Sandbox key available for the same endpoints without signup

⚠️ Limitations

Onboarding for the driver/app link is required (“about a minute” per description)
No ELD provider, corporate account, or annual contract is mentioned as not required for onboarding (but specifics beyond that are not provided)

Topics

ai-agentsapi-clientclaudedriver-locationeldfreightfreight-trackingfreight-visibilitygeofencinggps-trackingload-trackinglogisticsmcpmcp-servermodel-context-protocolsdksupply-chaintelematicstruckingtypescript

packages/mcp/README.md13 KBView on GitHub

@suverselabs/pingpoint-mcp

MCP server that gives an AI agent a live truck GPS position: create a freight load, PingPoint texts the driver an app link (onboarding takes about a minute — no ELD provider, no corporate account, no annual contract), then read live position, GPS track, stop timeline and ETA, and cancel a load you no longer need.

No account yet? A sandbox key is published at https://pingpoint.suverse.io/docs/#sandbox: same endpoints, no signup, and the load drives itself through the full cycle in about 20 minutes. Or skip keys entirely and pay per call with USDC from a wallet on Arc, Base or Solana.

Install

Claude Code, one line:

bash

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

Or add to your MCP config (Claude Desktop: claude_desktop_config.json; Claude Code: .mcp.json; any MCP-capable agent works the same way):

json

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

Restart the agent and the tools appear.

Tools

Tool	What it does	Returns	Price
`create_load`	Creates a freight load (multi-stop supported); PingPoint texts the driver app link to `driverPhone`	`loadNumber`, public `trackingLink`, driver web/app links, dedup flag	$0.65
`get_load_position`	Live state of a load by load number	status, driver tracking state (`driverTracking`) with invite/open/decline timestamps, GPS track (last 500 points), stops with arrive/depart timestamps, distance covered, on-time flag, dwell times, ETA block	$0.02
`get_trip_stats`	Post-trip summary over the whole GPS trip (best on a DELIVERED load)	`stats` with distance, duration, avg/max speed, hard accel/brake counts, city/highway/parked/night shares, GPS coverage, first/last ping	$0.02
`cancel_load`	Cancels the load: status CANCELLED, tracking stops, nothing deleted, no refund	`{ ok, loadNumber, previousStatus, status, cancelledAt, trackingEndedAt }`	free
`update_load_status`	Not part of the API — statuses are GPS-verified, see below	HTTP 501 `OPERATION_NOT_AVAILABLE`	—
`get_pricing`	Current USD price list for agent operations	`{ currency, prices }`	free
`get_balance`	Prepaid balance that pays for creates and position reads	`{ currency, balanceUsd }`	free

Why update_load_status answers 501. PingPoint drives load statuses itself, from driver GPS and geofence events, so external status writes don't exist. Treat that as a data-integrity guarantee: a status you read was never hand-set by anyone; it is backed by actually recorded position. The tool is kept only so an agent that tries it gets a clear answer instead of a mystery. Delivery confirmation is likewise not a vendor operation — it belongs to the carrier flow, where the carrier files the BOL over Telegram.

Stops. A load carries 1–2 pickups and 1–3 deliveries; array order is the stop sequence. Each stop takes an optional window: date (start) and dateTo (end). onTime is measured against the dateTo of the last delivery, so without it that field stays null. Stops are fixed at creation — there is no add-stop tool.

Required to create a load: driverPhone (E.164 — the driver app link is sent to that number) plus pickups and deliveries arrays; every stop needs address, city, state, zip. Everything else is optional. customerRef doubles as a dedup key; pass the same idempotencyKey on retries so the balance is charged at most once.

Example — "where is my load?"

get_load_position with { "loadNumber": "LD-2026-042317" } returns:

json

{
  "loadNumber": "LD-2026-042317",
  "pingpointLoadId": "6f1c2d3e-8a45-4b9c-9d10-2e5f7a8b9c01",
  "status": "IN_TRANSIT",
  "createdAt": "2026-08-18T14:02:11.000Z",
  "deliveredAt": null,
  "driverTracking": "REPORTING",
  "inviteSentAt": "2026-08-18T14:02:12.000Z",
  "linkOpenedAt": null,
  "declinedAt": null,
  "distanceMiles": 412.7,
  "onTime": null,
  "delayMinutes": null,
  "pickupDwellMinutes": 38,
  "deliveryDwellMinutes": null,
  "stops": [
    { "type": "PICKUP", "sequence": 1, "city": "Claremore", "state": "OK",
      "windowFrom": "2026-08-18T15:00:00.000Z", "windowTo": "2026-08-18T19:00:00.000Z",
      "arrivedAt": "2026-08-18T15:47:31.000Z", "departedAt": "2026-08-18T16:25:09.000Z" },
    { "type": "DELIVERY", "sequence": 2, "city": "Charlotte", "state": "NC",
      "windowFrom": "2026-08-20T12:00:00.000Z", "windowTo": "2026-08-20T16:00:00.000Z",
      "arrivedAt": null, "departedAt": null }
  ],
  "gpsTrack": [
    { "lat": 36.3126, "lng": -95.6161, "speed": null, "heading": null, "ts": "2026-08-18T16:25:09.000Z" },
    { "lat": 35.4676, "lng": -94.3579, "speed": null, "heading": null, "ts": "2026-08-18T18:55:42.000Z" }
  ],
  "pingCount": 214,
  "eta": {
    "nextStop": { "type": "DELIVERY", "sequence": 2, "city": "Charlotte", "state": "NC" },
    "receivingWindow": { "from": "2026-08-20T12:00:00.000Z", "to": "2026-08-20T16:00:00.000Z" },
    "distanceToNextStopMi": 611.4,
    "driveTimeHours": 11.2,
    "moving": true,
    "stoppedForMinutes": null,
    "etaWindow": { "from": "2026-08-20T13:05:00.000Z", "to": "2026-08-20T15:40:00.000Z" },
    "tracking": { "state": "pinging", "noDataForMinutes": null },
    "reason": null
  }
}

(gpsTrack shortened here; the API returns up to the last 500 points.)

Example — "how did the trip go?"

get_load_position answers "where is the truck now"; get_trip_stats answers "how did the finished trip go". On a DELIVERED load, get_trip_stats with { "loadNumber": "LD-2026-648319" } returns:

json

{
  "loadNumber": "LD-2026-648319",
  "loadId": "927741bc-dfd0-41ba-9e99-5c5031c756f9",
  "stats": {
    "dataPoints": 4785,
    "durationSeconds": 69329,
    "estimatedDistanceMiles": 486.591,
    "avgSpeedMph": 25.27,
    "maxSpeedMph": 88.22,
    "hardAccelCount": 280,
    "hardBrakeCount": 168,
    "cityMilesPct": 9.96,
    "highwayMilesPct": 88.65,
    "parkedTimePct": 53.65,
    "nightPct": 44.7,
    "coveragePct": 100,
    "firstAt": "2026-08-18T16:53:25.000Z",
    "lastAt": "2026-08-19T12:08:54.000Z"
  }
}

Distances are miles, speeds are mph, percentages are 0–100, timestamps are UTC.

driverTracking in the get_load_position answer is the same word the PingPoint cabinet shows, so the agent can explain a silent load without guessing from an empty track:

`driverTracking`	Meaning	Look at
`NOT_BOUND`	Driver link never opened in the app	`inviteSentAt` (SMS went out?), `linkOpenedAt` (opened in a browser but app not installed)
`BOUND_SILENT`	App bound to the load, no position yet	wait for the first ping
`DECLINED`	Driver tapped "Not now" on the location-consent screen	`declinedAt`; cleared once the driver agrees
`REPORTING`	Positions arriving	`gpsTrack`, `eta`
`PAUSED_BY_DRIVER`	Sharing paused from the app	`eta.tracking.state === "driver_paused"`

null means the load has no driver yet.

Webhooks

Push notifications (pingpoint.load.created, pingpoint.load.updated, pingpoint.status.changed, pingpoint.load.completed, pingpoint.exception.raised, pingpoint.exception.resolved — the last two for LATE / NO_SIGNAL / LONG_DWELL) are configured in the cabinet, not through MCP tools: https://pingpoint.suverse.io/docs/webhooks

Pay per call with USDC

No account, no key: point the server at a wallet and every paid tool call is settled from it in USDC over x402 (HTTP 402 + a signed USDC transfer). PingPoint's relayer submits the transfer and pays the gas; the server only signs. Pick the chain with PINGPOINT_NETWORK:

`PINGPOINT_NETWORK`	Key file holds	USDC
`arc-mainnet`	EVM private key, `0x` + 64 hex	USDC on Arc `0x3600…0000`
`arc-testnet` (default)	EVM private key, `0x` + 64 hex	Arc testnet USDC `0x3600…0000` (faucet)
`base-mainnet`	EVM private key, `0x` + 64 hex	Circle USDC on Base `0x8335…2913`
`solana-mainnet`	Solana secret key — the 64-byte JSON array written by `solana-keygen`, or base58	Circle USDC mint `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`

bash

# EVM (Arc testnet / Base)
echo "0x<64 hex private key>" > ~/.pingpoint-wallet.key && chmod 600 ~/.pingpoint-wallet.key
claude mcp add pingpoint --env PINGPOINT_WALLET_KEY_FILE=$HOME/.pingpoint-wallet.key --env PINGPOINT_NETWORK=base-mainnet -- npx -y @suverselabs/pingpoint-mcp

# Solana
solana-keygen new --outfile ~/.pingpoint-wallet.json   # or point at an existing keypair file
claude mcp add pingpoint --env PINGPOINT_WALLET_KEY_FILE=$HOME/.pingpoint-wallet.json --env PINGPOINT_NETWORK=solana-mainnet -- npx -y @suverselabs/pingpoint-mcp

json

{
  "mcpServers": {
    "pingpoint": {
      "command": "npx",
      "args": ["-y", "@suverselabs/pingpoint-mcp"],
      "env": {
        "PINGPOINT_WALLET_KEY_FILE": "/home/me/.pingpoint-wallet.json",
        "PINGPOINT_NETWORK": "solana-mainnet",
        "PINGPOINT_RPC_URL": "https://<your-solana-rpc>"
      }
    }
  }
}

Fund the wallet with USDC on that network (ask get_balance — it returns the address and the balance), then use the tools as usual. On Solana the wallet needs no SOL: PingPoint's relayer is the transaction fee payer. Paid results carry a payment block with the transaction hash (EVM) or signature (Solana) and an explorer link:

json

{ "loadNumber": "LD-2026-111417", "trackingLink": "https://pingpoint.suverse.io/track/…",
  "payment": { "transaction": "0x97f738e3…", "network": "base-mainnet", "payer": "0xE958…dB2E",
               "amountUsdc": "0.65", "explorerUrl": "https://basescan.org/tx/0x97f738e3…" } }

Tool	Price (USDC)	Notes
`create_load`	0.65	per wallet and network: 2 loads per 24 hours on a testnet, 20 on a mainnet; a driver phone used by another wallet within the hour is refused
`get_load_position`	0.02 per call	only loads created by this wallet (another wallet's load → 403)
`get_trip_stats`	0.02 per call	same ownership rule
`cancel_load`	free	zero-value signature proves ownership, no transaction
`get_pricing`	free	reads the server's 402 offers, nothing signed
`get_balance`	free	one RPC read of the wallet's USDC (ERC-20 `balanceOf` or the Solana token account); `PINGPOINT_RPC_URL` overrides the public RPC

A refused call (403, 404, 429, invalid input, PaymentFailed INSUFFICIENT_BALANCE, 503 X402_RELAYER_LOW_GAS) costs nothing: ownership, limits, balance and the relayer's gas are checked before settlement. EVM offers live 300 s with a one-time nonce per signature; a Solana transaction lives as long as its blockhash (about a minute). The SDK refuses offers above 1 USDC or on another asset or network before signing. Keep the key file private (chmod 600) — a wallet holding just enough USDC for the day is the sensible setup. Public RPC endpoints (Base, Solana) rate-limit; set PINGPOINT_RPC_URL to your provider for steady use.

Getting a key

Sign up at pingpoint.suverse.io (e-mail or Google/GitHub).
In the cabinet open Integrations → Agent API and press Issue key.
The sup_agent_… key arrives by e-mail. PingPoint never stores the secret — if it's lost, re-issue from the same page.

Free operations work at zero balance. Paid ones debit your prepaid balance (top up in the cabinet, Billing); when it can't cover a call you get 402 INSUFFICIENT_FUNDS and nothing is charged.

Pricing

Operation	Price
Create a load	$0.65
Read load position	$0.02 per request
Trip summary stats	$0.02 per request
Cancel a load	free
Update load status	not available (501)
Pricing / balance	free

The same prices apply in USDC when paying per call with a wallet.

Environment

Variable	Meaning
`PINGPOINT_AGENT_KEY`	Your `sup_agent_…` key. Exactly one of this and `PINGPOINT_WALLET_KEY_FILE` is required.
`PINGPOINT_WALLET_KEY_FILE`	Path to a file holding the paying wallet's private key — pay per call with USDC instead of a key. EVM networks: `0x` + 64 hex. Solana: the `solana-keygen` JSON array (64 bytes) or base58.
`PINGPOINT_NETWORK`	Wallet mode: `arc-testnet` (default), `arc-mainnet`, `base-mainnet` or `solana-mainnet`.
`PINGPOINT_RPC_URL`	Wallet mode, optional: JSON-RPC URL of that chain for `get_balance` (and, on Solana, the blockhash read that every payment needs). Defaults to the public RPC, which rate-limits.
`PINGPOINT_BASE_URL`	Optional. Defaults to `https://api.suverse.io` with a key and `https://pingpoint.suverse.io` with a wallet.

Built on @suverselabs/pingpoint-sdk — same contract, one implementation. Node ≥ 18. Runtime deps: the MCP SDK, zod, viem (EVM wallet signing and balance read) and @solana/web3.js (Solana keypair signing).

Full API documentation: https://pingpoint.suverse.io/docs

Install

Configuration

Environment variables

PINGPOINT_AGENT_KEYsecret

PingPoint Agent API key (sup_agent_...), issued in the cabinet: Integrations -> Agent API. Either this or PINGPOINT_WALLET_KEY_FILE.

PINGPOINT_WALLET_KEY_FILEsecret

Pay per call with USDC (x402) instead of a key: path to a file holding the wallet key - EVM private key (0x + 64 hex) for arc-mainnet/arc-testnet/base-mainnet, solana-keygen JSON or base58 secret for solana-mainnet. Either this or PINGPOINT_AGENT_KEY.

PINGPOINT_NETWORKdefault arc-testnet

Network for wallet mode: arc-testnet (default), arc-mainnet, base-mainnet or solana-mainnet

PINGPOINT_BASE_URL

Override for the PingPoint API base URL (default https://api.suverse.io with a key, https://pingpoint.suverse.io with a wallet)

PINGPOINT_RPC_URL

Wallet mode only: JSON-RPC URL of the chosen chain for get_balance and, on Solana, the blockhash read each payment needs (default: the public RPC, which rate-limits)

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "pingpoint": {
      "command": "npx",
      "args": [
        "-y",
        "@suverselabs/pingpoint-mcp@0.5.1"
      ],
      "env": {
        "PINGPOINT_AGENT_KEY": "<YOUR_PINGPOINT_AGENT_KEY>",
        "PINGPOINT_WALLET_KEY_FILE": "<YOUR_PINGPOINT_WALLET_KEY_FILE>",
        "PINGPOINT_NETWORK": "arc-testnet",
        "PINGPOINT_BASE_URL": "<YOUR_PINGPOINT_BASE_URL>",
        "PINGPOINT_RPC_URL": "<YOUR_PINGPOINT_RPC_URL>"
      }
    }
  }
}

io.github.sudzikcoin/pingpoint — PingPoint MCP Server

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

@suverselabs/pingpoint-mcp

Install

Tools

Example — "where is my load?"

Example — "how did the trip go?"

Is the driver actually sharing?

Webhooks

Pay per call with USDC

Getting a key

Pricing

Environment

Install

Configuration