Meter Drivers & Fleets

View saved version →

---
name: meter-api-explainer
description: "Explain how Meter's agent surface works and what its data means, using the self-documenting describe_api and explain_data tools and the machine-readable docs (llms.txt, llms-full.txt, agents.md, openapi-mcp.json). Covers \"how do I connect\", \"which tool answers X\", \"what does this field mean\", OAuth sign-in, roles, and drafting an integration or client against the MCP server. Use for questions about the API, its tools, fields, authentication or integration code; do not use to actually answer a fleet question (meter-fleet-insights), change settings (meter-settings-changes) or onboard a fleet (meter-fleet-onboarding)."
---

# Explaining the Meter API

Meter's agent surface is one remote MCP server, `https://www.meterapp.co/api/mcp/fleet`, secured with OAuth 2.1 (PKCE). It is self-documenting, and the same documentation is published as static files. Use both.

## Ask the server

When the `meter` MCP server is connected:

- `describe_api` with no arguments returns a compact domain index with tool counts and listed tool names. Use `domain: "<domain>"` to browse its tools, access, risk and sensitive-field escalations; use `tool: "<name>"` for full detail including arguments, an example call and result fields. Choose one selector. Responses are capped at 64 KB; if truncated, request a tool or use `explain_data` for a specific field.
- `explain_data` with `tool` (and optionally `field`, a name or dot path like `items.pickup.address`) returns the meaning, JSON type, unit, allowed values and role visibility of result fields, generated from the schemas the server validates against.
- `whoami` shows what the signed-in person can do here.

Quote these results rather than paraphrasing from memory; they are the current truth for the connected server version.

## Read the published docs

Without a connection, or when drafting code, read the published files. They are generated from the same catalog:

| File | Use it for |
| --- | --- |
| `https://www.meterapp.co/llms.txt` | one-page index: endpoint, integrations, one line per tool, rules |
| `https://www.meterapp.co/llms-full.txt` | everything: OAuth flow, transport, every tool with arguments and result fields, error codes, data model |
| `https://www.meterapp.co/agents.md` | tool table (name, roles, writes?), authorization model, safety rules, the dry_run convention |
| `https://www.meterapp.co/openapi-mcp.json` | OpenAPI 3.1: the JSON-RPC envelope, the `oauth2` security scheme, JSON Schemas for every tool under `x-mcp` and `components.schemas` |
| `https://www.meterapp.co/.well-known/oauth-protected-resource` | which authorization server issues tokens (RFC 9728) |

Human pages: `https://www.meterapp.co/docs`, `/docs/mcp`, `/docs/cli`, `/docs/plugins`, `/docs/authentication`, `/docs/data`.

## Explaining authentication

There are no API keys. Describe the flow in these terms:

1. The client POSTs to `/api/mcp` without a token and gets 401 with `WWW-Authenticate: Bearer resource_metadata="https://www.meterapp.co/.well-known/oauth-protected-resource"`.
2. That document names the authorization server (Supabase Auth) and scopes; `<issuer>/.well-known/oauth-authorization-server` lists its endpoints. PKCE is required; dynamic client registration is available.
3. The person signs in and approves the connector at `https://www.meterapp.co/oauth/consent`; the client exchanges the code for tokens and sends `Authorization: Bearer <access_token>`.

Tokens carry the person's own permissions: owners and admins see fleet-wide data, drivers and riders their own. See [references/authorization.md](../../references/authorization.md).

## Drafting an integration

- Transport: one JSON-RPC 2.0 message per POST, `Accept: application/json, text/event-stream`, JSON responses, stateless (no session id). Methods `initialize`, `tools/list`, `tools/call`, `ping`.
- Prefer an MCP client library. In TypeScript, `@meterapp/meter-sdk` (`MeterMcpClient`) speaks this protocol an

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: meter-driver-personal
description: "Help an individual Meter driver or rider with their own data through the Meter MCP tools: their trips (list_trips driver \"me\"), bookings (list_bookings scope \"driver\" or \"rider\"), Meter Pay earnings and pay stubs (get_earnings scope \"me\"), and their own profile and availability (whoami, update_my_profile, update_my_availability). Use when the signed-in person asks about \"my trips\", \"my earnings\", \"my schedule\", their past rides or their account; do not use to book, track or cancel a ride as a rider (meter-ride), for fleet-wide questions (meter-fleet-insights) or for fleet settings (meter-settings-changes), which need an owner or admin role."
---

# A driver's or rider's own Meter data

