DHL API Assistant – MCP-Integration

Zweck

Diese Seite beschreibt, wie der DHL API Assistant MCP-Server in eine KI-gestützte Entwicklungsumgebung eingebunden wird. Die Integration ermöglicht es, unterstützte KI-Tools und IDEs über das Model Context Protocol (MCP) auf DHL-API-spezifische Funktionen zuzugreifen.

Der DHL API Assistant hilft Entwicklern dabei, Beispielanfragen zu erstellen, API-Fehler zu analysieren, erforderliche Felder zu verstehen und DHL-API-Workflows in der Sandbox-Umgebung zu testen. Die Integration unterstützt ausschließlich die Sandbox-Umgebung. Für den Produktivbetrieb ist die offizielle DHL-API-Dokumentation maßgeblich.

Voraussetzungen

• Ein DHL Developer Portal-Konto mit einer konfigurierten App, die Zugriff auf die gewünschte DHL-API hat.
• Ein gültiger DHL-API-Schlüssel für die Sandbox-Umgebung.
• Ein KI-Tool oder eine IDE mit Unterstützung für remote HTTP MCP-Server.

Unterstützte DHL-APIs

Der DHL API Assistant MCP-Server unterstützt derzeit:

• Shipment Tracking – Unified
• Parcel DE Shipping
• Parcel DE Private Shipping
• Parcel DE Returns

Geben Sie in jedem Prompt die gewünschte DHL-API explizit an, damit das KI-Tool den richtigen API-Kontext verwendet.

Empfohlene Reihenfolge

1. DHL Developer Portal-App anlegen oder auswählen und den Zugriff auf die benötigte DHL-API sicherstellen.
2. Den Sandbox-API-Schlüssel kopieren.
3. Den MCP-Server im gewählten KI-Tool konfigurieren.
4. Alle erforderlichen Authentifizierungsheader ergänzen.
5. Das KI-Tool neu starten oder neu laden.
6. Prüfen, ob die DHL API Assistant-Tools verfügbar sind.
7. Die Einrichtung mit einem einfachen Sandbox-Prompt testen.
8. Generierte Anfragen gegen die offizielle DHL-API-Dokumentation validieren.

Einrichtungsbausteine

Sandbox-Endpunkt

Der DHL API Assistant MCP-Server ist ausschließlich für die Sandbox-Umgebung verfügbar:

https://api-sandbox.dhl.com/development/mcp/v1/

Die Produktivumgebung wird über diesen MCP-Server nicht erreicht. Beim Wechsel in die Produktion müssen alle umgebungsspezifischen Einstellungen manuell angepasst werden – darunter URLs, Zugangsdaten, Authentifizierungsanforderungen, Fehlerbehandlung, Ratenbegrenzungen sowie Anforderungen an Protokollierung und Datenschutz.

Authentifizierungsheader

Jede Verbindung erfordert einen gültigen DHL-API-Schlüssel:

dhl-api-key: YOUR_API_KEY

Je nach gewählter DHL-API können weitere Zugangsdaten erforderlich sein:

dhl-api-secret: YOUR_API_SECRET
dhl-username: YOUR_USERNAME
dhl-password: YOUR_PASSWORD

Der API-Schlüssel und alle weiteren Zugangsdaten werden über das DHL Developer Portal verwaltet. Stellen Sie sicher, dass die konfigurierte App Zugriff auf die gewünschte DHL-API hat.

Zugangsdaten sicher verwalten

DHL-Zugangsdaten dürfen niemals in echten Werten in Repositories, Wiki-Seiten, Pull Requests, Screenshots oder Konfigurationsdateien hinterlegt werden.

Verwenden Sie sichere Speicherorte:

• Lokale Umgebungsvariablen
• Lokale Konfigurationsdateien, die per .gitignore ausgeschlossen sind
• Azure DevOps Secret-Variablen oder Library Variable Groups
• Azure Key Vault oder einen unternehmensinternen Secrets Manager

Verwenden Sie in Dokumentation und Beispieldateien ausschließlich Platzhalter wie YOUR_API_KEY, YOUR_API_SECRET, YOUR_USERNAME und YOUR_PASSWORD.

MCP-Konfiguration: VS Code, Cursor und Windsurf

Minimales Beispiel:

{
  "servers": {
    "DHL API Assistant": {
      "url": "https://api-sandbox.dhl.com/development/mcp/v1/",
      "headers": {
        "dhl-api-key": "YOUR_API_KEY"
      }
    }
  }
}

Beispiel mit zusätzlichen Authentifizierungsheadern:

{
  "servers": {
    "DHL API Assistant": {
      "url": "https://api-sandbox.dhl.com/development/mcp/v1/",
      "headers": {
        "dhl-api-key": "YOUR_API_KEY",
        "dhl-api-secret": "YOUR_API_SECRET",
        "dhl-username": "YOUR_USERNAME",
        "dhl-password": "YOUR_PASSWORD"
      }
    }
  }
}

MCP-Konfiguration: Codex CLI

Für Codex-basierte Umgebungen ergänzen Sie die MCP-Server-Konfiguration in ~/.codex/config.toml:

[mcp_servers.dhl_api_assistant]
url = "https://api-sandbox.dhl.com/development/mcp/v1/"

[mcp_servers.dhl_api_assistant.http_headers]
dhl-api-key = "YOUR_API_KEY"

