API & MCP
Everything a person can do on Puttopia, a program or AI agent can do with the same inputs and get the identical result.
HTTP API
GET https://puttopia.usefulweb.app/api/v1/tools– catalogGET https://puttopia.usefulweb.app/api/v1/tools/{id}– inputs, output schema, examplesPOST https://puttopia.usefulweb.app/api/v1/tools/{id}/calculate– run a toolGET https://puttopia.usefulweb.app/api/v1/workflows·POST https://puttopia.usefulweb.app/api/v1/workflows/{id}/run- OpenAPI 3.1: /openapi.json · /openapi.yaml
- Errors:
application/problem+json;422includes per-fielderrors.
Tools on Puttopia
- Minigolf Shot Simulator – Simulate one putt on a Puttopia hole: path, bounces, portals, water and whether it drops.
puttopia_shot_simulator - Minigolf Hole Checker – Check a minigolf hole: playable, estimated par and how many putts a perfect caddie needs.
puttopia_hole_check - Wheel Spinner with Weights – Spin a wheel with weighted segments — exact odds, provable result.
fieldday_wheel_spinner
Every result contains
inputs (normalised, defaults applied), summary, result (validated against the published schema), units, assumptions, sources, warnings, computedAt and links.
MCP (Model Context Protocol)
- Streamable HTTP endpoint:
https://puttopia.usefulweb.app/mcp– protocol revisions 2026-07-28 (stateless) and 2025-11-25 / 2025-06-18 / 2025-03-26 (initialize handshake). - Tools:
puttopia_shot_simulator,puttopia_hole_check,fieldday_wheel_spinner - Local stdio connector:
node src/mcp-stdio.ts
{
"mcpServers": {
"usefulweb": { "type": "http", "url": "https://puttopia.usefulweb.app/mcp" }
}
}