Integrate the DHL API Assistant MCP Server into your AI environment to enable access to DHL shipping, returns, labeling, and tracking capabilities via natural language and structured tool calls.

Introduction

Integrating DHL Post & Parcel Germany APIs can be complex. Different endpoints, authentication methods, and data formats increase implementation effort and slow down delivery.

The DHL API Assistant MCP Server simplifies this by providing a central technical connection between your AI environment and DHL APIs. It exposes DHL capabilities as AI-compatible tools using the Model Context Protocol (MCP) and provides the required integration context directly where you work.

This means AI systems such as IDE assistants, chat agents, and automation tools can support the development and operation of a DHL API integration by helping with:

  • code completion for requests and related integration logic
  • agent-assisted implementation of the API connection
  • troubleshooting and debugging during integration
  • test case creation and evaluation

In agent-capable environments, the MCP Server can be addressed directly from the same workspace where you build, test, and refine your integration.

Supported APIs

The MCP Server currently supports integration with the following APIs:

Tip: To help your AI environment use the MCP Server in the intended API context, it is recommended to mention the relevant DHL API explicitly in your prompt or task description. Example: instead of asking only for "create a shipment request", refer to "DHL Parcel DE Private Shipping" if that is the API you want to work with.

Authentication

Required

All requests to the MCP Server must include a valid API key:

Header Description
dhl-api-key API key for MCP access

The dhl-api-key used for the MCP Server is identical to the API key used for the supported DHL APIs. You receive this key when you create an app in the DHL Developer Portal.

Optional

Additional headers may be required depending on the API you use:

Header Description
dhl-api-secret API authentication (if required)
dhl-username DHL user authentication
dhl-password DHL user password

Only the dhl-api-key is required to establish a connection.
Whether dhl-api-secret, dhl-username, and dhl-password are required depends on the specific API. For details about the authentication required for the DHL Sandbox, refer to the documentation of the respective API listed in the supported APIs section.

Endpoint

Sandbox environment:

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

Important: The MCP Server and the required credentials are valid for the Sandbox environment only. The MCP Server does not provide access to production environments. If you later move from Sandbox to production, this change must be performed manually by the developer. This includes updating the target API URL as well as using the valid credentials for the production environment.

This guide explains how to connect an AI client to the DHL MCP Server in the Sandbox environment. API-specific business flows, endpoint behavior, and any additional authentication outside the MCP Server must be taken from the documentation of the respective supported API. Example: if an API returns a frontend URL such as entryUrl, access requirements for that frontend are not part of the MCP Server authentication.

Integration

The DHL MCP Server can be integrated into different environments.
The following examples show common client-side configurations for the same sandbox endpoint.

VS Code / Cursor / Windsurf

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

Example with all supported headers, if required by the API:

{
  "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"
      }
    }
  }
}

See more detailed instructions for usage of Visual Studio Code here.

Codex (CLI / IDE)

Edit:

~/.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"

OpenAI API (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:
    "Create a shipment label using the Parcel DE Shipping API. Use test data.",
});

Claude Desktop

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

Validation

After configuration:

  • Ensure the MCP Server is reachable
  • Verify that tools are available in your AI environment
  • Test with a simple prompt, for example:
Please check the status for DHL shipment number 003404341234567890

Troubleshooting

MCP Server not available

  • Check if dhl-api-key is set correctly
  • Verify endpoint URL
  • Ensure network access

Tools not visible

  • Authentication may be incomplete
  • Additional headers may be required

Authorization errors (401/403)

  • Invalid API key
  • Missing or incorrect credentials

Security Best Practices

  • Do not store credentials in source code
  • Use environment variables or secret managers
  • Separate sandbox and production credentials

Key Takeaways

  • The DHL MCP Server requires only a valid API key to connect
  • Additional headers are optional and enable extended capabilities
  • The same configuration can be adapted across multiple AI environments

Support

Technical Support & Assistance

For further help, please visit our IT-Portal. There you can open a support ticket and receive direct assistance from DHL Support. To help us resolve your issue quickly, please describe your request in as much detail as possible and include traceable excerpts of your web service communication.

Customer Integration Services (CIS)

Business hours: Monday to Friday, 8 a.m. to 16 p.m.