--- title: Agent verbinden description: 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](/de/overview/persistence-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: ```http 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 ```bash 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: ```json { "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: ```json { "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 | Tool | Umfang | Aufgabe | | ------------------------- | ------------------- | ---------------------------------------------------------------------------- | | `search_projects` | Lesen | Findet Projects nach Name, Kunde, Referenz, Ziel oder Name einer Frachtzeile | | `get_project` | Lesen | Liest ein Project mit einem Kopf pro Ladeplan | | `list_cargo_lines` | Lesen | Blättert durch die Frachtzeilen eines Projects | | `get_load_plan` | Lesen | Fasst einen berechneten Ladeplan zusammen | | `get_calculate_status` | Lesen | Liest einen Berechnungslauf | | `list_equipment` | Lesen | Listet Laderaumtypen, einschließlich der eingebauten Sea- und Road-Typen | | `search_cargo_library` | Lesen | Durchsucht die Ladungsbibliothek | | `create_project` | Lesen und schreiben | Legt ein Project an | | `import_cargo_lines` | Lesen und schreiben | Hängt Frachtzeilen in einer Transaktion an ein Project an | | `create_load_plan` | Lesen und schreiben | Legt einen Ladeplan in einem Project an | | `set_load_plan_equipment` | Lesen und schreiben | Setzt die Laderaumtypen, auf die ein Ladeplan lädt | | `calculate_load_plan` | Lesen und schreiben | Berechnet einen Ladeplan und ersetzt das vorherige Ergebnis | | `create_share_link` | Lesen und schreiben | Erzeugt einen Freigabelink nur zum Ansehen | 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](/de/overview/persistence-api#idempotenz). 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.