Agent verbinden

Lassen Sie einen KI-Agenten über den Cargo-Marshal-MCP-Server Projects suchen, Frachtzeilen importieren, Ladepläne berechnen und das Ergebnis freigeben.

Der Cargo-Marshal-MCP-Server lässt einen KI-Agenten in Claude Code, Cursor oder VS Code tun, was die Persistenz-API tut: ein Project finden, Frachtzeilen importieren, einen Ladeplan berechnen und einen Freigabelink erzeugen. Er nutzt dieselben API-Schlüssel der Organisation und dieselben Limits wie die REST-API. Diese Seite behandelt den Produkt-Server. Um diese Dokumentation aus einem Agenten zu durchsuchen, nutzen Sie den Dokumentations-Server unter https://docs.cargomarshal.com/mcp.

Bevor Sie beginnen

• Die Organisation braucht den Enterprise-Plan. Andere Pläne erhalten einen Fehler.
• Ein Owner oder Admin erstellt einen Schlüssel unter Einstellungen → API-Schlüssel. Das Geheimnis beginnt mit sc_live_ und wird nur einmal angezeigt.
• Wählen Sie den Umfang danach, was der Agent darf. Nur lesen erlaubt die lesenden Tools. Lesen und schreiben erlaubt auch die Tools, die Daten anlegen oder ändern.

Jeder Aufruf wirkt auf Ihre echte Organisation. Testschlüssel gibt es nicht, probieren Sie einen neuen Agenten deshalb an einem Wegwerf-Project aus.

Endpunkt

Der Server spricht zustandsloses Streamable HTTP unter https://www.cargomarshal.com/mcp. Senden Sie den Schlüssel bei jeder Anfrage:

Authorization: Bearer sc_live_…

Ein fehlender, widerrufener oder abgelaufener Schlüssel antwortet mit 401. Die Anmeldung per OAuth gibt es noch nicht, der Client muss den Schlüssel also als Header senden.

Server zum Client hinzufügen

Claude Code

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

Prüfen Sie mit claude mcp list, ob der Server verbindet. Mit --scope user gilt er in jedem Projekt. Mit --scope project landet der Eintrag in .mcp.json, die Sie über die Versionskontrolle teilen. Schreiben Sie den Schlüssel deshalb nicht hinein, sondern übergeben Sie --header 'Authorization: Bearer ${CARGO_MARSHAL_API_KEY}' in einfachen Anführungszeichen. Claude Code liest den Schlüssel dann beim Start aus dieser Umgebungsvariable.

Cursor

Tragen Sie den Server in ~/.cursor/mcp.json ein, oder in .cursor/mcp.json eines Projekts, das nicht in der Versionskontrolle liegt:

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

Setzen Sie CARGO_MARSHAL_API_KEY vor dem Start von Cursor und starten Sie Cursor neu.

VS Code

Tragen Sie den Server in .vscode/mcp.json ein. VS Code fragt den Schlüssel einmal ab und hält ihn aus der Datei heraus:

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

Tools

Ein Schlüssel mit dem Umfang „Nur lesen“ erhält beim Aufruf eines schreibenden Tools einen Fehler, bevor sich etwas ändert. Maße sind in Millimetern und Gewichte in Gramm, wie in der REST-API. get_load_plan liefert eine Zusammenfassung pro Ladeeinheit, nicht die Platzierung jedes einzelnen Stücks. Die gespeicherten Platzierungen lesen Sie über die REST-API.

Berechnen und warten

calculate_load_plan wartet bis zu etwa 20 Sekunden. Ist die Berechnung fertig, liefert das Tool dieselbe Zusammenfassung wie get_load_plan. Läuft sie noch, liefert das Tool eine Berechnungs-ID. Rufen Sie damit get_calculate_status auf, bis der Status completed ist, und danach get_load_plan.

Senden Sie bei jeder Änderung an einem Ladeplan expected_revision aus get_load_plan oder create_load_plan mit. Eine veraltete Revision wird abgelehnt, der Agent überschreibt also keine Arbeit anderer.

Wiederholungen und Idempotenz

Jedes Tool, das Daten anlegt, und calculate_load_plan nehmen einen optionalen idempotency_key. Übergeben Sie bei einer Wiederholung denselben idempotency_key, damit der Aufruf nicht doppelt läuft, zum Beispiel damit import_cargo_lines die Zeilen nicht noch einmal anhängt. Die Regeln entsprechen der REST-API. Ein wiederholtes create_share_link liefert den Link mit url gleich null, weil das Geheimnis nur einmal angezeigt wird. Rufen Sie es mit einem neuen idempotency_key erneut auf, um einen frischen Link zu erzeugen.

Der Server teilt sich die Ratenlimits mit der REST-API. Warten Sie nach einem 429 die Sekunden aus Retry-After, bevor Sie es erneut versuchen.

Zugriff widerrufen

Rotieren oder widerrufen Sie den Schlüssel unter Einstellungen → API-Schlüssel. Der Agent verliert den Zugriff sofort.