Overview & quickstart

Choose REST or MCP

Both interfaces use the same calculation engine and permission model. Use REST with an API key for applications and scripts where you control each request. Use MCP when an AI assistant or agent should discover the available tools, understand their schemas, and choose the right calculation itself.

Authentication

Two sign-in methods reach the same calculation engine. Interactive AI clients connect to the MCP server and authorize access in the browser with OAuth. Applications, services, scripts and manual integrations use a Road User Tools API key sent as a Bearer token. Keys are free to create and can be rotated or revoked at any time.

Authorization: Bearer rut_live_...

REST quickstart

Send a JSON request to any versioned REST endpoint using your API key. Responses use a consistentok, data, anderrorstructure across all calculation tools.

curl -X POST https://roaduser.tools/api/v1/journey-time \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "distance": { "value": 250, "unit": "km" },
    "speed": { "value": 100, "unit": "kmh" }
  }'

MCP quickstart

Add the server URL to a compatible AI client and approve access in your browser when the Road User Tools authorization page opens. The client discovers the sign-in setup and the available tools automatically, with no keys or tokens to copy.

https://roaduser.tools/mcp

Alternative: manual configuration with an API key

Clients without browser authorization, and programmatic integrations, can send an API key instead:

{
  "mcpServers": {
    "roaduser-tools": {
      "url": "https://roaduser.tools/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

REST response format

Successful REST responses return the calculated result indata. Validation and request failures return a stable machine-readable error code alongside a human-readable message.

{
  "ok": true,
  "data": {
    "totalHours": 2.5,
    "formatted": "2:30:00"
  }
}

{
  "ok": false,
  "error": {
    "code": "invalid_request",
    "message": "Invalid journey time input."
  }
}