Calibrated decisions as tools for AI agents. Hesperan 1 is a decision model, not a text generator: it reads a state (text or JSON) and answers typed questions with a probability for every possible answer. Agents use it for decisions with known options, such as routing, triage, policy or risk checks, or "should I proceed?", and act automatically only when the probability is high enough.

Two ways to connect, with the same tools:

Remote (no install): https://api.hesperan.com/mcp, Streamable HTTP, header Authorization: Bearer hsp_… (or x-api-key: hsp_…). Tools can be listed without a key; calling them needs one.
Local stdio (this package): npx -y hesperan-mcp with HESPERAN_API_KEY in the environment

You need an API key: sign in at hesperan.com (1M free tokens a month, no card), then open Console → API keys.

Tools

Tool	What it does
`decide`	Ask one or more typed questions about a state. `choice` picks one of named options, `noul` gives the probability that a statement is true, `score` rates on an ordinal scale you define. Returns probabilities for every answer.
`decide_with_profile`	Run one of your decision profiles, a question calibrated on your own labelled cases with a target precision. Returns the decision, its calibrated confidence and `action`: `auto` (act on it) or `review` (a person decides). An optional `idempotency_key` makes retries safe: a repeat within 24 hours returns the first decision and is not charged again.
`report_outcome`	Record the correct answer for an earlier profile decision, so the console tracks the live precision.

Example decide arguments:

{
  "state": "Hi, I was charged twice for order #48213. Please refund the second charge.",
  "questions": {
    "team":   { "type": "choice", "instructions": "Which team should handle this ticket?",
                "criteria": { "billing": "payments, refunds", "shipping": "delivery, tracking", "technical": "app errors, login" } },
    "urgent": { "type": "noul", "instructions": "The customer has lost money and needs a reply today." }
  }
}

The result is the API response: { "answers": { "team": { "choice": "billing", "probabilities": { … } }, "urgent": { "noul": … } }, … }.

Setup

Claude Code

# remote
claude mcp add --transport http hesperan https://api.hesperan.com/mcp --header "Authorization: Bearer $HESPERAN_API_KEY"
# or local
claude mcp add hesperan --env HESPERAN_API_KEY=hsp_… -- npx -y hesperan-mcp

Claude Desktop

claude_desktop_config.json (Settings → Developer → Edit config):

{
  "mcpServers": {
    "hesperan": { "command": "npx", "args": ["-y", "hesperan-mcp"], "env": { "HESPERAN_API_KEY": "hsp_…" } }
  }
}

Cursor

~/.cursor/mcp.json or .cursor/mcp.json:

{
  "mcpServers": {
    "hesperan": { "url": "https://api.hesperan.com/mcp", "headers": { "Authorization": "Bearer ${env:HESPERAN_API_KEY}" } }
  }
}

Codex

codex mcp add hesperan --url https://api.hesperan.com/mcp --bearer-token-env-var HESPERAN_API_KEY

or in ~/.codex/config.toml:

[mcp_servers.hesperan]
url = "https://api.hesperan.com/mcp"
bearer_token_env_var = "HESPERAN_API_KEY"

Other clients

Any client with Streamable HTTP and custom headers can use the remote endpoint. Otherwise run the stdio server: command: npx, args: ["-y", "hesperan-mcp"], env: { HESPERAN_API_KEY }.

Variable
`HESPERAN_API_KEY`	API key (`hsp_…`), required for tool calls. The server starts without it so clients can list the tools.
`HESPERAN_BASE_URL`	API base URL, default `https://api.hesperan.com`

Requires Node.js 20 or newer. The server supports MCP 2025-11-25 (and earlier) clients as well as the stateless 2026-07-28 protocol.

Billing and errors

Tool calls are ordinary API requests with your key, billed by input tokens (the state once plus each question with its options once): first from the tokens your plan includes this month, then from your prepaid balance. decide and decide_with_profile are billed that way, report_outcome is free, and failed calls are not charged. Pricing: hesperan.com/pricing.

Hesperan 1 runs on serverless GPUs. The first call after a quiet period starts the model and can take about 2–3 minutes, or answer 503 "model is starting" with Retry-After; later calls skip that wait while the model is warm.

Errors come back as tool errors that say whether a retry makes sense. Rate limits (429) and a model that is still starting (503 with Retry-After) are retryable. An invalid key (401) or used-up tokens without enough balance (402) need the user. A 503 "opens soon" (without Retry-After) means the API is closed; it is not retryable.