# Hansatic MCP — load planning for AI agents

Give your AI agent the ability to pack trucks and shipping containers. This
[MCP](https://modelcontextprotocol.io) server wraps the
[Hansatic packing API](https://hansatic.com/en/docs): submit a cargo manifest,
get back a physically valid layout — placements with rotation, stacking,
fragility, weight and axle constraints respected — plus the freight billing
metrics that matter: **LDM (loading meters), linear feet, and EUR pallet
positions**.

> "Pack 14 machine crates and 8 EUR pallets into a 13.6m curtainsider" →
> a validated 3D load plan with 5.25 LDM, in one tool call.

## Setup

1. **Get an API key** (free): [hansatic.com](https://hansatic.com) → sign in →
   click your name → **API** → *Generate key*. Every account includes 25 free
   sandbox packs/month — no subscription needed to try it.

2. **Add the server** to your MCP client:

**Claude Code**
```bash
claude mcp add hansatic -e HANSATIC_API_KEY=hk_live_... -- npx -y hansatic-mcp
```

**Claude Desktop** (`claude_desktop_config.json`)
```json
{
  "mcpServers": {
    "hansatic": {
      "command": "npx",
      "args": ["-y", "hansatic-mcp"],
      "env": { "HANSATIC_API_KEY": "hk_live_..." }
    }
  }
}
```

**Cursor** (`.cursor/mcp.json`) — same shape as Claude Desktop.

## Tools

| Tool | What it does |
|---|---|
| `pack_cargo` | Optimize a cargo manifest into a vehicle. Async under the hood; returns the finished layout + metrics in one call (typically 5–30s). Production accounts get a `plan_url` — the layout opens in Hansatic's 3D editor. |
| `list_vehicles` | All built-in trucks, trailers and containers with interior dimensions and payload — the valid `vehicle` codes. |
| `check_job` | Poll a job by id (only for very large manifests that outlive the tool timeout). |

## Notes

- **Units**: metric (mm/kg) by default; pass `units: "imperial"` for in/lb —
  results come back in the same units.
- **Sandbox vs production**: non-enterprise keys sandbox automatically (full
  result, nothing persisted). Enterprise keys create a real plan in the
  workspace, editable at the returned `plan_url`.
- The engine is validated continuously against real dispatcher layouts —
  see [how the algorithm is measured](https://hansatic.com/en/docs).
- REST API, OpenAPI spec and full docs: [hansatic.com/en/docs](https://hansatic.com/en/docs)

MIT licensed. The optimization engine runs server-side at hansatic.com.