This page as Markdown, byte for byte: /agents.md

Craton for AI agents#

You may be an agent working for an underwriting team, a program designer, a broker, a corporate risk manager — or for a developer building for one of them. This page is written for you. It is short on ceremony and exact about requests, because the two things visiting agents most often lose time to are guessing hosts and guessing request bodies.

Craton is an API for building insurance software: one canonical risk object, seven verbs, an open schema, an open model registry. You can design a trigger-based product, replay it across forty seasons of pinned history, read a technical price with every assumption attached as a field, compose a pricing model from validated primitives, and watch a live structure — all through plain HTTP, no SDK.

The two hosts#

Requests for documentation go to the docs host. Requests that create or read product state go to the API host. Nothing else exists.

Fetching a docs path on the API host answers 401 or 404; it means the host is wrong, not that the page moved. The API host is reachable inside the operator's tailnet today; api.oncraton.com follows once its edge protections land, and this page will name it the day it does.

One transport courtesy that is actually a requirement: send a descriptive User-Agent header. The edge in front of the public hosts refuses the anonymous default-library agents (Python-urllib, and friends) with a 403 before any of our code runs; a named agent passes.

A key in one call#

curl -s -X POST https://altier.ridgehead-hamlet.ts.net:8472/signup \
  -H 'Content-Type: application/json' \
  -d '{"label": "my-agent"}'

The 201 answer carries api_key.secret (cede_sk_...). The secret appears in that response only. Store it, then send it on every other call as Authorization: Bearer <secret>. Free sandbox plan, no payment details, no human in the loop. Unknown members in the body are refused with a 422, not ignored — send label or nothing.

The verbs, precisely#

Every request body shape below is documented on a page whose examples are extracted verbatim and executed against the live product on every change — they cannot rot. Read the page before you compose the request; the 422s in our walk logs are all guessed bodies.

Objects come first: POST /objects stores the canonical risk object that every verb reads. The complete worked path from nothing to a priced, backtested structure is quickstart; composing a pricing model from registry primitives is model-builder.

A 202 answer is an async job: poll the Location header (/jobs/{id}) until status is succeeded or failed; the result is embedded in the terminal job document. Everything else answers synchronously.

Why this platform rewards agent work#

• Determinism you can verify. Models make no network calls at run time; every result names the feed version and the SHA-256 of the exact bytes it read. Re-run a backtest a year later and it replays byte for byte.
• Run ids are content addresses. A run id is derived from the document it identifies — check a result rather than trusting a caption.
• Assumptions as fields. Model versions, data vintages, event sets and loadings arrive beside every number, machine-readable.
• Docs that execute. Any example you read here ran against the live product on the current release. Raw markdown at /{page}.md; the index at /llms.txt.
• One error envelope. Refusals are structured JSON with a code and a message (errors); 401 means the key, 422 means the body, 429 carries Retry-After, and rate-limit headers arrive on every answer.
• Receipts. A published run you can reproduce digest-for-digest: receipts.

Connecting over MCP#

Craton also serves its tools over the Model Context Protocol — thirteen tools from create_api_key through run_backtest to compose_model, each dispatching against the REST API above. The endpoint is stateless Streamable HTTP, plain JSON, no auth dance: get a key with the create_api_key tool and pass it as the api_key argument (or send it as a Bearer header).

Endpoint: https://altier.ridgehead-hamlet.ts.net:8475/mcp

Claude Code:

claude mcp add --transport http craton https://altier.ridgehead-hamlet.ts.net:8475/mcp

Project .mcp.json:

{
  "mcpServers": {
    "craton": {
      "type": "http",
      "url": "https://altier.ridgehead-hamlet.ts.net:8475/mcp"
    }
  }
}

Cursor (~/.cursor/mcp.json) takes the same object under mcpServers; VS Code (.vscode/mcp.json) uses the top-level key servers. The host above is reachable inside the operator's tailnet today; a public hostname follows with the production deployment, and claude.ai custom connectors need that public hostname.

Where Craton stops#

Craton outputs technical prices, never quotes; it drafts terms, never offers; it cannot bind, issue, endorse, claim or settle. It holds no money and never touches paper. What you build here is analysis and drafts; execution belongs to the people you work for and their own capacity.