# Global Logistics MCP

<!-- install-cta -->
## Use it in 60 seconds

Paste this into your MCP client config (Claude Desktop, Cursor, Windsurf, or any MCP-capable agent):

```json
{
  "mcpServers": {
    "global-logistics": {
      "type": "http",
      "url": "https://logi-global.wishpool.app/mcp"
    }
  }
}
```

Nothing to install. Credentials, when you need them, travel as HTTP headers on each request and are never stored — see the [threat model](https://mcp.wishpool.app/trust).

### Or run it yourself

Would you rather not send production credentials to a server you do not control? Deploy this identical code to your own account and point your agent at your own URL:

[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/junter1989k-ai/global-logistics-mcp)

```bash
git clone https://github.com/junter1989k-ai/global-logistics-mcp && cd global-logistics-mcp && npx vercel --prod
```

MIT-licensed. Self-hosting removes us from the picture entirely, at no cost and with no loss of function.

---

Remote MCP server that lets any AI agent **buy shipping labels worldwide** via
[AfterShip Shipping (Postmen)](https://www.aftership.com/shipping) — UPS, USPS, FedEx, DHL,
Ninja Van, J&T and more — using the **merchant's OWN bound carrier accounts**. Stateless,
bring-your-own API key, never stored.

- **Endpoint:** `https://logi-global.wishpool.app/mcp` (MCP Streamable HTTP, stateless JSON)
- **Credential header:** `x-aftership-key` (your AfterShip key; forwarded upstream as `as-api-key`)
- **Environment header:** `x-aftership-env` = `sandbox` (default — real labels at zero cost) or `production`

## The aggregation model (the honest core)

This server **owns no carrier accounts**. AfterShip is an aggregation layer: the **merchant**
binds their **own** carrier accounts (their contracts and rates) inside AfterShip
(`admin.postmen.com`) and passes that `shipper_account_id` on each call. This is exactly how an
agent reaches carriers that do **not** issue self-serve API keys — **J&T, Ninja Van, Aramex** —
the curve-around is the merchant's AfterShip-bound account. The sandbox can be tested with a fake
shipper account at zero cost.

## Tools & capability matrix

| Tool | AfterShip endpoint | Supported | Notes |
|---|---|---|---|
| `quote_rates` | `POST /postmen/v3/rates` | ✅ yes | Compare live rates across the carriers on `shipper_account_id`. Read-only, buys nothing. Returns `service_type` + `total_charge`. |
| `create_label` | `POST /postmen/v3/labels` (pre-quoted via `/rates`) | ✅ yes | Buy a chosen `service_type`. Re-quotes the exact charge and applies owner policy guardrails **before** buying. Returns `label_url` + `tracking_number`. |
| `cancel_label` | `POST /postmen/v3/cancel-labels` | ✅ yes | Void an unused label by `label_id`. `cancel_status`: cancelled / pending / failed. Idempotent. |
| `query_tracking` | — | ❌ **not supported** | The Shipping (Postmen) API has no tracking endpoint. Tracking is a separate product: the [AfterShip Tracking API](https://www.aftership.com/docs/tracking). Returns a structured `not_supported` result (never errors). |

Addresses use **ISO 3166-1 alpha-3** country codes (`USA`, `GBR`, `JPN`). Weight and dimension are
`{value, unit}` (unit `kg|lb|oz|g` and `cm|in|m`).

## Owner policy guardrails

Set by the human owner in the MCP client config; the agent cannot relax them. The label charge is
gated **before** any purchase.

- `x-agentpay-max-amount` — hard cap; over it, `POLICY_BLOCKED`.
- `x-agentpay-approval-above` — over it, returns an unsigned **draft** (rate quoted, no label bought).
- `x-agentpay-allowed-tools` — tool allow-list.

## Safety

Stateless translation layer: the AfterShip API key travels per-request in a header and is never
stored; labels are generated and served by AfterShip/the carrier, never held here. Parcels flow
sender ↔ carrier ↔ recipient directly.

## Develop

```bash
npm run dev    # local server on http://localhost:3242
npm test       # e2e: protocol + validation + units + fake-key real 401 fingerprint
```

The e2e suite includes a **live** probe: a fake key really hits `sandbox-api.aftership.com` and
must receive the native `401 "The API key is invalid."` fingerprint (proving the endpoint is alive).

## Sister servers

US domestic labels via EasyPost — [usa-logistics-mcp](https://logi-us.wishpool.app) · Taiwan CVS
pickup & home delivery — [taiwan-logistics-mcp](https://logi-tw.wishpool.app) · local payments in
81 countries — [mcp.wishpool.app](https://mcp.wishpool.app) · electronic-invoice servers across
nine countries (Mexico CFDI, Brazil NF-e, Chile DTE, Peru CPE, India GST).

MIT.