MCP · protocol 2025-06-18
An agent can read the water and write a plan
POST JSON-RPC 2.0 to https://swellread.vercel.app/api/mcp. Eight typed tools, five of them mutating, all going through the same service layer and the same audit chain as this website.
Arguments
One-click calls
protocol
read and analysis
mutating tools
Mutating tools write through the same service layer the web UI uses, scoped to this browser's anonymous owner. create_session takes an idempotency key, so retrying it does not create a second session.
Responses · newest first
Nothing sent yet. Start with
initialize, then tools/list, then a mutating tool.Tool surface
What is actually exposed
| Tool | Kind | What it does |
|---|---|---|
| list_breaks | read | Returns the curated catalogue: coordinates, break type, peel orientation, reef slope, take-off depth, and whether a NOAA tide station is in range. |
| get_conditions | read | Fetches the normalised hourly slice for a break's local day from NOAA CO-OPS tide predictions and Open-Meteo marine/forecast data, with attribution and an honest live/fallback status. |
| analyse_break | read | Runs the swellread-engine/2026.10.1 deterministic engine on one hour and returns the score, band, every factor with its weight, contribution and human-readable arithmetic, hard gates, derived physics, the best window in the day, and the SHA-384 seal of the result. Pass tideM to ask a what-if question; it never changes stored data. |
| create_session | mutating | Freezes a real conditions snapshot and an engine verdict into a new session owned by the calling browser, and appends the first audit event. Safe to retry with the same idempotencyKey. |
| decide_session | mutating | Sets the in/out call and confidence on a session and appends a sealed audit event. |
| log_ride | mutating | Records a ride from the WebGL wave lab against a session. This is the same write path the lab's save button uses. |
| delete_session | mutating | Soft-deletes a session and keeps a tombstone plus its audit chain so the history stays replayable. |
| verify_integrity | read | Recomputes every SHA-384 seal in a session's chain from the genesis value and reports the first broken link, or that there is none. |
A ready-made manifest is published at /mcp.json, pointing at the live endpoint.
Scope and safety
What an agent may do to your data
- Owner scope: every tool acts on the anonymous HTTP-only cookie of the browser it was called from. An agent cannot read or delete another rider's sessions, because it has no way to name them.
- Idempotency:
create_sessionaccepts anidempotencyKey. Replaying the same key returns the original session instead of writing a second one. - No invented data: a tool that cannot reach a live source reports the source as
fallbackand drops any factor it cannot compute. - Rate limited: 120 JSON-RPC calls a minute per client, in memory, per serverless instance. That is a speed bump rather than a hard limit — see settings.
Point any MCP client at
https://swellread.vercel.app/api/mcp. The endpoint also answers GET with a discovery document listing every tool and a copy-pasteable example of each call.