Skip to main content
Glama
serve-delivery-mcp

serve-delivery-mcp

by edtechniti

serve-delivery-mcp

An MCP server that lets AI assistants quote, dispatch and track sidewalk delivery robots through the Serve Robotics AV Delivery API.

Independent project. Not affiliated with, endorsed by, or sponsored by Serve Robotics. Built only from Serve's public API reference. Fees and ETAs in mock mode are invented.

You:     Send two coffees from Corner Cafe to Alex at 200 Spring St.
Claude:  A robot can do that for $4.07, arriving in about 13 minutes. Book it?
You:     Yes.
Claude:  Dispatched. The robot is heading to the cafe now.

Why it's built this way

Letting an agent act in the physical world is mostly a guardrails problem. This server enforces the important rules in code instead of trusting the model to follow them:

Guardrail

How

The human approves every price

Dispatching takes a two-step flow, and dispatch_robot requires an existing quote_id plus confirmed: true. Serve's one-step instant-dispatch endpoint is deliberately not exposed.

Hard spending cap

SERVE_MAX_FEE_CENTS (default $15) is checked against the fee Serve returned, not anything the model says.

No address swaps

Pickup and dropoff are bound to the quote on the server side. The model can't dispatch to an address that wasn't priced.

No duplicate dispatches

Job creation is never retried blindly. If a response is lost, the server looks up the order before reporting an error.

Production needs two switches

Both SERVE_ENV=production and SERVE_ALLOW_PRODUCTION=true.

Unlock is explicit

Tracking output never includes the bin unlock code.

No leaked secrets

Credentials come only from the environment and are redacted from all logs. Logs go to stderr, because stdout carries the MCP protocol.

Related MCP server: getterdone-mcp-server

Tools

Tool

What it does

check_robot_availability

Counts robots on duty near a location

get_delivery_quote

Gets a price and ETA for pickup → dropoff (reserves nothing)

dispatch_robot

Turns a confirmed quote into a delivery

track_delivery

Shows status, robot position and ETAs

list_deliveries

Lists active or recent deliveries

cancel_delivery

Cancels an unfinished delivery

unlock_robot_bin

Opens the cargo bin at the dropoff

get_delivery_route

Shows the planned route summary, with GeoJSON on request

simulate_delivery_progress

Mock/sandbox only: moves a delivery through its stages

Every tool carries MCP annotations (readOnlyHint, destructiveHint, …), so clients can tell which ones only read data and which ones act.

Quick start (no credentials needed)

Requires Node.js ≥ 22.12.

git clone https://github.com/edtechniti/serve-mcp.git
cd serve-mcp
npm install
npm run build
npm run mock          # terminal 1: mock Serve API on http://127.0.0.1:4010
npm run inspect       # terminal 2: MCP Inspector (optional)

Claude Desktop

Add this to claude_desktop_config.json (keep npm run mock running):

{
  "mcpServers": {
    "serve-delivery": {
      "command": "node",
      "args": ["/absolute/path/to/serve-mcp/dist/src/index.js"],
      "env": {
        "SERVE_ENV": "mock",
        "GEOCODER_USER_AGENT": "serve-delivery-mcp (you@example.com)"
      }
    }
  }
}

Then ask Claude something like: "Quote a robot delivery from 100 Main St to 200 Spring St, Los Angeles CA 90012."

Configuration

All settings are environment variables. See .env.example.

Variable

Default

Notes

SERVE_ENV

mock

mock, sandbox or production

SERVE_BASE_URL

per environment

Override, e.g. a different mock port. Must be https outside mock mode.

SERVE_PARTNER_ID

ptnr_mock

Required for sandbox/production

SERVE_API_KEY

—

Required for sandbox/production; sent as X-API-Key

SERVE_ALLOW_PRODUCTION

false

Must be true to use production

SERVE_MAX_FEE_CENTS

1500

Hard cap per delivery

SERVE_REQUEST_TIMEOUT_MS

15000

Per-request timeout

GEOCODER

nominatim

nominatim (OpenStreetMap) or none (caller supplies lat/lng)

GEOCODER_USER_AGENT

generic

Nominatim's policy asks for an identifying UA with contact info

LOG_LEVEL

info

debug, info, warn, error

