Quickstart

Connect an AI assistant to Shipwell in under 10 minutes.

Prerequisites

A Shipwell API token — obtain it from Settings → API Management in the Shipwell app
Node.js 18+ (required for Claude Desktop and Cursor setups that use mcp-remote )

Read-only by default

The MCP server starts in read-only mode. Your AI assistant can query all data the token's user has access to, but cannot create or modify anything until write access is explicitly enabled on your account. See Safety & Write Access.

For production setups, use a dedicated integration user's token rather than a personal token — see Best Practices.

Connection Modes

HTTPS (Recommended)

The hosted MCP server runs over HTTPS. Authentication is stateless — your Shipwell API token is passed in the Authorization header on each request and is never stored server-side. Use this for shared or remote deployments.

Stdio (Local process)

Run the MCP server as a local process with your token set as an environment variable. Best for individual developer setups or air-gapped environments.

Setup — Claude Desktop

Obtain your Shipwell API token from Settings → API Management
Open your Claude Desktop config file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Add the following block inside "mcpServers" :

Copy

Copied

{
  "mcpServers": {
    "shipwell": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.shipwell.com/mcp",
        "--header",
        "Authorization: Bearer YOUR_SHIPWELL_API_TOKEN"
      ]
    }
  }
}

Replace YOUR_SHIPWELL_API_TOKEN with your token
Restart Claude Desktop

Setup — Cursor

Open Cursor Settings → MCP
Add a new MCP server with:
- Type: http
- URL: https://mcp.shipwell.com/mcp
- Authorization header: Bearer YOUR_SHIPWELL_API_TOKEN
Save and reload

Setup — Claude Code (CLI)

Copy

Copied

claude mcp add shipwell \
  --transport http \
  --url https://mcp.shipwell.com/mcp \
  --header "Authorization: Bearer YOUR_SHIPWELL_API_TOKEN"

Verifying the Connection

Once connected, ask your AI assistant:

"List my active shipments in Shipwell"

The agent will auto-discover all 90+ tools via MCP tool discovery — no API docs required.

Note

To use the sandbox environment, replace mcp.shipwell.com with sandbox-mcp.shipwell.com in any of the configs above.

Next Steps

Tool Reference — full list of available tools by domain
Safety & Write Access — the server is read-only by default; learn how to enable write tools
Use Cases — example workflows to try with your AI client