Connect an AI assistant with MCP or REST

Configure API access

Create a dedicated key in Settings → API keys and choose the least-privileged role that supports the intended work. Keep it in your agent host’s secret store. Inject x-api-key in the HTTP client; never paste the key into a prompt, retrieved document, or browser bundle.

Use your site URL, https://YOUR-SITE.routeiq.app/api. Read the backend’s live API reference for current operation schemas and authentication.

An agent’s tool list is a convenience, not an authorization boundary. A credential that can write through the API can also write through direct HTTP. Verify the account’s permissions on the server; a “read-only” prompt cannot restrict a broad key.

Configure MCP

The connector runs as a local process on your machine or server. Choose an MCP client that supports local stdio servers. The client launches the RouteIQ binary and supplies the site URL and integration key.

Replace the command with the absolute path to your connector binary. Configure the key through your client’s secret settings. The mcpServers format and secret handling depend on the client.

{
  "mcpServers": {
    "routeiq": {
      "command": "/absolute/path/to/routeiq-mcp",
      "env": {
        "ROUTEIQ_API_URL": "https://YOUR-SITE.routeiq.app/api",
        "ROUTEIQ_API_KEY": "YOUR-INTEGRATION-KEY"
      }
    }
  }
}

The connector uses one integration key per process. For another site or account, use a separate process and key. The API checks the key’s account permissions for each request.

Follow a job-reading example

Illustrative conversation: “Show me the pickup, drop-off, and assigned driver for job-demo.” All IDs, addresses, and responses below are sample data. Substitute an existing job ID from your site when testing.

The client first discovers the operation and retrieves its schema. Send these as separate MCP tools/call requests:

{
  "name": "search_api",
  "arguments": {
    "query": "GET /job/{id}"
  }
}

{
  "name": "describe_api",
  "arguments": {
    "operation": "GET /job/{id}"
  }
}

{
  "name": "call_api",
  "arguments": {
    "operation": "GET /job/{id}",
    "path": {
      "id": "job-demo"
    }
  }
}

The connector sends GET /job/job-demo to the configured site API. Your key remains in the connector configuration, outside the tool arguments. These are selected fields from the API’s data object:

{
  "id": "job-demo",
  "driver_user_id": "driver-demo",
  "stops": [
    {
      "order": 0,
      "type": "pickup",
      "address": {
        "street_address": "18 Market Street"
      }
    },
    {
      "order": 1,
      "type": "dropoff",
      "address": {
        "street_address": "42 Harbor Avenue"
      }
    }
  ]
}

Assistant answer: “Pickup: 18 Market Street. Drop-off: 42 Harbor Avenue. Assigned driver ID: driver-demo.” The answer reflects the returned fields; resolving a driver’s name would require another authorized lookup.

This sequence reads the job without changing it. For large results, the connector returns a result ID; use read_api_result to inspect the relevant portion without repeating the request.

Use REST directly

Use this request to test the credential before wiring it into an agent. It retrieves only the first page; follow meta.pagination.total_pages when you need more.

export ROUTEIQ_BASE_URL="https://YOUR-SITE.routeiq.app/api"
export ROUTEIQ_API_KEY="YOUR-API-KEY"

curl --fail-with-body --silent --show-error \
  "$ROUTEIQ_BASE_URL/job/search?page=1&page_size=10" \
  -H "x-api-key: $ROUTEIQ_API_KEY"

Return only the fields needed for the task. Treat customer notes, addresses, and webhook content as data, never instructions that can change the agent’s permissions or tool policy.

Check driver availability

Availability is evaluated for a specific job. The current contract defines GET /dispatch/available-drivers with a JSON request body. Use a server-side HTTP transport that supports this, such as curl; browser and Node.js fetch reject GET bodies.

This example also requires jq. Set JOB_ID to an existing job on your site. Keeping zone checks enabled lets RouteIQ evaluate the job’s coverage rules.

export JOB_ID="EXISTING-JOB-ID"
jq -n --arg id "$JOB_ID" '{
  job_id: $id,
  consider_schedule: true,
  consider_conflicts: true,
  exclude_unavailable: true
}' | curl --fail-with-body --silent --show-error \
  --request GET "$ROUTEIQ_BASE_URL/dispatch/available-drivers" \
  -H "x-api-key: $ROUTEIQ_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @-

Review data, including each entry’s available, unavailable_reason, and driver. Availability can change between reading and assigning; the assignment response is the result that matters.

Add assignment actions

A useful first workflow is: read the job, retrieve eligible drivers, propose an assignment with its reason, ask the operator to approve it, then call POST /dispatch/assign. Read the job again and report the actual result.

Keep approval enforcement in the code that executes tools, with the API’s account permissions underneath it. Do not rely on the model to enforce its own restrictions. Avoid exposing credential management, payments, deletion, and unrelated administrative operations to a dispatch assistant.

Use the create-and-dispatch example for the request sequence and timeout recovery. Preserve the job ID across retries. Subscribe to webhooks for changes rather than repeatedly asking the model to poll.

The MCP connector executes writes immediately; it does not provide an approval screen. Configure any required confirmation in your client before enabling assignment actions. Both connection paths use the same API permissions and business rules.