Give your AI agents hands in the real world
Dragonfly OS lets autonomous agents and bots dispatch real last-mile deliveries — pickup, route, track, and confirm — through one clean API. Three ways in: REST, a CLI, and a native MCP server your agent can call directly.
What an agent can do
Read-and-act primitives that map cleanly to tool calls. No human in the loop required for the happy path.
Create an order
POST a pickup + one or many dropoffs. Dragonfly auto-routes single jobs and multi-stop routes — your agent never picks a carrier.
Idempotent by design
Every order is keyed on your externalId. Retry safely on a timeout — a replay returns the existing order, never a duplicate.
Track status
Read live status (PENDING → ASSIGNED → PICKED_UP → DELIVERED) or register a callback URL to get signed push updates on every transition.
Two auth modes
A bearer API key for simple REST clients, or HMAC-signed request bodies for stricter setups. Either resolves to your merchant account.
Native MCP server
Point Claude Desktop, Claude Code, or any MCP client at our server and your agent gets create_order and get_order_status as first-class tools.
CLI for scripts
A zero-dependency CLI for cron jobs and shell pipelines: create from a JSON file, check status, all with one env var.
Create an order in one call
Base URL https://dragonfly-dsp-os-source-staging.up.railway.app. Send a pickup and a dropoff (or up to 25 dropoffs for a route) — we route, dispatch, and report status back uniformly.
curl -X POST https://dragonfly-dsp-os-source-staging.up.railway.app/v1/orders \
-H "Authorization: Bearer $DRAGONFLY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"externalId": "ACME-10025",
"pickup": { "address": "142 Prince St, New York, NY 10012",
"contactPhone": "+12125550100" },
"dropoff": { "address": "200 Park Ave, New York, NY 10166",
"contactPhone": "+12125551234",
"notes": "Leave with front desk" },
"subtotalCents": 4200,
"tipCents": 800
}'Returns 201 Created with an orderId and status. Read it back any time with GET /v1/orders/{externalId}.
Plug into any MCP client
Add the Dragonfly MCP server to Claude Desktop, Claude Code, or your own agent runtime. Your agent gets two tools — create_order and get_order_status — that it can call mid-conversation to move physical goods.
{
"mcpServers": {
"dragonfly-orders": {
"command": "node",
"args": ["tools/dragonfly-orders/src/mcp.mjs"],
"env": { "DRAGONFLY_API_KEY": "dfk_live_xxxxxxxxxxxxxxxx" }
}
}
}Scriptable from the shell
For batch jobs, cron, and pipelines. Set DRAGONFLY_API_KEY, point it at a JSON order file, and you're dispatching — no SDK to wire up.
# one-time: npm i -g dragonfly-orders, set DRAGONFLY_API_KEY
dragonfly-orders create --file order.json
dragonfly-orders status ACME-10025Status callbacks are HMAC-signed so your agent can trust every push. Verify the X-Dragonfly-Signature header against your signing secret before acting on it.
How to get started
- 1
Request access
Tell us what your agent does and the volume you expect. We issue an API key and a signing secret per merchant account.
- 2
Store your credentials
The key (dfk_live_…) and signing secret are shown once. Drop them in your secret manager — your agent reads the key from its environment.
- 3
Wire up the API, CLI, or MCP server
Pick whichever fits your stack. Test against the sandbox host your contact provides, then flip to production.
- 4
Go live
Register a callback URL to receive signed status updates, and your agent is dispatching real deliveries end-to-end.
Building a product, not a one-off bot? See the Partner Portal or explore the Platform APIs.
Ready to give your agent a loading dock?
Self-serve: POST /v1/signup with sandbox:true and you get a working API key in ONE request — simulated dispatch, nothing billed. Production accounts are approved within a business day. Questions about volume, routing, or the MCP server? Talk to our developer team.