Serve needs both an address and coordinates for each stop. If the assistant doesn't provide coordinates, the server geocodes the address (at most 1 request per second, per Nominatim's policy). The quote shows the address it matched so the user can catch a wrong pin before approving.

The mock

mock/server.ts is an in-memory implementation of the public API contract: the same paths, payloads and error format; single-use quotes that expire after 5 minutes; the job lifecycle; and the documented error codes (used_quote, couriers_busy, not_arrived_at_dropoff, …). It uses only node:http and is what the integration tests run against.

Development

npm run check     # typecheck + lint + format check + tests
npm test          # tests only
npm run dev       # run the MCP server from source
src/
  index.ts              entry point (stdio)
  server.ts             builds the MCP server and registers tools
  config.ts             env parsing and guards
  logger.ts             stderr logger with redaction
  serve/                typed API client, schemas, error mapping
  geo/                  geocoders
  state/                session quote cache
  tools/                one module per tool
mock/                   mock Serve API
test/                   unit and end-to-end tests (MCP client ↔ server ↔ mock)

License

MIT. "Serve Robotics" is a trademark of its owner and is used here only to describe compatibility.

Available Tools

9 tools
cancel_deliveryCancel deliveryA
DestructiveIdempotent

Cancel a delivery that hasn't finished. Confirm with the user first; a canceled delivery can't be resumed.

Inputs: delivery_id (required), notes, reason.

check_robot_availabilityCheck robot availabilityA
Read-only

Count delivery robots on duty near a location. Use this to check whether Serve operates in an area before quoting a delivery.

Inputs: location (required), radius_m.

dispatch_robotDispatch robotA

Send a robot to fulfil a quote from get_delivery_quote. This creates a real delivery and incurs the quoted fee (outside mock mode). Only call it after the user has seen the fee and addresses and explicitly said yes; set confirmed=true only in that case. Pickup and dropoff are taken from the quote and can't be changed.

Inputs: items (required), quote_id (required), confirmed (required), recipient_name (required), +3 more.

get_delivery_quoteGet delivery quoteA
Read-only

Price and ETA for a robot delivery from pickup to dropoff. Reserves nothing. Quotes expire after about 5 minutes and can be used once. Always show the fee, ETA and both resolved addresses to the user and get their explicit approval before calling dispatch_robot.

Inputs: pickup (required), dropoff (required), dropoff_deadline, simulate_rejection.

get_delivery_routeGet delivery routeB
Read-only

The robot's planned route for a delivery: distance per leg, and optionally the GeoJSON geometry for mapping.

Inputs: delivery_id (required), include_geometry.

list_deliveriesList deliveriesA
Read-only

List deliveries, newest first. Defaults to active deliveries only.

Inputs: limit, active_only.

simulate_delivery_progressSimulate delivery progressA

Testing only (mock/sandbox): move a simulated delivery to a later stage, or reject it with a reason, to demo the full lifecycle.

Inputs: delivery_id (required), target_stage (required), reject_reason.

track_deliveryTrack deliveryB
Read-only

Current status, robot position and ETAs for a delivery.

Inputs: delivery_id (required).

unlock_robot_binUnlock robot binA

Open the robot's cargo bin so the recipient can collect the items. Only works once the robot has arrived at the dropoff.

Inputs: delivery_id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 9 tools

    Disambiguation4/5

    Each tool maps to a distinct step in the delivery lifecycle (quote, dispatch, track, route, unlock, cancel, list, availability), so misselection is unlikely. Minor overlap exists between track_delivery and get_delivery_route, and between cancel_delivery and simulate_delivery_progress's reject action, but descriptions clarify the boundaries.

    Naming Consistency5/5

    All nine tools follow a strict snake_case verb_noun convention (get_delivery_route, check_robot_availability, dispatch_robot, unlock_robot_bin, etc.). Verbs are chosen consistently for their operation type (get/list/check vs. dispatch/cancel/unlock).

    Tool Count5/5

    Nine tools is well within the ideal 3-15 range and each earns its place by covering a distinct lifecycle operation. Nothing feels padded or missing from a count perspective.

    Completeness4/5

    The surface covers the full flow: availability check, quote, dispatch, track, route, unlock bin, cancel, list, plus a mock simulator for testing. Gaps are minor—no way to fetch a single delivery's full detail/history by ID or modify an in-flight delivery's dropoff.

    Related MCP Connectors

    Related MCP Servers