# Streaming — Apparel Monster

Apparel Monster supports streaming through the **MCP streamable-HTTP transport**. Long-running tool responses, server-sent events, and progressive result delivery are all supported.

## MCP streamable-HTTP

The canonical agent-facing streaming endpoint is the MCP server:

```
https://dfe0ea20ac20.agentic.checkouttools.com/mcp
```

- **Transport:** streamable-http (MCP spec 2025-06-15 and later)
- **Protocol:** JSON-RPC 2.0
- **Bidirectional:** POST for request, Server-Sent Events (SSE) for streamed responses and server-initiated notifications
- **Protocol versions supported:** `2025-03-12`, `2025-06-15`, `2025-11-05`

### Why streamable-HTTP over legacy SSE

MCP's legacy SSE transport used a separate `/events` endpoint. Streamable-HTTP unifies both directions over a single URL and adds:

- **Request/response streaming** — tools can emit multiple partial results.
- **Server-initiated notifications** — inventory changes, order status, cart expiry.
- **Transport-level cancellation** — clients can abort in-flight calls.
- **HTTP/2 multiplexing friendliness** — multiple concurrent tool calls share a connection.

### Opening a stream

```http
POST /mcp HTTP/1.1
Host: dfe0ea20ac20.agentic.checkouttools.com
Content-Type: application/json
Accept: application/json, text/event-stream

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{...}}
```

If the server responds with `Content-Type: text/event-stream`, all subsequent JSON-RPC messages flow over the SSE stream until the client closes.

### Keeping the stream alive

The server sends `ping` notifications every 30 seconds. Clients should respond with `pong` within 10 seconds or the server will close the stream. If the connection drops, re-initialize — MCP session tokens are valid for up to 1 hour.

## Progressive tool results

Tools that take time (e.g. a large catalog search) can stream partial results via `notifications/progress`:

```json
{"jsonrpc":"2.0","method":"notifications/progress","params":{"progressToken":"t1","progress":0.5,"total":1.0,"message":"indexed 58 of 116 products"}}
```

The final result arrives as a normal JSON-RPC response referencing the same `id`.

## Webhook-style push (inbound)

Apparel Monster does not currently offer outbound webhooks on the Storefront API (stock change, price drop, order status transitions). Agents that need push notifications should:

- **Subscribe via MCP** — the MCP server will push `notifications/resources/updated` when watched products change price or stock.
- **Poll the order status endpoint** — `GET /api/v2/storefront/order_status/{order_number}` returns current state; poll every 5-10 seconds during active fulfillment.

## REST streaming

The Storefront API does NOT stream responses — every REST call returns a complete JSON:API document. For progressive delivery, use MCP.

## Rate limits during streaming

Open streams count as one request for rate-limit purposes; in-stream tool calls do NOT count individually. The 60 req/min limit applies to stream initiation and short-lived REST calls.

## Error recovery

Streams may be interrupted by:

- **Network disconnect** — client should reconnect and re-initialize.
- **Server restart** — session tokens become invalid; re-authenticate.
- **`429 Too Many Requests`** on initiate — honor the `Retry-After` header before reconnecting.
- **Protocol version mismatch** — server will reject `initialize` with an error; retry with a supported version from `supportedProtocolVersions`.

## References

- MCP server card: [`/.well-known/mcp/server-card.json`](/.well-known/mcp/server-card.json) — 8 tools with input schemas and UI resources.
- MCP transport spec: [`modelcontextprotocol.io`](https://modelcontextprotocol.io/specification/2025-06-15/basic/transports).
- Authentication for MCP: see [`authentication.md`](authentication.md). Pre-approved UCP signing keys at [`/.well-known/ucp`](/.well-known/ucp) `.signing_keys`.