---
title: Connect an agent
description: 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](/overview/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:

```http
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

```bash
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:

```json
{
  "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:

```json
{
  "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](/overview/persistence-api#idempotency). 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.