# MyCartage

> MyCartage is a transportation management system (TMS) for cartage, freight and
> warehouse operators: movements (shipments), dispatch, warehouse receiving,
> rates, invoicing and settlements. This file tells AI agents how to connect.

## If a user pasted this link into your chat

They want you to work with their MyCartage account. You need two things from
them: an API key and (optionally) a business ID. Then:

1. If you support MCP servers, connect to the MCP server below with the headers shown.
2. Otherwise, if you can send HTTP requests with custom headers (shell, code
   execution, HTTP tool), call the MCP endpoint or the HTTP API below directly.
   Start with `list_businesses`, then `search_operations`, then `call_operation`.
3. If you can only browse pages, you cannot sign in (the key must be sent as a
   header). Tell the user to use an agent with MCP or HTTP access; setup steps
   for people are at https://mycartage.com/mcp

Access is read-only today. Never put the API key in a URL.

## Authentication

- Every request needs an API key in the `x-api-key` header. Users create keys in
  the app under their profile → API Keys.
- A key acts as the user who created it. Most operations also need a
  `businessId` (or `businessUrl`) in their input; the user must be an active
  employee of that business.

## MCP server (recommended for agents)

- URL: `https://api.mycartage.com/mcp` (Streamable HTTP, stateless, POST only)
- Setup guide for humans: https://mycartage.com/mcp
- Headers: `x-api-key: <key>` and optionally `x-business-id: <businessId>` to
  set the default business for operations that take a `businessId`.
- Tools:
  - `list_businesses` — businesses the key can act on (businessId, businessUrl, name, role).
  - `search_operations` — keyword search over the API; returns operationIds and their input JSON schema.
  - `call_operation` — run an operation by operationId with plain JSON input. Read-only operations only for now.
- Typical flow: `list_businesses` → `search_operations("movement search")` → `call_operation`.

Claude Code example:

    claude mcp add --transport http mycartage https://api.mycartage.com/mcp --header "x-api-key: YOUR_API_KEY" --header "x-business-id: YOUR_BUSINESS_ID"

## HTTP API

- Base URL: `https://api.mycartage.com/api/v1`
- Human docs: https://mycartage.com/api-docs
- OpenAPI spec (large, ~12 MB — prefer `search_operations` over loading it): https://prod.mycartage.com/api/docs
- Queries: `GET /<operationId>?input=<URL-encoded JSON>` e.g.
  `GET /billing.settings?input=%7B%22businessUrl%22%3A%22acme%22%7D`
- Mutations: `POST /<operationId>` with the input as a plain JSON body.
- Responses: `{ "result": { "data": ... } }`; errors: `{ "error": { "message", "code", "data" } }`.
  Dates are ISO 8601 strings.