AI Assistant & MCP

Connecting ShipWave to Claude Desktop and Cursor

Use ShipWave as an MCP server so your local AI agent can run shipping operations directly.

What is MCP?

The Model Context Protocol (MCP) is an open standard that lets AI agents talk to external tools. ShipWave ships a full MCP server, so any MCP-compatible client — Claude Desktop, Cursor, Cline, Zed, and others — can use ShipWave's tools the same way Ask ShipWave does. This means you can ask Claude in your editor to "create a return label for order #12345" and it will hit the same audited endpoints.

Install the stdio shim

Most MCP clients today speak stdio, while ShipWave's MCP server runs over HTTP. The @shipwave/mcp-shim package bridges the two. Install it globally with npm install -g @shipwave/mcp-shim, or let your MCP client run it on demand via npx. No build step or Node project required.

Create a scoped API key

Go to Admin → Settings → API Keys and click Create key. Give it a descriptive name (e.g. "Claude Desktop on Eric's laptop") and pick scopes. For a typical agent setup, read:orders, read:shipments, read:inventory, write:labels, and write:returns cover the common operations without granting full write access. See API scopes explained for the full list.

Claude Desktop config

Open Claude Desktop's settings file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS) and add:

{ "mcpServers": { "shipwave": { "command": "npx", "args": ["-y", "@shipwave/mcp-shim"], "env": { "SHIPWAVE_API_KEY": "sw_live_..." } } } }

Restart Claude Desktop. You should see a hammer icon in the chat input indicating MCP tools are loaded. Type "what can ShipWave do?" to see the tool list.

Cursor config

In Cursor, open Settings → Features → MCP → Add new MCP server. Name it shipwave, type command, and paste SHIPWAVE_API_KEY=sw_live_... npx -y @shipwave/mcp-shim. Hit save. Cursor's agent mode can now call ShipWave tools from any chat.

Example prompts

Once connected, try prompts like:
  • "Create a return label for order #12345 using the cheapest USPS rate."
  • "List all orders shipped to California in the last 7 days that are still in-transit."
  • "Void the unused label on shipment SHP-2026-04-1842."
  • "Bulk-update the Amazon listing for SKU LEVY-BATTERY-36V to price $129.99."
The agent will preview any write action before executing it.

FAQs

Does the shim send my API key anywhere besides ShipWave?
No. The shim only forwards requests to https://shipwave.app/api/mcp using the key you set in your environment. It is open source — see github.com/shipwave/mcp-shim.
Can I rotate the key without reinstalling?
Yes. Update the env var in your MCP client config and restart the client. Old keys can be revoked from Admin → Settings → API Keys.
Do MCP calls count against my daily AI budget?
They count against the daily budget of the user who owns the API key. Per-tool rate limits also apply &mdash; see <a href="/help/ai-budget-and-limits">AI budgets and rate limits</a>.
Is there an HTTP MCP endpoint for hosted agents?
Yes. Point any HTTP-capable MCP client (e.g. a Claude.ai custom integration) at https://shipwave.app/api/mcp with a Bearer token. The same scopes apply.

More in AI Assistant & MCP

Back to Help Center