# RatioSeat MCP — waitlist & ratio tools for agents

> Streamable HTTP JSON-RPC at `https://ratioseat.com/api/mcp`. RatioSeat Pro ($29/mo) includes self-serve org API keys. Free agents: read-only demo key against Sunshine Kids Austin.

## Auth

- **GET** `https://ratioseat.com/api/mcp` — server card (no secret required).
- **POST** — JSON-RPC 2.0: `initialize`, `tools/list`, `tools/call`, `ping`.
- **Bearer** — `Authorization: Bearer rs_live_…` minted in the director app (**Settings → MCP**) on active Pro orgs.
- **401** responses include `WWW-Authenticate` and a link to `https://ratioseat.com/.well-known/oauth-protected-resource`.
- Read-only demo: Bearer rs_test_demo (Sunshine Kids Austin seed). Mutating tools return upgrade_required.

### Sample curl

```bash
curl -sS "https://ratioseat.com/api/mcp" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer rs_test_demo" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'

curl -sS "https://ratioseat.com/api/mcp" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer rs_test_demo" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
```

## Pricing

- **Free / demo** — Read-only tools, tight rate limits; mutating tools return `upgrade_required`.
- **RatioSeat Pro ($29/mo)** — Director app + MCP keys; write/notify tools with confirm/dry_run defaults.

Full catalog (21 customer tools) is live on the MCP endpoint — weekly digest, offers, and transitions included. Part-time packing, roster import, and custom ratio overrides are not advertised until implemented.

## Starter tool catalog

- **forecast_openings** — Project seat openings by classroom over the next few weeks from DOB move-ups, withdrawals, and kindergarten exits. (effects: Read; confirm: no)
- **simulate_enrollment** — Run a what-if enrollment: see cascade impact and ratio risk before you commit a seat or schedule pack. (effects: Read / write if persisted; confirm: When saving a scenario)
- **list_ratio_risks** — List projected ratio, group-size, and staffing risks for a date or range under your active ratio profile. (effects: Read; confirm: no)
- **send_offer_email** — Preview or send an enrollment offer email to a waitlisted family (dry-run by default on agent keys). (effects: Write + notify; confirm: Before a live send)
- **update_waitlist_priority** — Change a waitlist entry’s priority tier with a mandatory audit reason. (effects: Write; confirm: yes)

## Install — Cursor (`mcp.json`)

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

Full OAuth 2.1 authorization server and Smithery registry listing are deferred.

## Safety

- Confirm-gated writes on offers, priority changes, and live sends.
- Rate limits per org/key; HTTP `429` with `retry_after` in JSON-RPC error data.
- Idempotency: `Idempotency-Key` header or `idempotency_key` argument on mutating `tools/call`.
- RatioSeat is a planning aid. It does not certify licensing compliance or replace advice from your licensing specialist.

## More

- HTML install page: https://ratioseat.com/mcp
- llms.txt: https://ratioseat.com/llms.txt
- Pricing: https://ratioseat.com/pricing.md
- Compliance: https://ratioseat.com/compliance.md
- Support: support@ratioseat.com