Most Meter users are individual drivers (solo or in a fleet) and riders. Their tools work regardless of fleet role and never require an operational fleet. This skill keeps the agent inside that person's own data.

## Start with `whoami`

- `fleets[]`: a driver may belong to one or more fleets; `role: "driver"` means fleet-wide tools will refuse. That is expected, not an error to work around.
- `is_rider: true`: the person has booked rides; `list_bookings` with `scope: "rider"` returns them.
- `profile`: the person's own name, email and phone (never anyone else's).

## Own trips and rides

| Ask | Call |
| --- | --- |
| "My trips this month" | `list_trips` with `driver: "me"`, `start_date`, `end_date`; page with `cursor` |
| "How far did I drive / how much did I collect" | Sum `distance_meters` and `total_minor` over all pages; state the range and currency |
| "My upcoming rides" | `list_bookings` with `scope: "driver"`, `after: now`, `sort: "asc"` |
| "The ride I booked" (as a rider) | `list_bookings` with `scope: "rider"`, then `get_booking` |
| "What happened to that booking" | `get_booking_audit_log` (redacted timeline) |

Solo drivers without a fleet still have trips: `list_trips` with `driver: "me"` and no `fleet_id`.

## Earnings and pay stubs

`get_earnings` with `scope: "me"` returns Meter Pay payouts (card payments transferred to the person's bank account) per currency, with a `day` or `week` series. It does **not** include cash fares. For a pay-stub style summary:

1. Call `get_earnings` for the pay period (`start_date` inclusive, `end_date` exclusive), `granularity: "week"`.
2. Call `list_trips` with `driver: "me"` for the same period and total trips, distance, fares and tips by payment method.
3. Present: period, trip count, gross fares, tips, card payouts (from earnings), cash collected (from trips with a cash payment method), currency, and the fleet's payout fraction if the person is in a fleet (`get_fleet` shows it to admins only; otherwise say it is set by the fleet).

Label every figure with its source tool. Do not present the result as an official tax document.

## Profile and availability

`update_my_profile` (name, business name on receipts, navigation app, receipt privacy options with Meter Pro) and `update_my_availability` (the weekly hours riders may book the driver for; the whole week is replaced, so include every working day) change only the signed-in person's own record. Follow the dry-run sequence from `meter-settings-changes`: call with `dry_run: true` first, save the returned proposal, show every `changes` row (`field`, `from`, `to`), get an explicit yes, then repeat the intended arguments with `proposal_id` and `dry_run: false`. Stale or expired proposals require showing the fresh replacement and asking again. Email, phone, role and payout details are managed in the Meter app, not here.

## What this skill does not do

- It does not look at other drivers. `list_fleet_members`, `driver: "all"` and `scope: "fleet"` are owner/admin tools; a `forbidden` error confirms the person is a driver.
- It does not guess ids. Trip and booking ids come from the list tools.
- It does not change fares, fleet settings or bookings.
- It does not book, track or cancel a ride a

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: meter-fleet-insights
description: "Answer questions about a Meter fleet's trips, bookings, drivers, vehicles, earnings and accounting using the Meter MCP tools (whoami, list_trips, list_bookings, list_fleet_members, list_vehicles, get_earnings, get_accounting_summary). Covers picking the right tool, role limits, pagination and presenting money and times correctly. Use for any \"how many / how much / who / which / when\" question about a fleet; do not use for changing settings (meter-settings-changes), setting up a new fleet (meter-fleet-onboarding), an individual driver's own data (meter-driver-personal), booking a ride as a rider (meter-ride), or explaining the API itself (meter-api-explainer)."
---

# Fleet insights with Meter

The Meter MCP server at `https://www.meterapp.co/api/mcp/fleet` returns the data the signed-in person already sees in the Meter apps. Owners and admins see the whole fleet; drivers see only themselves. Nothing in this skill changes data.

## Always start with `whoami`

Call `whoami` once per session. It returns:

- `fleets[]` with `fleet_id`, `role` (`owner`, `admin`, `driver`) and `is_operational`
- `default_fleet_id` when the person belongs to exactly one fleet (then `fleet_id` may be omitted everywhere)
- `suggested_next_tools`

If there are several fleets and the question does not name one, ask which fleet before calling anything else. Never construct a `fleet_id`.

## Pick the right tool

| Question | Tool | Notes |
| --- | --- | --- |
| Who is in the fleet, which drivers exist | `list_fleet_members` | owners/admins only; `member_id` feeds `list_trips` |
| Which cars, who drives which | `list_vehicles` | `assigned_driver` is admin-only |
| Completed metered rides, revenue per trip, tips | `list_trips` | `driver: "all"` (admins) or a `member_id`; filter with `start_date`/`end_date` |
| One trip in detail | `get_trip` | id from `list_trips` |
| Scheduled and on-demand rides, what is unassigned | `list_bookings` | `scope: "fleet"` for admins; filter by `status`, `after`, `before` |
| What happened to a booking and when | `get_booking_audit_log` | redacted timeline; roles, never names |
| Card payouts to bank accounts | `get_earnings` | `scope: "fleet"`, `include_members: true` for a per-driver split |
| Full ledger: cash, card, unpaid, balances between fleet and drivers | `get_accounting_summary` | owners/admins of an operational fleet |
| Fleet settings, ride options, service zones | `get_fleet` | admins also get booking and payout settings |
| How far a new fleet is from its first booking | `get_onboarding_checklist` | owners/admins; works before the fleet is operational (see `meter-fleet-onboarding`) |

`get_earnings` counts only Meter Pay card payouts. For "how much did the fleet make" including cash, use `get_accounting_summary`. Say which one you used.

## Pagination and time ranges

- Lists return `items` and `next_cursor`. Pass `cursor` back until it is null; keep `limit` at or below 100. For totals over a period, page through everything or use the summary tools instead of stopping early.
- `start_date`/`end_date` (trips, earnings, accounting) and `after`/`before` (bookings) take ISO 8601 dates. Interpret "last week" in the fleet's timezone (`get_fleet` or `list_fleets` return `timezone`), and state the range you used.
- Trips are metered rides that happened. Bookings are scheduled rides, some of which become trips (`trip_id` on the booking once completed). Do not add them together.

## Present numbers correctly

- Money fields end in `_minor` and are in the currency's minor unit: divide by 100 for USD, EUR, GBP and most currencies (JPY and a few others have no minor unit). Show the currency code from the result.
- Distances are meters, durations are seconds, timestamps are ISO 8601. Convert for the human and keep the fleet timezone.
- When a field's meaning is unclear, call `explain_data` with the tool and field name rather than guessing.

## Role limits are final

A `forbidden` e

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: meter-fleet-onboarding
description: "Guide a new fleet owner through Meter fleet setup with the get_onboarding_checklist tool and the settings tools (update_fleet_settings, update_booking_settings, update_ride_option, assign_vehicle), always previewing with dry_run: true and confirming before applying, and knowing when to send them to the web onboarding at meterapp.co/fleet/onboarding instead. Use when someone has just created a fleet, asks what is left to set up, or wants help getting their fleet to its first booking; do not use for day-to-day questions about an established fleet (meter-fleet-insights) or isolated settings edits (meter-settings-changes)."
---

# Onboarding a fleet with Meter

A fleet becomes operational when onboarding is complete and billing is active (`is_operational` in `whoami` and `list_fleets`). Until then, fleet-wide read tools return `fleet_not_operational`, but `get_onboarding_checklist` works on fleets that are still onboarding. This skill turns "what do I still need to do?" into a guided checklist that ends with the first booking.

## Start

1. `whoami`. Confirm the person is `owner` (or `admin`) of the fleet. Drivers cannot onboard a fleet; tell them to ask the owner.
2. `get_onboarding_checklist` with the `fleet_id`. It returns `items` (fleet profile, brand icon, service area, a ride option with a fare, booking settings, a vehicle, a driver, payouts connected as a yes/no, the shareable booking link, the first booking), each saying whether it is done, whether riders can book without it, and how to complete it: the MCP tool to call or the web page to send the human to. It also returns `required_remaining`, `booking_page_status` and the public booking URL. Treat it as the source of truth for what is missing; do not invent steps.
3. `get_fleet` for the current settings so you can quote them back before changing anything.

## Work through the checklist

For each incomplete item, in the order the checklist gives:

- Explain the item in one or two sentences in plain language (what it is, why the fleet needs it, whether riders can book without it).
- Ask for the values you need. Do not fill in defaults the human did not choose, especially fares, cancellation terms and lead times.
- Call the settings tool the item names with `dry_run: true` and only those fields. `dry_run` defaults to false, so never omit it on the preview call. Show the returned `changes` (each `field`, `from`, `to`) verbatim.
- Only after an explicit yes, repeat the intended arguments with the saved `proposal_id` and `dry_run: false`. Stale or expired proposals require showing the fresh replacement and asking again. Confirm `status: applied` (a no-op has `applied: false`), then re-run `get_onboarding_checklist` and continue.

Never batch several items into one apply. One item, one confirmation.

## Send them to the web when

Some items cannot be completed through tools and the checklist says so: it names the page instead of a tool. Send the person to `https://www.meterapp.co/fleet/onboarding` (signed in with the same account) for:

- Billing and subscription (payment method, plan) and connecting payouts (the checklist only reports connected yes/no)
- Uploading the brand icon
- Creating ride options (the tools edit existing ones) and adding vehicles or inviting drivers
- Anything involving documents, identity verification or phone number verification

Say exactly which item needs the web and why; do not attempt a workaround through unrelated tools.

## Fares and ride options

`update_ride_option` edits an existing ride option and the rates of its default fare (in major currency units as shown in the console). Changing a fare is a money decision: state `from` and `to` for the base fare, minimum fare, per-distance and per-minute rates with the currency, and require an explicit yes. If the fleet has an official tariff, prefer it; do not guess market rates.

## Vehicles and drivers

- `list_vehicles` shows the fleet's cars; `assign

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: meter-settings-changes
description: "Safely change Meter fleet settings, booking settings, ride options and fares, vehicle assignments, or the signed-in person's own profile and availability through the Meter MCP write tools (update_fleet_settings, update_booking_settings, update_ride_option, assign_vehicle, update_my_profile, update_my_availability). Enforces the dry_run: true preview, echo changes, explicit confirmation, apply sequence. Use whenever a request would modify fleet settings or the person's own profile in Meter; do not use for read-only questions (meter-fleet-insights, meter-driver-personal), for first-time fleet setup as a whole (meter-fleet-onboarding), or for booking, changing or cancelling a ride as a rider (meter-ride)."
---

# Changing settings in Meter

Every Meter write tool requires a saved proposal. With `dry_run: true` the server validates and authorizes the request, computes the exact changes, saves the proposal and writes nothing. A first call without a live proposal also writes nothing and returns `confirmation_required`. This skill exists so that no change ever happens without the human seeing those changes first.

## The result envelope

A preview includes the following envelope (with the returned proposal ID saved for confirmation):

```json
{
  "status": "preview",
  "proposal": { "id": "the opaque ID returned by this preview" },
  "applied": false,
  "dry_run": true,
  "changes": [{ "field": "payment_mode", "from": "payments_optional", "to": "pre_payment_required" }],
  "booking_settings": { "...": "the resulting object (the current one on a dry run)" }
}
```

- `status` identifies preview, confirmation required, or applied results. `applied` is `false` on a preview and for an applied no-op, and `true` after a mutation. Preserve the complete returned proposal; never construct its ID.
- `changes` lists only the fields that would differ, each with `field`, `from` and `to`. An empty list means nothing would change.
- The last key is the DTO (`fleet`, `booking_settings`, `ride_option`, `vehicle`, `profile`, `availability`); `explain_data` documents its fields.

## The sequence, every time

1. **Read first.** `whoami` for the role, then the matching read tool (`get_fleet` for fleet, booking and ride-option settings; `list_vehicles` and `list_fleet_members` for assignments). Quote the current value.
2. **Dry run.** Call the write tool with `dry_run: true` and only the fields the human named. Never pass fields "to be safe"; omitted fields are left alone and unknown fields are rejected.
3. **Echo the changes.** Show `changes` exactly as returned: each `field` with its `from` and `to` value, plus any warnings. If the list is empty, say nothing would change and stop.
4. **Ask.** One clear question: "Apply these N changes to <fleet name>? (yes/no)". Wait for the answer. A vague reply ("sure, whatever works") is not a yes for money fields; ask again with the numbers.
5. **Apply.** Repeat the intended arguments with the saved `proposal_id` and `dry_run: false`. Confirm `status: applied`; an applied no-op has `applied: false` and no changes. For stale or expired proposals, show the fresh replacement and ask for confirmation again. Report the result and, for fleet settings, re-read with `get_fleet`.

Never skip the dry run because the change "is small", never apply in the same turn as the dry run without an answer in between, and never apply a change the human did not see in the echoed list.

## Money changes need the numbers

Fares (`update_ride_option`: `fare.base`, `fare.minimum_fare`, `fare.distance_rate`, `fare.minute_rate`, `fare.wait_time_minute_rate`, `fare.tax_rate`, in major currency units as shown in the console, 0 to 10000) and cancellation fees (`update_booking_settings`) are money. State `from` and `to` with the currency, e.g. "Base fare: 3.50 -> 4.00 USD". If the human gave a percentage or a vague direction ("raise it a bit"), compute the concrete value, show it, and get a yes on the 

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.