Developers / Reference

MCP server

Connect an AI agent to FuelAtlas over the Model Context Protocol so it can list vehicles, set destinations, read fuel guidance, and find the cheapest diesel as first-class tools — with your API key, the same scopes and caps as the REST API, and the sandbox for safe testing.

What is the MCP server

The Model Context Protocol is an open standard for connecting AI agents to tools and data. The FuelAtlas MCP server exposes the Public API as MCP tools, so a compatible client (Claude, ChatGPT, or any agent framework) can act on a fleet directly — no bespoke integration code. It is served over streamable HTTP at a single endpoint:

https://api.fuelatlas.com/mcp

Authentication is the same API key as REST, sent as a bearer token. A fa_test_ key keeps an agent on the simulated sandbox fleet (and unlocks the reset_sandbox / trigger_scenario tools) while you build; a fa_live_ key acts on your real fleet. Every tool obeys the same scopes, per-query caps, rate limits, monthly quotas and anti-scrape station budget as the REST API — an agent can't do anything your key isn't already allowed to do.

Connect

• Endpoint: https://api.fuelatlas.com/mcp (streamable HTTP, stateless).
• Auth header: Authorization: Bearer fa_test_… (or fa_live_…).
• Partner keys select the acting fleet with the FA-Fleet: flt_… header on the connector, or a fleet_id argument per tool call. Company and sandbox keys resolve their fleet automatically.

Claude Code

Register the server in one command, then just talk to your fleet:

claude mcp add --transport http fuelatlas https://api.fuelatlas.com/mcp \
  --header "Authorization: Bearer fa_test_your_key"

Claude Desktop & claude.ai

In Settings → Connectors → Add custom connector, use the endpoint URL and add the bearer header. For Claude Desktop's config file, add an HTTP MCP server:

{
  "mcpServers": {
    "fuelatlas": {
      "type": "http",
      "url": "https://api.fuelatlas.com/mcp",
      "headers": { "Authorization": "Bearer fa_test_your_key" }
    }
  }
}

ChatGPT

In ChatGPT developer mode (Settings → Connectors → Advanced → Developer mode), add a connector with the MCP URL https://api.fuelatlas.com/mcp and an Authorization: Bearer header set to your API key. The FuelAtlas tools then appear to the model in that conversation.

Tool catalog

Every tool returns the same snake_case JSON as the REST API; stations are opaque stn_ ids.

• Vehicles — list_vehicles, get_vehicle (status + last location + fuel + guidance summary), push_vehicle_location.
• Guidance — get_vehicle_guidance, set_vehicle_destination (open continuous fuel guidance).
• Routing & prices — optimize_route, get_fuel_prices_near, get_fuel_prices_along_route.
• Trips & reporting — create_trip, get_trip, get_savings_report.
• Sandbox only (fa_test_ keys) — reset_sandbox, trigger_scenario.

Resources

The server also publishes read-only MCP resources an agent can pull into context:

• fuelatlas://openapi — the full public OpenAPI 3.0 spec.
• fuelatlas://docs/getting-started — a concise onboarding guide.
• fuelatlas://docs/errors — the stable error-code registry.

A first prompt to try

“List my vehicles and tell me which one needs fuel soonest, and where it should stop.”

The agent will call list_vehicles, get_vehicle, then optimize_route or get_fuel_prices_near — and come back with a recommended stop, price and savings.

Errors & limits

Tool errors return a structured { code, message, hint, doc_url } with the same stable machine codes as the REST API (see the error reference), so an agent can self-heal — e.g. a missing scope returns insufficient_scope and a too-broad price query returns validation_failed or station_budget_exceeded. For deeper background you can also feed llms-full.txt into your agent, or explore every operation in the interactive API reference.