(Docs)

MCP server

Give any agent that speaks the Model Context Protocol (Claude, Cursor, Codex and others) Hesperan as a tool. It asks typed questions and gets probabilities back, then acts when they are high enough and asks the user when they are not.

Two ways to connect

	Remote	Local (stdio)
Address	`https://api.hesperan.com/mcp`	`npx -y hesperan-mcp`
Transport	Streamable HTTP	stdio, Node.js 20+
Key	`Authorization: Bearer hsp_…`	`HESPERAN_API_KEY`
Use when	the client supports remote servers with headers	the client only runs local servers

Both offer the same tools and use your API key. Create one under Console → API keys and keep it in an environment variable, not in a config file you share.

Claude Code

Remote

claude mcp add --transport http hesperan https://api.hesperan.com/mcp \
  --header "Authorization: Bearer $HESPERAN_API_KEY"

Local

claude mcp add hesperan --env HESPERAN_API_KEY=$HESPERAN_API_KEY -- npx -y hesperan-mcp

Claude Desktop

In Settings → Developer → Edit config, add the local server to claude_desktop_config.json and restart Claude:

claude_desktop_config.json

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

Cursor

~/.cursor/mcp.json

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

Codex

Shell

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

~/.codex/config.toml

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

Other clients

Use the remote address if your client supports Streamable HTTP with custom headers. Otherwise run the local server with command npx, arguments -y hesperan-mcp and HESPERAN_API_KEY in its environment. Set HESPERAN_BASE_URL to use a different API address. The server supports clients on MCP 2025-11-25 and earlier as well as the stateless 2026-07-28 protocol.

Tools

Tool	Arguments	Returns
`decide`	`state` (text or JSON) and named `questions` of type `choice`, `noul` or `score`, as in judgment types	The API response: a probability for every answer of every question
`decide_with_profile`	`profile` (slug), `state`, optional `idempotency_key` for safe retries	`decision`, calibrated `confidence`, `action` auto or review, `decision_id`. See decision profiles
`report_outcome`	`decision_id` and the correct `actual` option	`{ "ok": true }`

An agent checking a shell command before it runs it would call decide with:

decide arguments

{
  "state": "About to run: rm -rf ./build ./dist in the repo root",
  "questions": {
    "risky": { "type": "noul", "instructions": "This command could delete work the user wants to keep." },
    "kind":  { "type": "choice", "instructions": "What does the command do?",
               "criteria": { "cleanup": "removes build output",
                             "destructive": "removes source or data",
                             "other": "anything else" } }
  }
}

The tool descriptions tell the agent what Hesperan is for: decisions with known options, not writing text or answering knowledge questions. They also tell it to act only above a threshold and hand everything else to the user.

Billing and errors

Every tool call is an ordinary API request with your key, so the same billing and limits apply. decide and decide_with_profile are billed by input tokens, and report_outcome is free. Failed calls are not charged.

API status	The agent is told
400	Which argument is invalid; do not retry unchanged.
401	The key is missing, unknown or revoked; the user needs a valid key.
402	Out of tokens; the user tops up the balance or subscribes to Pro.
429	Rate limit; retry after the given number of seconds.
502 / 503	Temporarily unavailable; retry with backoff (honouring Retry-After).

Listing the tools works without a key, so clients and registries can see what the server offers. Tool calls need a valid key, as Authorization: Bearer hsp_… or, for hosts that can only set that header, x-api-key: hsp_…. Without one, /mcp answers HTTP 401. If a key is sent, it must be valid.