# dzship MCP server: ship parcels in Algeria from your AI assistant

> Index of every page: https://freeship.dzbuild.com/llms.txt

Source: https://freeship.dzbuild.com/docs/mcp

dzship has an MCP endpoint next to its HTTP API. An assistant that connects to it can find a
courier, check an address, create a parcel, track it, quote its fee and cancel it. The tools run
the same routes as the API, so the rules, the errors and the limits are the same.

```text
https://freeship.dzbuild.com/mcp
```

It speaks Streamable HTTP, needs no login and keeps no session.

## Connect

### Claude Code

```bash
claude mcp add --transport http dzship https://freeship.dzbuild.com/mcp
```

### Cursor

```json title=".cursor/mcp.json"
{
  "mcpServers": {
    "dzship": { "url": "https://freeship.dzbuild.com/mcp" }
  }
}
```

### VS Code

```json title=".vscode/mcp.json"
{
  "servers": {
    "dzship": { "type": "http", "url": "https://freeship.dzbuild.com/mcp" }
  }
}
```

Any other client that speaks Streamable HTTP takes the same URL.

## Try it with no account

The `sandbox` courier needs no credentials. It checks a parcel the way a real courier does and
creates nothing. Ask your assistant:

> Create a sandbox parcel with dzship for Amine Bouzid, 0551234567, Bab Ezzouar in wilaya 16,
> home delivery, 4,500 DZD cash on delivery. Then track it.

## Tools

| Tool | What it does |
|---|---|
| `list_couriers` | Finds a courier: its key, the credentials it needs and what it supports |
| `list_wilayas` | The 58 wilayas couriers deliver to, or the 69 of the 2026 division |
| `list_communes` | Communes in the spelling couriers accept, by wilaya or by name |
| `create_parcel` | Creates a parcel on your courier account |
| `track_parcel` | Status and event history of a parcel |
| `get_rates` | Delivery and return fees for a route |
| `list_stop_desks` | The stop desks a courier runs in one wilaya |
| `cancel_parcel` | Cancels a parcel the courier has not collected |

Each tool takes the body of the matching endpoint in the [API reference](https://freeship.dzbuild.com/docs/api.md). A waybill is
a PDF, which is no use inside a conversation, so labels stay on the HTTP API:
[`POST /v1/label`](https://freeship.dzbuild.com/docs/api/shipping/label.md).

## Courier credentials

A real courier call needs the credentials of your own account at that courier. `list_couriers`
names the fields. There are two ways to send them.

**In the connection, so the assistant never sees them.** Send an `X-Courier-Credentials` header
with a JSON object keyed by courier key. Keep the value in an environment variable:

```bash
export DZSHIP_CREDENTIALS='{"yalidine":{"apiId":"YOUR_ID","apiToken":"YOUR_TOKEN"}}'

claude mcp add --transport http dzship https://freeship.dzbuild.com/mcp \
  --header "X-Courier-Credentials: $DZSHIP_CREDENTIALS"
```

```json title=".cursor/mcp.json"
{
  "mcpServers": {
    "dzship": {
      "url": "https://freeship.dzbuild.com/mcp",
      "headers": { "X-Courier-Credentials": "${env:DZSHIP_CREDENTIALS}" }
    }
  }
}
```

A tool call that carries no `credentials` then uses the entry for its courier. dzship uses them
for that one call to the courier and never stores them.

**In the call.** Every shipping tool also accepts a `credentials` argument. That puts the secret
in the conversation, so use it only with a client that cannot send headers.

> **A real parcel is a real parcel**
> `create_parcel` and `cancel_parcel` act on your courier account. The server tells the assistant
> to ask you first. Read the call before you approve it.

## Limits and errors

- The limits are those of the API, counted per IP address: 200 parcels an hour, 60 tracking calls
  a minute. The [endpoints guide](https://freeship.dzbuild.com/docs/endpoints.md) lists them all.
- An API error comes back as a tool error with the API's own body, for example
  `CONFIGURATION_ERROR` with the credential fields that are missing.
- A result above 64 KB is refused, so the full commune list does not flood the conversation. Pass
  `wilaya` or `q` to `list_communes`.

The server is listed in the official MCP registry as `com.dzbuild/dzship`. Its server card, for
clients that read one, is at [`/mcp/server-card`](https://freeship.dzbuild.com/mcp/server-card).