# Transcend — Freight & Mobility API for AI Agents

> Transcend (by Cargoffer) is the freight & mobility API gateway that lets AI agents calculate tolls, find fuel stations, track drivers, and plan routes via one MCP connection.

## Documentation

- [Getting Started](https://docs.transcend.cargoffer.com/getting-started): Install, auth, first call
- [API Reference](https://docs.transcend.cargoffer.com/api-reference): All endpoints
- [MCP Integration](https://docs.transcend.cargoffer.com/integrations): Connect Claude, Cursor, Hermes, swarm1

## Live Resources

- Gateway: https://back.transcend.cargoffer.com/
- MCP Server (HTTP): https://mcp.transcend.cargoffer.com/mcp
- API Health: https://back.transcend.cargoffer.com/health

## Source Code

- Backend (gateway): https://github.com/cargoffer/transcend_back
- MCP Server: https://github.com/cargoffer/transcend-mcp

## Key Features

- Tolls calculation for any route (Transcend tolls service)
- Nearby / best-price fuel stations along a route
- Parking search via POI service
- Driver lookup + live position tracking
- Fleet vehicle listing
- Route calculation with metrics

## Tech Stack

- Backend: Node.js + Express (API gateway to microservices: route, tolls, poi, stations, drivers, vehicles, iam)
- Auth: ServiceApiKey (`x-api-key: tr_sk_...`) verified by IAM, or Bearer JWT
- MCP: @modelcontextprotocol/sdk (stdio + HTTP streamable)

## Authentication

- **ServiceApiKey:** `x-api-key: tr_sk_...` header, server-side, verified by IAM (tiers: free/pro/enterprise, rate-limited).
- **JWT:** `Authorization: Bearer <jwt>` for user-scoped calls.

## MCP Integration

```json
{
  "mcpServers": {
    "transcend": {
      "command": "node",
      "args": ["/path/to/transcend-mcp/dist/index.js"],
      "env": { "TRANSCEND_API_KEY": "tr_sk_xxx" }
    }
  }
}
```

Or hosted: `https://mcp.transcend.cargoffer.com/mcp`

## API Endpoints by Module

### tolls (1 endpoint)
- `GET /tolls` - Calculate tolls for a route

### stations (2 endpoints)
- `GET /stations/nearby` - Fuel stations near location/path
- `GET /stations/best-prices` - Best fuel prices

### poi (1 endpoint)
- `GET /poi/parking/location` - Parking near coordinates

### drivers (2 endpoints)
- `GET /drivers/{id}` - Driver detail
- `GET /drivers/{id}/position` - Live position

### vehicles (1 endpoint)
- `GET /vehicles/vehicles` - List fleet vehicles

### route (1 endpoint)
- `GET /route` - Calculate route

### gateway (1 endpoint)
- `GET /health` - Gateway health + active microservices

## Common Use Cases

```bash
# Tolls via REST (needs x-api-key)
curl "https://back.transcend.cargoffer.com/tolls?origin=Madrid&destination=Barcelona" \
  -H "x-api-key: tr_sk_xxx"

# MCP tool call via mcporter (ad-hoc HTTP)
mcporter call https://mcp.transcend.cargoffer.com/mcp.transcend_get_tolls
```

## Self-Hosting

```bash
git clone https://github.com/cargoffer/transcend-mcp
cd transcend-mcp && npm install && npm run build
TRANSCEND_API_KEY=tr_sk_xxx node dist/http-server.js   # :3000/mcp
```

## License

MIT