Skip to content
Cargo Marshal
Esc
↑↓navigate↵open⌘Jpreview
On this page

Connect an agent

Let an AI agent search Projects, import Cargo Lines, calculate Load Plans, and share the result through the Cargo Marshal MCP server.

The Cargo Marshal MCP server lets an AI agent in Claude Code, Cursor, or VS Code do what the persistence API does: find a Project, import Cargo Lines, calculate a Load Plan, and mint a Share Link. It runs on the same organization API keys and the same limits as the REST API. This page covers the product server. To search these docs from an agent, use the documentation server at https://docs.cargomarshal.com/mcp.

Before you begin

  • The organization must be on the Enterprise plan. Other plans receive an error.
  • An owner or admin creates a key under Settings → API keys. The secret starts with sc_live_ and is shown once.
  • Choose the scope by what the agent may do. Read only allows the read tools. Read & write also allows the tools that create or change data.

Every call acts on your real organization. There are no test keys, so try a new agent on a throwaway Project.

Endpoint

The server speaks stateless Streamable HTTP at https://www.cargomarshal.com/mcp. Send the key on every request:

Authorization: Bearer sc_live_…

A missing, revoked, or expired key answers 401. OAuth sign-in is not available yet, so the client must send the key as a header.

Add the server to your client

Claude Code

claude mcp add --transport http cargo-marshal https://www.cargomarshal.com/mcp \
  --header "Authorization: Bearer sc_live_…"

Run claude mcp list to check that the server connects. Add --scope user to use it in every project. With --scope project the entry is written to .mcp.json, which you share through source control, so do not put the key in it. Pass --header 'Authorization: Bearer ${CARGO_MARSHAL_API_KEY}' in single quotes instead, and Claude Code reads the key from that environment variable when it starts.

Cursor

Add the server to ~/.cursor/mcp.json, or to .cursor/mcp.json in a project you keep out of source control:

{
  "mcpServers": {
    "cargo-marshal": {
      "url": "https://www.cargomarshal.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:CARGO_MARSHAL_API_KEY}"
      }
    }
  }
}

Export CARGO_MARSHAL_API_KEY before you start Cursor, then restart Cursor.

VS Code

Add the server to .vscode/mcp.json. VS Code asks for the key once and keeps it out of the file:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "cargo-marshal-key",
      "description": "Cargo Marshal API key",
      "password": true
    }
  ],
  "servers": {
    "cargo-marshal": {
      "type": "http",
      "url": "https://www.cargomarshal.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:cargo-marshal-key}"
      }
    }
  }
}

Tools

Tool Scope Does
search_projects Read Finds Projects by name, customer, reference, destination, or Cargo Line name
get_project Read Reads a Project and a header per Load Plan
list_cargo_lines Read Pages through a Project’s Cargo Lines
get_load_plan Read Summarizes a calculated Load Plan
get_calculate_status Read Reads a calculate run
list_equipment Read Lists Equipment Types, built-in Sea and Road included
search_cargo_library Read Searches the Cargo Library
create_project Read & write Creates a Project
import_cargo_lines Read & write Appends Cargo Lines to a Project in one transaction
create_load_plan Read & write Creates a Load Plan on a Project
set_load_plan_equipment Read & write Sets the Equipment Types a Load Plan loads onto
calculate_load_plan Read & write Calculates a Load Plan and replaces the previous result
create_share_link Read & write Mints a view-only Share Link

A read-only key that calls a write tool gets an error before anything changes. Dimensions are in millimetres and weights in grams, as in the REST API. get_load_plan returns a summary per Unit, not the placement of every piece. Read the stored placements through the REST API.

Calculate and wait

calculate_load_plan waits up to about 20 seconds. If the calculate finishes, the tool returns the same summary as get_load_plan. If it is still running, the tool returns a calculate id. Call get_calculate_status with it until the status is completed, then call get_load_plan.

Send expected_revision from get_load_plan or create_load_plan with every change to a Load Plan. A stale revision is rejected, so the agent cannot overwrite work from another person.

Retries and idempotency

Every tool that creates data, and calculate_load_plan, takes an optional idempotency_key. Pass the same idempotency_key on a retry so the call does not run twice, for example so import_cargo_lines does not append the lines again. The rules match the REST API. A replayed create_share_link returns the link with url set to null, because the secret is shown once. Call it again with a new idempotency_key to mint a fresh link.

The server shares the REST API’s rate limits. After a 429, wait the Retry-After seconds before you retry.

Revoke access

Rotate or revoke the key under Settings → API keys. The agent loses access at once.

Was this page helpful?