API & MCP Documentation

Every calculator on Stupidly Clever is available as a REST endpoint and an MCP tool, running the exact same logic as its web page. This page is the human on-ramp — the full endpoint reference lives in the API reference below.

Get an API keyFree tier includes 1,000 calls/month — no card required.

Quick start

Get an API key

Make your first call

Every parameter goes in the query string for GET endpoints:

curl "https://api.stupidlyclever.com/v1/mortgage?homePrice=400000&downPayment=80000&annualRate=6.5&termYears=30" \
  -H "Authorization: Bearer YOUR_API_KEY"

See the response

Every endpoint returns the same envelope shape — a result object plus meta:

{
  "result": {
    "monthlyPayment": 2022.62,
    "totalPayment": 728142.36,
    "totalInterest": 408142.36,
    "loanAmount": 320000,
    "currency": "USD",
    "schedule": [ /* year-by-year amortization */ ]
  },
  "meta": { "computedAt": "2026-08-05T12:00:00.000Z" }
}

Using it from an AI agent (MCP)

Every REST endpoint has a matching tool on the MCP server at https://api.stupidlyclever.com/mcp. It speaks Streamable HTTP, so any MCP-compatible client — Claude, the OpenAI Responses API, or a custom agent built on the MCP SDK — can connect to it directly and call any of the 160+ tools without you writing integration code. Authentication is the same Bearer API key as the REST API, sent as a header on the MCP connection.

Use with the OpenAI Responses API

Add this to the request's tools array:

{
  "type": "mcp",
  "server_url": "https://api.stupidlyclever.com/mcp",
  "server_label": "stupidly_clever",
  "headers": { "Authorization": "Bearer YOUR_KEY" }
}

To explore the tool list directly or verify a connection, use the MCP Inspector:

npx @modelcontextprotocol/inspector@latest --cli \
  --transport http --server-url https://api.stupidlyclever.com/mcp \
  --method tools/list

Data provenance

Any response built on a reference dataset carries a top-level provenance array saying what that data actually is. Read it before you build on a number: some of these datasets are the publisher's own figures, and some are curated approximations that resemble them.

sourced — the publisher's own figures.
derived — computed by us from a real source, using the stated method.
illustrative — a curated estimate approximating the named publisher. Not their published figures, and not citable as them.

For derived and illustrative datasets the method field states in one sentence how the values were produced. MCP tool results carry the same array, and a tool whose data is illustrative says so in its description. The full catalogue is on the data sources page.

"provenance": [
  {
    "dataset": "ppp_factors",
    "status": "illustrative",
    "publisher": "World Bank International Comparison Program (ICP)",
    "method": "Curated estimates approximating World Bank ICP PPP conversion factors ...",
    "vintage": "2023 approximate",
    "lastVerified": "2026-08-29"
  }
]

Reference

Interactive API reference
Every route, parameter, and response schema, generated from the live OpenAPI 3.1 spec (openapi.json). This is the canonical reference — the source of truth for every parameter type, default, and example.
Postman collection
Every endpoint, pre-filled with realistic example values, organized by category. Search "Stupidly Clever" on the Postman Public API Network once the listing goes live — linked here as soon as it's published.
Code examples on GitHub
OpenAI Responses API examples in JavaScript and Python, once the repository is public. Linked from this page's MCP section above.

Authentication

Every REST and MCP request needs an API key, sent as Authorization: Bearer YOUR_API_KEY. Requests without a valid key return 401.

Get a key from the pricing page — the free tier requires no card. The web calculators on stupidlyclever.com call these same endpoints directly from your browser without a key; a key is only needed for your own external requests.

Rate limits

Limits reset monthly and are enforced per API key.

Free	1,000 calls / month
Starter	50,000 calls / month
Pro	500,000 calls / month

Error reference

Failed requests return { "error": "..." } with one of these HTTP status codes.

400Bad Request

A required parameter was missing, or a value was malformed (wrong type, out of range, invalid enum value).

Handle it: Check the response body — { "error": "..." } names the specific parameter and what was wrong with it. Fix the request and retry; retrying without changing anything will fail the same way every time.

401Unauthorized

No API key was sent, or the key sent is invalid, revoked, or expired.

Handle it: Confirm the Authorization: Bearer YOUR_API_KEY header is present and the key is current — copy it fresh from the dashboard if unsure.

429Too Many Requests

The API key's monthly call quota for its plan has been used up.

Handle it: Wait for the monthly reset, or upgrade the plan for a higher quota. The response includes the limit and how many calls have been used.

500Internal Server Error

Something failed on our end, not because of the request — a bug, or an upstream dependency (e.g. a live data source) being unavailable.

Handle it: Retry after a short delay. If it persists across several minutes, it's worth reporting to support@stupidlyclever.com with the endpoint and approximate time.