# StallReady MCP — food-truck readiness for agents

Remote MCP **Streamable HTTP** transport (protocol `2025-06-18`). Single endpoint:

**`https://stallready.com/api/mcp`**

- **POST** (Bearer required): JSON-RPC (`initialize`, `tools/list`, `tools/call`). Include `Accept: application/json, text/event-stream` for spec-compliant clients; responses are JSON unless the client negotiates SSE on the POST.
- **GET** (Bearer required): authenticated discovery JSON, or **405** for legacy standalone SSE (use POST Streamable HTTP instead).
- **Unauthenticated** MCP HTTP requests return **401** with `WWW-Authenticate` pointing at [Protected Resource Metadata](https://stallready.com/.well-known/oauth-protected-resource).

- **Legacy transport:** The 2024-11-05 HTTP+SSE profile is **not** hosted; use Streamable HTTP only. That is not the same as sending `2024-11-05` only inside an `initialize` JSON-RPC body (see **Protocol version** below).

## Protocol version

- **Recommended HTTP header:** `MCP-Protocol-Version: 2025-06-18` on every MCP HTTP request. Also accepted: `2025-03-26`, or omit the header.
- **Unsupported HTTP header** (e.g. `MCP-Protocol-Version: 2024-11-05`) → **HTTP 400** with `{ "error": { "code": "invalid_protocol_version", ... } }` before JSON-RPC runs.
- **`initialize` body:** With a supported or omitted header, `params.protocolVersion: "2024-11-05"` is **not** rejected. Response is **HTTP 200** with negotiated `protocolVersion: "2025-06-18"` in the result.

## Auth

- **OAuth 2.1 (remote):** Clients discover the authorization server via `https://stallready.com/.well-known/oauth-protected-resource` (RFC 9728). AS metadata includes `mcp_oauth_status`: `stub` until `MCP_OAUTH_*` env vars point at a live IdP — **Bearer `sr_live_` keys are the supported credential today.**
- **API key (interim):** `Authorization: Bearer sr_live_…` from app settings on **Ops+MCP** (`ops_mcp`).
- **401** — missing/invalid credentials (includes `WWW-Authenticate` for OAuth discovery).
- **403** — valid key but org not on Ops+MCP (Solo/Fleet do not unlock MCP).

Demo key (local seed): `sr_live_demo_stallready_ops_key_0001` on the seeded demo org.

## Tool catalog

| Tool | Purpose |
| --- | --- |
| `list_trucks` | Trucks in the authenticated org |
| `list_credentials` | Credentials; optional `truck_id`, `status` filter |
| `list_expiring_docs` | Expiring within `within_days` (default 30); optional `truck_id`, `doc_types`, `include_expired` |
| `get_readiness_score` | **Required:** `truck_id`, `city`, `event_date` — score 0–100 + missing docs |
| `get_city_checklist` | **Required:** `city` — TX corridor / DSHS rule cards with sources |
| `export_inspector_packet` | **Required:** `truck_id` — creates packet export; returns `print_url` (side effect) |
| `generate_compliance_pack` | **Required:** `city`, `event_date`, `truck_id`; **`confirm: true`** required — aggregates checklist + readiness + packet |

## Honest limits

- **No government submit** — prepare-only; does not file with agencies or portals.
- **Confirm-gated pack** — `generate_compliance_pack` returns `confirm_required` without `confirm: true`.
- **Rate limits (per org, in-memory):** 600 requests/minute; 120 tool calls/minute; **429** with `Retry-After`.
- **Monthly fair-use:** 5,000 tool calls/mo included; soft `X-MCP-Fair-Use-Warning` after allowance; hard cap 7,500/mo.
- **Idempotency:** `export_inspector_packet` and `generate_compliance_pack` accept optional `idempotency_key`.
- **Tier gate** — MCP requires Ops+MCP ($149/mo). Upgrade via [billing](https://stallready.com/app/billing?plan=ops_mcp). See [pricing.md](https://stallready.com/marketing/pricing.md).
- **Docs:** [docs/mcp](https://stallready.com/docs/mcp) (PathProbe workflow) · [server.json](https://stallready.com/server.json).

## Example: tools/list

```bash
curl -s -X POST https://stallready.com/api/mcp \
  -H "Authorization: Bearer YOUR_SR_LIVE_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

## Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "stallready": {
      "url": "https://stallready.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_SR_LIVE_KEY"
      }
    }
  }
}
```

## Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "stallready": {
      "url": "https://stallready.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_SR_LIVE_KEY"
      }
    }
  }
}
```

Replace `YOUR_SR_LIVE_KEY` with an Ops+MCP key from https://stallready.com/app/settings after upgrade.

## More

- Human install page: https://stallready.com/mcp
- Agent index: https://stallready.com/llms.txt
- Start free: https://stallready.com/signup
- Ops consult: https://stallready.com/sales?intent=ops

**Not legal advice.** Confirm city rules with the issuing agency.