Deftship MCP Server

A Model Context Protocol server for the Deftship multi-carrier shipping API. It lets any MCP-capable AI client (Claude Desktop, Claude Code, Cursor, Codex CLI, and others) quote, ship, track, void and manage shipments in natural language using your Deftship API token.

What it can do

The full shipping lifecycle is exposed as tools:

Domain	Tools
Parcel	get rates, create draft, ship, void, get/track, merge labels, mark as shipped, list e-commerce orders
Freight	get rates, create draft, ship, void, get/track
Pickup	get rates, create, arrange, void, get
Insurance	get rate, book, void
Batch (beta)	create, add items, remove items, get, ship
Account	check balance, address book, validate address, service names, carrier status, create ticket

A typical flow: deftship_get_parcel_rates → choose a rate_id → deftship_ship_parcel → deftship_get_parcel to fetch the label and track it.

Safety guardrails

Because an AI agent can drive this end to end, spending is deliberately hard to do by accident:

• Sandbox by default. With DEFTSHIP_ENV=sandbox (the default) every operation runs against the isolated sandbox with a $10,000 dummy balance and never touches production. Going live is a deliberate one-line change.
• Explicit confirmation. Every tool that spends your balance or is irreversible (ship, void, book_insurance, arrange_pickup, ship_batch) refuses to run unless called with "confirm": true, forcing the agent to surface the action to you first.
• Honest tool hints. Read-only tools are marked readOnlyHint; spending tools are marked destructiveHint, so clients can prompt for approval.

Setup

1. Get an API token

Generate a sandbox token from your Deftship organisation's API page. Use sandbox while you test; switch to a production token only when you are ready to spend real money.

2. Configure your MCP client

Claude Desktop / Claude Code (claude_desktop_config.json or .mcp.json):

{
  "mcpServers": {
    "deftship": {
      "command": "npx",
      "args": ["-y", "deftship-mcp"],
      "env": {
        "DEFTSHIP_API_TOKEN": "bearer-your-token-here",
        "DEFTSHIP_ENV": "sandbox"
      }
    }
  }
}

Codex CLI (~/.codex/config.toml):

[mcp_servers.deftship]
command = "npx"
args = ["-y", "deftship-mcp"]
env = { DEFTSHIP_API_TOKEN = "bearer-your-token-here", DEFTSHIP_ENV = "sandbox" }

Cursor (.cursor/mcp.json): same shape as the Claude example above.

Environment variables

Variable	Required	Default	Description
DEFTSHIP_API_TOKEN	yes	—	Your Deftship API token.
DEFTSHIP_ENV	no	sandbox	sandbox or production. Determines the base URL.
DEFTSHIP_BASE_URL	no	derived	Override the API base URL entirely (takes precedence over DEFTSHIP_ENV).

Local development

npm install
npm run build      # compile TypeScript to dist/
npm run dev        # watch mode
DEFTSHIP_API_TOKEN=bearer-... npm start

The server speaks MCP over stdio. Do not write anything to stdout in tool code — stdout carries the JSON-RPC stream; diagnostics go to stderr.

Project structure

src/
  config.ts        env parsing, sandbox/production base URL resolution
  http.ts          fetch wrapper: auth, error + rate-limit normalization
  schemas.ts       shared Zod schemas (address, package, item, ...)
  server.ts        assembles the server and registers all tool modules
  index.ts         stdio entry point
  tools/
    helpers.ts     registration wrapper, confirm gate, result formatting
    parcel.ts freight.ts pickup.ts insurance.ts batch.ts account.ts

Tool schemas mirror the field tables in the official Deftship developer docs.

License

MIT