# Packy Tracking MCP

[![Listed on mcpservers.org](https://mcpservers.org/badge.svg)](https://mcpservers.org/servers/packy-tracking/packy-tracking-mcp)

Packy Tracking MCP connects compatible AI clients to the Packy Tracking API through the Model Context Protocol (MCP).

This repository contains public integration documentation and configuration examples. The MCP implementation itself is a hosted service; no local server installation is required.

The MCP server acts on behalf of the connected Packy account. It does not provide permissions beyond those available to the API key selected during OAuth authorization.

## Endpoint

Production MCP endpoint:

```text
https://mcp.parceltracking.app/mcp
```

## Authentication

OAuth is the recommended authentication method. The client opens the Packy authorization page, where you sign in and select an active API key. After you approve access, the MCP application is connected to that key.

OAuth permissions are checked by the MCP server and are not forwarded to the product API. Product requests are made with the selected account API key.

### Access model

- During OAuth consent, the user selects one active API key belonging to the current Packy account.
- The MCP application is bound to that selected key after **Allow**.
- Several MCP applications can be bound to the same API key; each application has its own OAuth authorization.
- Disconnecting one application revokes only that application's OAuth access and does not deactivate the API key or affect other applications.
- The MCP server validates the OAuth authorization and key status before forwarding an action to the Packy API.

### OAuth with Claude

Before connecting, sign in to <https://lk.parceltracking.app>, create an API key, and make sure it is active.

1. Open Claude Settings → Connectors → Add custom connector.
2. Enter the MCP endpoint:

   ```text
   https://mcp.parceltracking.app/mcp
   ```

3. Keep OAuth authentication enabled and allow Claude to register a client automatically.
4. Sign in to Packy in the browser. A short **Continue authorization** page redirects automatically; there is nothing to click. The link is single-use and expires after two minutes.
5. On **Allow access?**, select the active API key this connection will use and choose **Allow**.
6. Return to Claude and confirm that the connector is connected.

OAuth access tokens are short-lived and refreshed automatically. If the flow fails, start a new connection attempt from Claude instead of reopening the previous authorization URL.

### OAuth with Codex

```bash
codex mcp add packy-tracking-mcp \
  --url https://mcp.parceltracking.app/mcp \
  --oauth-resource https://mcp.parceltracking.app/mcp
```

Open the authorization URL printed by Codex, sign in to Packy, select an active API key, and choose Allow.

### Cursor with an API key

The documented Cursor setup uses an API key. Add the server URL and `Authorization: Bearer <YOUR_API_KEY>` header in Cursor's project or user `mcp.json`, then restart MCP/the agent. See [`examples/cursor/mcp.json`](examples/cursor/mcp.json).

## API-key fallback

Clients that do not support MCP OAuth can use a Packy API key directly. The API key is the same key used with the regular Packy Tracking API.

```json
{
  "mcpServers": {
    "packy-tracking-mcp": {
      "url": "https://mcp.parceltracking.app/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}
```

Replace `<YOUR_API_KEY>` with an active key from the Packy account. Never publish or share the key.

The server also accepts the equivalent header:

```text
X-API-Key: <YOUR_API_KEY>
```

The OAuth flow is recommended because the key is selected in Packy and is not copied into the client configuration.

## Tools

| Tool | Tracking API operation |
| --- | --- |
| `trackings_create` | `POST /v1/trackings` |
| `trackings_list` | `GET /v1/trackings` |
| `trackings_get` | `GET /v1/trackings/{id}` |
| `trackings_delete` | `DELETE /v1/trackings/{id}` |
| `couriers_list` | `GET /v1/couriers` |
| `courier_detections_create` | `POST /v1/courier-detections` |
| `webhooks_list` | `GET /v1/webhooks` |
| `webhooks_create` | `POST /v1/webhooks` |
| `webhooks_update` | `PATCH /v1/webhooks/{id}` |
| `webhooks_delete` | `DELETE /v1/webhooks/{id}` |

Operations that change stored data are `trackings_create`, `trackings_delete`, `webhooks_create`, `webhooks_update`, and `webhooks_delete`. Run them only when you explicitly intend to modify account data.

Only `trackings_create` consumes credits: one credit per unique tracking number, including each tracking number in a batch. Courier, detection, read, delete, and webhook tools do not consume credits. MCP is not billed separately from the Tracking API.

## Disconnect and revocation

To stop one MCP application:

1. Sign in to the Packy account at <https://lk.parceltracking.app>.
2. Open **Connected applications**.
3. Select the application and choose **Disconnect** / **Revoke**.

Revoking an application stops new requests from that OAuth connection. It does not deactivate the API key itself, and other applications connected to the same key remain independent.

You can also deactivate or replace the API key in the **API keys** section. This affects every integration using that key, including MCP applications.

## Verify the service

These public liveness endpoints do not require an API key:

```bash
curl -fsS https://mcp.parceltracking.app/health
curl -fsS https://mcp.parceltracking.app/ready
```

Expected responses:

```json
{"status":"ok"}
```

```json
{"status":"ok","checks":{"api_gateway":"healthy"}}
```

`/ready` also confirms that the MCP service can reach its API gateway.

## Troubleshooting

- If no tools appear, check the endpoint, use the server name `packy-tracking-mcp`, and restart the client.
- If OAuth does not finish, sign in to the intended Packy account, confirm that it has an active API key, and start a new connection attempt.
- If access is denied, verify that the selected key is active and belongs to the intended account.
- If access must be stopped immediately, disconnect the application in **Connected applications** or deactivate the API key.

## Links

- Packy website: <https://packyapp.com>
- Packy account: <https://lk.parceltracking.app>
- MCP endpoint: <https://mcp.parceltracking.app/mcp>

## Support

For account and support requests, email [wasup@clickor.net](mailto:wasup@clickor.net).

For technical questions about the Tracking API and MCP integration, join the
[Packy Developer Community on Discord](https://discord.com/invite/S6W2tdrt6n).
All official contact options are available at <https://packyapp.com/contacts>.

## Repository scope

This repository contains integration documentation only. It does not contain Packy API source code, credentials, API keys, OAuth tokens, or deployment configuration.