Hesper Atlas for AI agents

A Model Context Protocol endpoint for the public historical replay, row-level static-tail and rolling walk-forward evidence, version provenance, append-only publication commitments and the latest completed end-of-day signal snapshot. The public evidence layer needs no credential; exact forward rows and the current action layer need a subscription.

1Connect

The transport is Streamable HTTP: one stateless POST carrying JSON-RPC 2.0. There is no stream to open, no session to keep and, in the current protocol, no initialize handshake. MCP clients handle the request metadata automatically. A plain HTTP client can discover the server like this:

curl -s https://hesperatlas.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: server/discover' \
  -d '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{
        "io.modelcontextprotocol/protocolVersion":"2026-07-28",
        "io.modelcontextprotocol/clientInfo":{"name":"curl","version":"1"},
        "io.modelcontextprotocol/clientCapabilities":{}}}}'

Every current-protocol request repeats that _meta block and sends matching MCP-Protocol-Version and Mcp-Method headers. A tools/call request also sends Mcp-Name. This makes each request independently routable and prevents a proxy and the application from interpreting different operations.

HTTPS browser agents are supported through CORS preflight. The server echoes the validated origin and allows the MCP, content-type and authorization headers, but never enables cookie credentials: public tools remain anonymous and subscriber tools require an explicit OAuth access token or developer API key.

Subscriber account connection

OAuth-capable clients discover the authorization flow from /.well-known/oauth-protected-resource/mcp. Hesper Atlas implements authorization code with mandatory PKCE S256, exact MCP resource binding, dynamic public-client registration, one-hour access tokens and rotating refresh tokens. The consent page authorizes only signals:read; the token is refused on every account, billing and non-MCP route.

If an anonymous call selects a subscriber tool, its error result carries _meta["mcp/www_authenticate"], so a compatible client can open sign-in and consent instead of asking the user to copy a secret.

Developer API-key fallback

For clients that cannot complete OAuth, create a read-only API key on the account page and add one header. Nothing else changes.

curl -s https://hesperatlas.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/call' \
  -H 'Mcp-Name: get_signal' \
  -H 'Authorization: Bearer hsp_live_...' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"get_signal","arguments":{"symbol":"NVDA"},"_meta":{
         "io.modelcontextprotocol/protocolVersion":"2026-07-28",
         "io.modelcontextprotocol/clientInfo":{"name":"curl","version":"1"},
         "io.modelcontextprotocol/clientCapabilities":{}}}}'

In an MCP client that takes a remote server URL, add https://hesperatlas.com/mcp as a Streamable HTTP server. Let the client follow OAuth when it asks for a subscriber tool, or set the developer bearer key manually if OAuth is unavailable. Current clients may use server/discover; domain-level discovery metadata also lives at /.well-known/mcp.json. 2025-era clients remain supported through their automatic initialize / notifications/initialized flow.

2Discovery files

3The tools

For automation, treat action and suggested_position as authoritative. The confirmed state can still read LONG during the interval after price crosses a published sell line and before the closing-bar engine transition is recorded; in that case the tool returns action: EXIT, recommended_state: FLAT and target position 0. Entry clocks are named explicitly: current_leg matches the public replay window, while first_entry covers the longer active trend.

Calling a subscriber tool anonymously returns a structured subscription payload plus MCP OAuth challenge metadata. A compatible client can connect the user; a model can still explain the price, sign-up URL and free alternatives without inventing a result.

4Trust and provenance fields

Every successful data tool returns a compact trust contract alongside its actual result. Read these fields before presenting a number:

The historical replay applies today’s engine rules retrospectively over up to five years of end-of-day data. It includes winners, losses and open replay positions, but it remains separate from validation and from the append-only forward ledger. get_heldout_evidence exposes all 152 static-tail rows and records that later research reused the tail, so it is validation, not a pristine unseen test. get_walk_forward_evidence is stricter: each annual choice is fit only through the preceding year, then scored on the following calendar year. It deliberately retains names and years where the adaptive selector lagged holding or the champion-free base, rechecks the frozen input files before publication, and embeds the exact component hashes behind its calculation version.

The forward ledger begins when the feature is deployed; there is no retroactive reconstruction. Public callers can inspect each verified commitment and a compact maturity summary: total snapshots, distinct market dates, the first and latest dates, the latest revision, instrument count and change counts. The summary deliberately returns performance_status: not_calculated_from_commitments: a hash proves what was stored, not whether it later made money. Subscribers can retrieve exact frozen rows or ask for changes after a stable publication id. Those hashes detect later alteration within the published chain, but Hesper Atlas has no independent timestamp authority or third-party signer configured; get_provenance says so explicitly. A symbol marked unavailable was absent from that scan snapshot; that alone does not prove it left the universe.

5OAuth and developer keys

OAuth is the consumer connection path. The user signs into Hesper Atlas in their browser, sees the requesting client by name, approves read-only access, and can disconnect that client from the account page. Access tokens live for one hour. Refresh tokens live for 30 days, rotate on every use, and a replayed refresh token revokes its entire token family.

API keys remain available for developer clients that cannot run OAuth. They are shown once, stored only as cryptographic hashes, capped at ten per account and independently revocable.

Both credential types unlock current signals, exact frozen forward rows and change-since queries only at /mcp. Neither can cancel a subscription, change billing, delete an account, create credentials or place trades. OAuth additionally binds every token to the exact https://hesperatlas.com/mcp resource.

6Limits and fair use

• 120 calls per minute per connected OAuth client or API key. Without a credential, 40 per minute per address.
• Every response is served from a completed local snapshot. Nothing an agent can call triggers even a background recomputation. Time-sensitive payloads carry as_of, last_updated and data-type fields.
• One subscription covers one user's own agents. Republishing the paid signal layer, or fanning it out to third parties, is what the terms call redistribution and it is not covered. The free tools carry no such restriction: quote the replay with its caveats, and please cite it.

7What the API deliberately does not return

No raw price history. Every field is Hesper Atlas's own derived output: signals, dates, returns, statistics. If you need candles, use a market-data vendor; that is their product, not ours.

No personalized advice, from any tool. The engine does not know your portfolio, tax position, horizon or risk tolerance, and its output is an impersonal publication. Every payload carries a disclaimer field for exactly this reason: relay it.