Wenn die gewählte DHL-API weitere Zugangsdaten erfordert, ergänzen Sie diese im Abschnitt http_headers.

MCP-Konfiguration: OpenAI Responses API

const response = await client.responses.create({
  model: "gpt-4.1",
  tools: [
    {
      type: "mcp",
      server_url: "https://api-sandbox.dhl.com/development/mcp/v1/",
      headers: {
        "dhl-api-key": "YOUR_API_KEY"
      }
    }
  ],
  input: "Using the DHL Parcel DE Shipping API in the sandbox environment, create a shipment label request with test data."
});

MCP-Konfiguration: Claude Desktop

{
  "mcpServers": {
    "dhl-api-assistant": {
      "url": "https://api-sandbox.dhl.com/development/mcp/v1/",
      "headers": {
        "dhl-api-key": "YOUR_API_KEY"
      }
    }
  }
}

MCP-Konfiguration: Claude Code

Minimales Setup:

claude mcp add --transport http dhl-api-assistant https://api-sandbox.dhl.com/development/mcp/v1/ --header "dhl-api-key: YOUR_API_KEY"

Mit zusätzlichen Authentifizierungsheadern:

claude mcp add --transport http dhl-api-assistant https://api-sandbox.dhl.com/development/mcp/v1/ \
  --header "dhl-api-key: YOUR_API_KEY" \
  --header "dhl-api-secret: YOUR_API_SECRET" \
  --header "dhl-username: YOUR_USERNAME" \
  --header "dhl-password: YOUR_PASSWORD"

Nach der Konfiguration prüfen Sie, ob der MCP-Server verfügbar ist:

/mcp

Validierung

Nach der Einrichtung empfohlene Prüfschritte:

• Endpunkt-URL ist korrekt konfiguriert.
• dhl-api-key ist gültig.
• Zusätzliche Zugangsdaten sind vorhanden, sofern von der gewählten DHL-API verlangt.
• Das KI-Tool zeigt die DHL API Assistant-Tools an.
• Ein einfacher Sandbox-Prompt kann erfolgreich ausgeführt werden.

Validierungsbeispiel:

Using the DHL Shipment Tracking - Unified API in the sandbox environment, explain how to check the status of a shipment and provide an example request.

Empfehlungen für Prompts

Prompts sollten stets den Namen der DHL-API, die Umgebung, die gewünschte Operation und das erwartete Ergebnis enthalten.

Gutes Beispiel:

Using the DHL Parcel DE Shipping API in the sandbox environment, create a sample shipment label request with test data. Return the request payload and explain the required authentication headers.

Debugging-Beispiel:

Using the DHL Parcel DE Shipping API in the sandbox environment, help me debug this shipment request. Explain possible validation errors and suggest a corrected payload.

Testfall-Beispiel:

Using the DHL Parcel DE Returns API in the sandbox environment, generate test cases for successful return label creation, missing required fields, invalid credentials, and invalid recipient data.

Fehlerbehebung

MCP-Server ist nicht verfügbar

Mögliche Ursachen:

• Fehlender oder ungültiger dhl-api-key
• Falsche MCP-Endpunkt-URL
• Netzwerk-, Proxy- oder Firewall-Einschränkungen
• KI-Tool unterstützt keine remote HTTP MCP-Server
• Konfigurationsdatei liegt am falschen Speicherort

Empfohlene Prüfschritte:

1. Endpunkt-URL prüfen.
2. API-Schlüssel bestätigen.
3. Prüfen, ob die lokale Umgebung https://api-sandbox.dhl.com erreichen kann.
4. JSON- oder TOML-Konfigurationssyntax validieren.
5. Das KI-Tool nach der Konfigurationsänderung neu starten.

DHL-Tools sind nicht sichtbar

Mögliche Ursachen:

• Der KI-Client wurde nach der Konfigurationsänderung nicht neu gestartet.
• Authentifizierungsheader sind unvollständig.
• Der konfigurierte Transport wird vom gewählten Tool nicht unterstützt.
• Der MCP-Server konnte nicht initialisiert werden.

Empfohlene Prüfschritte:

1. KI-Client neu starten.
2. MCP-Status-Ansicht oder -Befehl öffnen, sofern verfügbar.
3. Speicherort der Konfigurationsdatei prüfen.
4. Prüfen, ob die gewählte DHL-API zusätzliche Zugangsdaten erfordert.

Autorisierungsfehler 401 / 403

Mögliche Ursachen:

• Ungültiger oder fehlender API-Schlüssel
• Fehlender API-Secret
• Falscher Benutzername oder falsches Passwort
• Zugangsdaten stimmen nicht mit der gewählten DHL-API überein
• Die DHL Developer Portal-App hat keinen Zugriff auf die erforderliche API

Empfohlene Prüfschritte:

1. DHL Developer Portal-App prüfen.
2. Sicherstellen, dass die App Zugriff auf die gewünschte DHL-API hat.
3. Prüfen, ob Sandbox-Zugangsdaten verwendet werden.
4. Zugangsdaten bei Bedarf neu generieren.
5. API-spezifische Authentifizierungsanforderungen in der offiziellen DHL-Dokumentation prüfen.

Weiterführende Informationen

• Offizielle Seite im DHL Developer Portal: DHL API Assistant – Manual MCP Integration Guide
• Carrierspezifische DHL-Shipping-Einrichtung in Shipping Labels: DHL Shipping