DHL API Assistant – MCP Integration

Integrating the DHL API Assistant MCP Server into AI-enabled development environments for DHL API development.

Purpose

This page describes how to integrate the DHL API Assistant MCP Server into an AI-enabled development environment. The integration allows supported AI tools and IDEs to access DHL API-specific capabilities through the Model Context Protocol (MCP).

The DHL API Assistant helps developers create request examples, analyze API errors, understand required fields, and test DHL API workflows in the sandbox environment. The integration is limited to the sandbox environment. For production use, the official DHL API documentation is authoritative.

Prerequisites

A DHL Developer Portal account with a configured app that has access to the required DHL API.
A valid DHL API key for the sandbox environment.
An AI tool or IDE that supports remote HTTP MCP servers.

Supported DHL APIs

The DHL API Assistant MCP Server currently supports:

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

Always mention the specific DHL API in each prompt so that the AI tool selects the correct API context.

Recommended Sequence

Create or select an app in the DHL Developer Portal and make sure it has access to the required DHL API.
Copy the sandbox API key.
Configure the MCP Server in the selected AI tool.
Add all required authentication headers.
Restart or reload the AI tool.
Verify that the DHL API Assistant tools are available.
Test the setup with a simple sandbox prompt.
Validate generated requests against the official DHL API documentation.

Setup Components

Sandbox Endpoint

The DHL API Assistant MCP Server is available for the sandbox environment only:

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

Production environments are not accessed through this MCP Server. When moving from sandbox to production, all environment-specific settings must be adjusted manually – including URLs, credentials, authentication requirements, error handling, rate limits, and logging and data protection requirements.

Authentication Headers

Every connection requires a valid DHL API key:

dhl-api-key: YOUR_API_KEY

Depending on the selected DHL API, additional credentials may be required:

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

The API key and any additional credentials are managed through the DHL Developer Portal. Make sure the configured app has access to the required DHL API.

Credential Security

DHL credentials must never be committed to source control or documented with real values in repositories, wiki pages, pull requests, screenshots, or configuration files.

Use secure storage instead:

Local environment variables
Local configuration files excluded via .gitignore
Azure DevOps secret variables or Library variable groups
Azure Key Vault or a company-approved secrets manager

Use placeholders in documentation and example files: YOUR_API_KEY, YOUR_API_SECRET, YOUR_USERNAME, and YOUR_PASSWORD.

MCP Configuration: VS Code, Cursor, and Windsurf

Minimal example:

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

Example with additional authentication headers:

{
  "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 Configuration: Codex CLI

For Codex-based environments, add the MCP server configuration to ~/.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"

If the selected DHL API requires additional credentials, add them to the http_headers section.

MCP Configuration: 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 Configuration: Claude Desktop

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

MCP Configuration: Claude Code

Minimal setup:

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

With additional authentication headers:

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"

After configuration, run the following command in Claude Code to verify that the MCP server is available:

/mcp

Validation

After setup is complete, run the following checks:

The endpoint URL is configured correctly.
The dhl-api-key is valid.
Additional credentials are provided where required by the selected DHL API.
The AI tool shows the DHL API Assistant tools.
A simple sandbox prompt can be executed successfully.

Validation prompt example:

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.

Prompting Recommendations

Prompts should always include the DHL API name, the environment, the requested operation, and the expected output.

Good example:

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 example:

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.

Test case example:

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.

Troubleshooting

MCP Server Is Not Available

Possible causes:

Missing or invalid dhl-api-key
Incorrect MCP endpoint URL
Network, proxy, or firewall restrictions
The AI tool does not support remote HTTP MCP servers
The configuration file is placed in the wrong location

Recommended checks:

Verify the endpoint URL.
Confirm that the API key is correct.
Check whether the local environment can reach https://api-sandbox.dhl.com.
Validate the JSON or TOML configuration syntax.
Restart the AI tool after changing the MCP configuration.

DHL Tools Are Not Visible

Possible causes:

The AI client was not restarted after the configuration change.
Authentication headers are incomplete.
The configured transport is not supported by the selected tool.
The MCP server failed to initialize.

Recommended checks:

Restart the AI client.
Open the MCP status view or command if available.
Confirm that the configuration file is located correctly.
Check whether the selected DHL API requires additional credentials.

Authorization Errors: 401 / 403

Possible causes:

Invalid or missing API key
Missing API secret
Incorrect username or password
Credentials do not match the selected DHL API
The DHL Developer Portal app does not have access to the required API

Recommended checks:

Verify the DHL Developer Portal app.
Confirm that the app has access to the required DHL API.
Check whether sandbox credentials are being used.
Regenerate credentials if necessary.
Review API-specific authentication requirements in the official DHL documentation.

Further Information

Official page on the DHL Developer Portal: DHL API Assistant – Manual MCP Integration Guide
Carrier-specific DHL Shipping setup in Shipping Labels: DHL Shipping