dispatch MCP server
Commit Nov 8, 2026Lets an AI agent quote, book, and track last-mile deliveries across multiple fleet partners using integrated REST clients and webhooks.
Also known as rayneto06/dispatch-mcp
- Stars
- 0
- Tools
- 5
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 8, 2026
- License
- MIT
What is dispatch MCP?
dispatch lets an AI agent quote, book, and track last-mile deliveries across multiple fleet partners using integrated REST clients and webhooks. It exposes 5 tools, such as quote_delivery, create_delivery, get_delivery.
Summary generated from the project's README
About dispatch MCP server
Managing last-mile logistics through an AI agent is possible with dispatch-mcp. This Go-based server allows developers to integrate AI clients like Claude Code or Cursor with multiple fleet partners to quote, book, and track deliveries. It handles the complex integration work by managing individual REST clients for different partners, ensuring idempotent bookings and handling retries when services fail or rate-limit requests.
Users can run the server locally via stdio or deploy it to Cloud Run for remote access using Streamable HTTP. The system uses OSRM for routing and distance calculations. It includes built-in reliability features like HMAC-signed webhooks, deduplication, and reconciliation to ensure delivery statuses remain accurate even if webhooks are delivered multiple times or arrive out of order. The partner_health tool provides visibility into partner behavior, including timeouts and error rates.
What you can do with it
- 1Compare delivery pricesAsk the agent to find the cheapest delivery option between two specific locations.
- 2Automate delivery bookingsInstruct an AI to select and book a delivery based on speed or cost.
- 3Monitor delivery statusTrack the real-time progress of a package from pickup to delivery.
- 4Audit partner performanceCheck how reliable different fleet partners are by reviewing their error and timeout rates.
Written from the project's README. Every use case is checked against a quote from it.
dispatch MCP tools 5
Detected from the READMEquote_deliverycreate_deliveryget_deliverylist_deliveriespartner_health
Configuration
PARTNER_API_KEYPROJECT_ID
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablerayneto06/dispatch-mcp is public and reachablegithub.com/rayneto06/dispatch-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-08github.com/rayneto06/dispatch-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model5 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubdispatch-mcp
An MCP server, written in Go, that lets an AI agent quote, book and track last-mile deliveries across several fleet partners.
The agent never talks to a partner. It calls five tools; the server does the integration work behind them: one REST client per partner with idempotent bookings and careful retries, HMAC-signed webhooks coming back, deduplication, ordering, reconciliation, and counters that let the agent see how the partners behaved.
The partners are simulated (cmd/fakefleet), and they misbehave on
purpose: one is slow, one rate-limits and fails, and all of them sometimes
deliver the same webhook twice. Routing uses the public
OSRM demo server.
This is a learning project, built to get hands-on with Go. It deploys to Cloud Run, but it is a proof of concept, not a production system; DECISIONS.md says what would change for production. No public instance is running: run it locally, or deploy your own.
Architecture
agent (Claude Code, MCP Inspector, ...)
│ MCP: stdio locally, Streamable HTTP when hosted
▼
dispatch-mcp ─────────── GET ──────────► OSRM (route distance and time)
│ ▲
│ │ POST /webhooks/{partner} HMAC-signed status events
│ │
▼ │ REST /{partner}/v1/... API key, Idempotency-Key
fakefleet: partners alpha, beta, gamma
| Partner | Behavior |
|---|---|
| alpha | reliable, mid-priced |
| beta | slow to quote (0.8–2.5 s), often misses the 1.5 s quote round |
| gamma | cheapest; 15% 429 with Retry-After, 15% 503, and 10% "books the delivery, then answers 503" |
Deliveries go pending → assigned → picked_up → delivered in two to three
minutes, each step reported by webhook.
Tools
| Tool | What it does |
|---|---|
quote_delivery |
Routes the trip once (OSRM, or a straight-line estimate if OSRM is down), then asks every partner for a price at the same time and waits at most 1.5 s. Returns quotes sorted by price and the partners that did not answer, with the reason. |
create_delivery |
Books a quote with its partner. Idempotent per quote_id: repeating the call, even concurrently, returns the same delivery. |
get_delivery |
Current status and history. If the partner has been quiet for 30 s, asks it directly before answering, so a lost webhook only delays an update. |
list_deliveries |
Newest first, cursor-paginated. |
partner_health |
Per partner: requests, retries, 429s, 5xx, timeouts, webhooks received, duplicates and out-of-order events dropped, bad signatures. Plus OSRM calls and fallbacks. |
Run it locally
Requires Go 1.27.
go build -o bin/ ./cmd/...
# Terminal 1: the simulated partners on :8090. TIME_SCALE=0.2 runs five times faster.
PARTNER_API_KEY=dev WEBHOOK_SECRET=dev TIME_SCALE=0.2 bin/fakefleet
# Claude Code starts dispatch-mcp over stdio; it listens for webhooks on 127.0.0.1:8081.
claude mcp add dispatch -e PARTNER_API_KEY=dev -e WEBHOOK_SECRET=dev -- "$PWD/bin/dispatch-mcp"
Then ask Claude Code something like "quote a delivery from the Ferry Building to Mission Dolores and book the cheapest one".
If port 8081 is already taken, by a second window running the server for
example, the server still starts. Its webhooks then reach the other server,
so get_delivery keeps its deliveries current by asking the partner instead;
list_deliveries shows the status as of the last get_delivery.
With the MCP Inspector:
npx @modelcontextprotocol/inspector -e PARTNER_API_KEY=dev -e WEBHOOK_SECRET=dev bin/dispatch-mcp
Example session
Tool calls captured by internal/smoke against a Cloud Run deployment of
this repo (abridged), from the Ferry Building to Mission Dolores in San
Francisco. The same flow runs locally.
// quote_delivery {"pickup":{"lat":37.7955,"lon":-122.3937},"dropoff":{"lat":37.7599,"lon":-122.4268}} 2.2 s
{
"route": {"distance_km": 6.8, "duration_min": 11, "source": "osrm"},
"quotes": [
{"quote_id": "q_9028947b83f2c361", "partner": "gamma", "price_cents": 1311, "pickup_eta_min": 16, "dropoff_eta_min": 27},
{"quote_id": "q_9a8cea8add653a48", "partner": "alpha", "price_cents": 1714, "pickup_eta_min": 15, "dropoff_eta_min": 26}
],
"unavailable": [{"partner": "beta", "reason": "timed out after 1.5s"}]
}
// create_delivery {"quote_id":"q_9028947b83f2c361"} 0.4 s
{"already_booked": false, "delivery": {"delivery_id": "d_…", "partner": "gamma", "status": "pending", "last_update_source": "create", ...}}
// get_delivery, about 15 s later: gamma's webhook moved it on
{"delivery": {"status": "assigned", "last_update_source": "webhook", "history": [...]}}
Connect to a deployment
A deployment's endpoint is one URL with a secret path segment, which
deploy/deploy.sh saves to .env as MCP_URL. It works with any MCP client
that supports remote servers over Streamable HTTP; there is no OAuth step,
because the URL is the credential. Keep it out of client config files you
commit: .gitignore already covers .mcp.json and .vscode/mcp.json.
set -a; . ./.env; set +a # loads MCP_URL into this shell
| Client | How to connect |
|---|---|
| Claude Code | claude mcp add --transport http dispatch "$MCP_URL" |
| Codex (CLI and IDE) | codex mcp add dispatch --url "$MCP_URL", or in ~/.codex/config.toml: [mcp_servers.dispatch] with url = "<MCP_URL>" |
| Claude Desktop, claude.ai | Settings → Connectors → Add custom connector, paste the URL |
| Cursor | ~/.cursor/mcp.json: {"mcpServers": {"dispatch": {"url": "<MCP_URL>"}}} |
| VS Code | .vscode/mcp.json: {"servers": {"dispatch": {"type": "http", "url": "<MCP_URL>"}}} |
| MCP Inspector | Transport "Streamable HTTP", paste the URL |
Then ask in plain language, for example "quote a delivery from the Ferry Building to Mission Dolores in San Francisco and book the fastest one". The server's instructions tell the agent the flow. Any city works, as long as pickup and dropoff are within 50 km. Clients that only speak the older HTTP+SSE transport will not connect.
Once deployed, both services scale to zero. The first call after a quiet period wakes them (a few seconds), and state is in memory, so deliveries disappear after about 15 minutes without traffic. The server's instructions tell the agent this.
Configuration
| Variable | Binary | Default | |
|---|---|---|---|
PARTNER_API_KEY |
both | required; the partners' API key | |
WEBHOOK_SECRET |
both | required; HMAC key for webhooks | |
TRANSPORT |
dispatch-mcp | stdio |
stdio or http |
MCP_TOKEN |
dispatch-mcp | required in http mode, 32+ chars; the secret path segment of /mcp/{token} |
|
PORT |
both | 8080 / 8090 |
http listener |
WEBHOOK_ADDR |
dispatch-mcp | 127.0.0.1:8081 |
webhook listener in stdio mode |
FLEET_BASE_URL |
dispatch-mcp | http://127.0.0.1:8090 |
|
PARTNERS |
dispatch-mcp | alpha,beta,gamma |
|
OSRM_BASE_URL |
dispatch-mcp | https://router.project-osrm.org |
|
QUOTE_DEADLINE |
dispatch-mcp | 1.5s |
|
WEBHOOK_URL |
fakefleet | http://127.0.0.1:8081 |
where to send webhooks |
TIME_SCALE |
fakefleet | 1 |
multiplies status timings |
LOG_LEVEL |
both | info |
Logs are JSON on stderr, in the shape Cloud Logging reads. Every MCP request
gets a request ID that is logged with each partner call it makes and sent to
the partner as X-Request-ID, so one tool call can be followed across both
services:
gcloud logging read 'jsonPayload.request_id="req_3f9a1c0b7d2e"' --project my-project --format json
Tests
go test -race ./...
# Against a running server in http mode, a deployment or a local one
# (MCP_URL comes from .env, see Deploy):
set -a; . ./.env; set +a
go test -tags smoke -v ./internal/smoke
CI runs gofmt, go vet, the race-enabled tests and a Docker image build on
every push. Unit tests use httptest servers for the partner, OSRM and
webhook sides. cmd/dispatch-mcp has end-to-end tests that drive the real
server through an in-memory MCP client against an in-process fleet,
including one where the partner books and then fails, and sends every
webhook twice.
Tested end to end with Claude Code, MCP Inspector and the Go SDK client.
Deploy
deploy/deploy.sh builds one image with Cloud Build and deploys two Cloud
Run services, dispatch-mcp and fakefleet, in their own project. It
creates the project if needed, the secrets in Secret Manager, and one service
account per service that can read only the secrets that service uses. Once a
deploy has succeeded, re-running it is safe; a first run that fails while
linking billing or creating the secrets may need that step finished by hand.
The MCP URL carries the token, so the script writes it to .env (gitignored,
mode 600) as MCP_URL instead of printing it; .env.example lists the
variables.
PROJECT_ID=my-project BILLING_ACCOUNT=XXXXXX-XXXXXX-XXXXXX bash deploy/deploy.sh
Both services run with min-instances=0 and max-instances=1. Set a
Cloud Billing spend cap on Cloud Run for the project.
To rotate the token, add a secret version and deploy again; the script
rewrites MCP_URL in .env:
openssl rand -hex 32 | tr -d '\n' | gcloud secrets versions add mcp-token --data-file=- --project my-project
PROJECT_ID=my-project bash deploy/deploy.sh
To remove everything, delete the project: gcloud projects delete my-project.
Layout
cmd/dispatch-mcp main: config, wiring, stdio/http, shutdown
cmd/fakefleet main for the simulated partners
internal/mcpserver the five tools, instructions, request logging, error messages
internal/dispatch quotes and deliveries: fan-out, booking, reconciliation, store
internal/partner REST client for one partner: retries, Retry-After, typed errors
internal/webhook webhook receiver: signature, dedup, ordering
internal/webhooksig signing scheme shared by both sides
internal/routing OSRM client and fallback estimate
internal/fleet the simulated partners
internal/health counters behind partner_health
internal/httpx server timeouts, graceful shutdown, token and rate-limit middleware
internal/obs JSON logger and request IDs
internal/geo coordinates and distance
internal/smoke smoke test for a deployment (build tag "smoke")
License
MIT.
dispatch MCP questions
What tools does dispatch MCP provide?
It exposes 5 tools, including quote_delivery, create_delivery, get_delivery, list_deliveries, partner_health.
What can an AI agent do with this server?
The agent can quote delivery prices, book deliveries, track current status and history, list recent deliveries, and check the health of fleet partners.
How does the server handle partner reliability issues?
The server uses idempotent bookings, careful retries, HMAC-signed webhooks, deduplication, and reconciliation to manage partner behavior.
How do I connect to a deployed instance?
You can connect using any MCP client that supports remote servers over Streamable HTTP by providing the MCP_URL, which contains a secret token.