Developer documentation

MCP for AI agents

POST /api/mcp · Bearer API keys

Fleetonomy exposes a Model Context Protocol server so MCP-compatible agents — Claude Desktop, Cursor, Windsurf, or your own orchestrator — can read and act on fleet data with the same authentication, rate limits, and RBAC as the REST API.

On this page

Overview
Endpoint
Authentication
Protocol
Tools
Resources
Safety rails
Quick start
Local development

Overview

The MCP layer is a thin JSON-over-HTTP transport designed for serverless hosting. Each request is stateless: we re-validate your API key, tenant subscription, and key scopes before executing a tool.

Live fleet data

Vehicles, drivers, trips, alerts, and payments.

Same API keys

Reuse keys from Settings → API keys.

Webhook parity

Mutations emit the same events as REST.

Endpoint

The HTTP transport is available at your Fleetonomy host:

POST/api/mcpProduction: replace host with your deployed URL

Authentication

Agents authenticate with the same Authorization: Bearer <api-key> header as /api/v1. Configure your MCP client transport:

MCP transport config

{
  "transport": "http",
  "url": "https://your-host/api/mcp",
  "headers": {
    "Authorization": "Bearer fln_live_..."
  }
}

The server resolves the tenant from the key, checks subscription status, and enforces scopes attached to the key. Agents cannot escalate beyond what the underlying tenant role allows.

Protocol

Requests POST a single JSON envelope (or an array of envelopes for batching). A tools/call example:

tools/call

{
  "method": "tools/call",
  "params": {
    "name": "fleet.list_vehicles",
    "arguments": { "limit": 10, "status": "active" }
  },
  "id": "req-1"
}

Supported methods include:

initialize — handshake and capability discovery
tools/list — enumerate registered tools
tools/call — invoke a tool with arguments
resources/list / resources/read — tenant metadata and schema overview

Responses use { "ok": true, "result": ... } or { "ok": false, "error": { "code", "message" } }.

Tools

Tools return structured JSON aligned with Firestore documents. Read tools are marked with a search icon; writes are labelled Writes data.

Fleet

Vehicles, drivers, and trips in the active tenant.

fleet.list_vehicles
Paginated vehicle list with optional status filter.
fleet.get_vehicle
Fetch a single vehicle by id.
fleet.list_drivers
List drivers with optional status filter.
fleet.list_trips
List trips ordered by createdAt descending.

Operations

Alerts and payments surfaced to agents.

fleet.list_alerts
Recent alerts (open or acknowledged).
fleet.acknowledge_alert
Mark an alert acknowledged (records API key as actor).
Writes data
fleet.list_payments
Recent M-Pesa / bank payments with filters.
fleet.create_alert
Create a telematics or compliance alert from an agent.
Writes data

Run tools/list against your deployment for the authoritative schema (including Zod input definitions). Every mutating tool can emit webhook events so downstream automations stay in sync.

Resources

MCP resources provide read-only context without invoking tools:

fleetonomy://tenant
Active tenant
Metadata for the tenant the API key belongs to.
fleetonomy://schema
Data model overview
High-level Firestore collections and relationships.

Safety rails

Built-in guardrails

Mutations respect API key scopes and tenant RBAC — same rules as REST.
Every invocation is logged to auditLogs with tool name, API key id, and argument hash.
Payment-related tools should include idempotency keys when exposed (see REST docs).
Tenant must have features.apiAccess enabled for destructive operations where applicable.

Quick start (Cursor)

Add Fleetonomy to your Cursor MCP settings (replace the API key with one from your dashboard):

Cursor mcp.json

{
  "mcpServers": {
    "fleetonomy": {
      "url": "http://localhost:3001/api/mcp",
      "headers": {
        "Authorization": "Bearer fln_live_YOUR_KEY"
      }
    }
  }
}

Local development

MCP_API_TOKENS

Set a comma-separated list in .env.local to authorise tokens during development without provisioning Firebase users. Never use this in production.