hosannaith-mcp
# Hosannaith
**A pay-per-call x402 reliability oracle — live on Algorand Mainnet.**
🔗 **Live app:** [hosannaith.com](https://hosannaith.com) · **API:** `api.hosannaith.com` ·
**Repo:** [github.com/cameron4316/x402-oracle-server](https://github.com/cameron4316/x402-oracle-server)
## The problem
As x402 turns APIs into pay-per-request services, agents increasingly pay endpoints they didn't
build — with no way to know if an endpoint is actually reliable before sending real USDC. Dead or
misbehaving endpoints silently waste money and break automated flows.
## What it does
Hosannaith is itself an x402 endpoint. It independently and continuously monitors other x402
endpoints and sells a verified reliability score on demand: uptime, correct `402` behaviour, and
latency percentiles, backed by real accumulated history — with every response flagging its
confidence (`"history"` for a stood-behind score, `"one-shot"` for a target queried for the first
time). It's x402 monitoring x402.
```
GET https://api.hosannaith.com/reliability?target=<x402-endpoint-url>[&windowHours=24|168|720]
```
`windowHours` picks the history window: 24 hours (default), 168 (rolling 7 days) or 720 (rolling
30 days). The 7- and 30-day windows are the ones FINOS OpenEAGO Appendix D specifies for
`reliability_score`, `error_rate`, `latency_p99_ms` (7 days) and `availability_pct` (30 days). The
batch route takes the same value as `"windowHours"` in its JSON body.
Unpaid requests get `402 Payment Required` with payment instructions; paid requests settle in
USDC on Algorand via the GoPlausible facilitator and return JSON like:
> **Verifiable on-chain:** first mainnet settlement —
> [`3F2ATV3NCRVOI45IEL6OUKAWED3NQX246WJADESJB5CFR6LIXGCQ`](https://allo.info/tx/3F2ATV3NCRVOI45IEL6OUKAWED3NQX246WJADESJB5CFR6LIXGCQ)
```json
{
"target": "https://x402.example.com/api",
"status": "pass",
"score": 98.7,
"detail": {
"observations": 1439,
"windowHours": 24,
"uptimePct": 100,
"correct402Pct": 100,
"p50LatencyMs": 88,
"p95LatencyMs": 127,
"p99LatencyMs": 210,
"confidence": "history",
"availability_pct": 100,
"error_rate_pct": 0,
"protocol_conformance_pct": 100,
"score_normalized": 0.987
}
}
```
### Reading the result
| Field | Meaning |
|---|---|
| `status` | `pass` (score ≥ 90) · `degraded` (60–89) · `fail` (< 60) · `unknown` (not enough data) |
| `score` | 0–100 composite: 0.6 × uptime + 0.4 × correct-402 − a latency penalty (up to 20). `null` below 5 observations. |
| `uptimePct` | Probes where the endpoint was serving: reachable and not a 5xx. |
| `correct402Pct` | Of the probes where the endpoint made a payment decision (a `402`, or serving an unpaid `2xx`), the share that correctly answered `402`. Other `4xx` (e.g. a `400` because our probe sends no input) are indeterminate and excluded. `null` if no probe was determinate. |
| `p50/p95/p99LatencyMs` | Latency percentiles of serving probes. `p99LatencyMs` is `null` below 20 samples (it would just be the slowest one); below 20 samples `p95LatencyMs` equals the slowest sample. |
| `confidence` | `history` (accumulated monitoring) · `one-shot` (first sighting, one live probe, `score: null`) · `pending` (batch only: no history yet, now enrolled). |
| `mainnetPayablePct` | Of the `402`s that recorded their x402 payment requirements (`paymentRequirementsSamples`), the share whose requirements parse and name a known mainnet. A `402` alone proves gating, not that the endpoint can be paid on a mainnet (some answer with testnet-only requirements). Informational: not part of the score. |
| `discoverablePct` | Of those `402`s, the share carrying the x402 bazaar discovery extension. Informational, never a score input. |
| `acceptedNetworks` | Payment networks those `402`s named, as sent (CAIP-2 ids or x402 v1 names). The monitored endpoint chooses this text, so only well-formed network ids are repeated; anything else is left out. |
| `currentSdkPayablePct` | Like `mainnetPayablePct`, but counting only network ids the **current** x402 SDK accepts. Since `@x402/core` / `@x402/avm` 2.29.0 the SDK refuses Algorand's legacy full-genesis-hash id, so an endpoint offering only that id for Algorand is payable by older clients but not by up-to-date ones. |
| `algorandIdForm` | Which Algorand mainnet id the endpoint offers: `spec` (32-character CAIP-2 form), `legacy` (full genesis hash), `both`, or `null`. Offering `both` serves every client during the transition. |
### OpenEAGO SLO view
The same numbers in the SLO vocabulary used by agent registries and SLA/SLO feasibility checks.
These are pure aliases (no new measurement) and are `null` exactly when their source is `null`.
| SLO term | Field | Definition |
|---|---|---|
| availability | `availability_pct` | = `uptimePct` |
| error rate | `error_rate_pct` | = 100 − `uptimePct`: % of probes that were 5xx or unreachable (server-side errors). Client-side 4xx are indeterminate for an unpaid probe and are not counted. |
| protocol conformance | `protocol_conformance_pct` | = `correct402Pct`: % of gating-determinate probes that returned 402 rather than serving unpaid 2xx. |
| latency | `p50LatencyMs`, `p95LatencyMs`, `p99LatencyMs` | as above |
| registry score | `score_normalized` + `confidence` | `score` / 100, in [0, 1] |
### Machine-readable contract
- [`/openapi.json`](https://api.hosannaith.com/openapi.json): OpenAPI 3.1 description of every route, with each paid route's x402 terms in `x-x402`.
- JSON Schemas (draft 2020-12): [`/schema/check-result.json`](https://api.hosannaith.com/schema/check-result.json), [`/schema/batch-result.json`](https://api.hosannaith.com/schema/batch-result.json), [`/schema/problem.json`](https://api.hosannaith.com/schema/problem.json).
- Errors are [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) Problem Details (`application/problem+json`). The `402 Payment Required` response is the x402 protocol's own.
- Timestamps are RFC 3339 in UTC. Responses are additive-only: new optional fields may appear; existing fields never change name, type or meaning.
- **Signed results:** when signing is enabled, every result (and every batch, as a whole) carries an ES256 signature over its RFC 8785 canonical JSON, verifiable against [`/.well-known/hosannaith-keys.json`](https://api.hosannaith.com/.well-known/hosannaith-keys.json). Format, verification and key policy: [`docs/attestation.md`](docs/attestation.md).
## Use it in your own code
A small TypeScript SDK wraps the full x402 pay-per-call handshake (402 → sign USDC payment →
retry) so you don't have to implement it yourself:
```ts
import { getReliability } from 'hosannaith-client';
const result = await getReliability('https://some-x402-endpoint/api', {
mnemonic: process.env.AVM_MNEMONIC!, // 25-word Algorand mnemonic, funded with USDC
});
console.log(result.score, result.detail.confidence);
```
See [`sdk/typescript/`](sdk/typescript/) for the client, a runnable example, and full usage docs.
## Use it from any MCP agent (Model Context Protocol)
This repo also ships an **MCP server** in [`mcp/`](mcp/) — published to npm as
[`hosannaith-mcp`](https://www.npmjs.com/package/hosannaith-mcp) and listed in the official
[MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.cameron4316/hosannaith-mcp`.
It lets any Model Context Protocol client (Claude Desktop, Cursor, and other MCP agents) vet an
x402 endpoint's reliability before paying it.
Built on the official MCP TypeScript SDK (`@modelcontextprotocol/sdk`), it exposes three **MCP
tools**:
- `get_hosannaith_info` — free; explains the score shape and how to act on it.
- `check_x402_reliability` — paid; reliability score for one endpoint, settled as an x402 USDC
micropayment on Algorand.
- `check_x402_reliability_batch` — paid; score up to 50 endpoints in a single call.
Add it to an MCP client's config:
```json
{
"mcpServers": {
"hosannaith": {
"command": "npx",
"args": ["-y", "hosannaith-mcp"],
"env": { "AVM_MNEMONIC": "<25-word Algorand mnemonic, funded with USDC>" }
}
}
}
```
See [`mcp/`](mcp/) for the MCP server, its tools, and full setup docs.
There is also a **hosted remote MCP server** at `https://api.hosannaith.com/mcp` (Streamable HTTP,
paid per call via x402 MCP). Its tools carry MCP annotations (paid tools: read-only, not destructive,
not idempotent, open-world; the one side effect is that a target with no history gets one live probe
and is enrolled for monitoring). Every call is recorded in an audit log with its on-chain settlement,
or the quote offered when no payment was made; payment payloads and URL query strings are never
logged.
Targets must be public http(s) URLs. Private, loopback, link-local and reserved addresses, internal
host names and URLs with credentials are refused before any payment, on the HTTP API and both MCP
servers. When probing, every redirect hop is checked, host names are resolved first, and the
connection can only go to the addresses that were checked, so a public URL cannot redirect or
resolve a probe into a private network, even if its DNS answer changes a moment later. A batch that
contains a refused target is rejected as a whole and never charged.
## Architecture and vision
The architecture is deliberately **pluggable**: every paid product implements the `Check`
contract (see `src/checks/types.ts`). Reliability ships first; a **compliance/attestation**
product for tokenization — the trust layer institutions need to bring real-world assets on-chain —
is planned as a second `Check` + one route entry, with no rewrite of the payment plumbing.
The **monitor** (`pnpm monitor`, run continuously on the production droplet) records one
observation per target per interval, append-only, to `data/observations.jsonl`. That history
compounds and cannot be reconstructed later — every score above is backed by real, continuous
observation, not a synthetic estimate.
---
## For developers
Everything below is setup/reference for running Hosannaith locally (defaults to testnet) or
understanding the codebase — not required to use the live API above.
---
## 1. Install
```bash
pnpm install
# runtime deps (exact packages from the official Algorand tutorial):
pnpm add @x402/core @x402/avm @x402/hono @x402-avm/extensions hono @hono/node-server dotenv
```
## 2. Configure
```bash
cp .env.example .env
```
Then edit `.env`:
- `AVM_ADDRESS` — a **testnet** account funded with ALGO and opted in to testnet USDC.
- Leave `NETWORK=testnet` and the GoPlausible `FACILITATOR_URL` as-is for now.
- `MONITOR_TARGETS` already points at the Foundation's public example endpoint.
Testnet setup (accounts, faucets, USDC opt-in) follows the official tutorial:
https://dev.algorand.co/resources/x402-on-algorand/
## 3. Run (two terminals)
```bash
pnpm monitor # terminal 1 — starts collecting observations immediately
pnpm dev # terminal 2 — starts the paid resource server on :4021
```
Sanity checks:
```bash
curl http://localhost:4021/health # -> {"ok":true,...} (free)
curl -i "http://localhost:4021/reliability?target=https://x402.goplausible.xyz/examples/weather"
# -> HTTP 402 Payment Required (correct: it's a PAID route)
```
To pay and get the JSON back, point the tutorial's client at
`http://localhost:4021/reliability?target=...` (client code:
https://dev.algorand.co/resources/x402-on-algorand/#part-1-build-the-client).
---
## File map
```
src/
index.ts Hono app + x402 wiring (edit sparingly)
monitor.ts Standalone monitor process (pnpm monitor)
config.ts Network/asset/facilitator config; testnet<->mainnet switch
routes.config.ts Paid routes + Bazaar discovery metadata <-- add compliance route here
checks/
types.ts The pluggable Check contract (shared by all products)
registry.ts Maps check id -> implementation
reliability/
monitor.ts probe() + startMonitor()
store.ts Observation type + append-only JSONL store (swappable)
score.ts Turns observations into a 0-100 score
index.ts The reliability Check (reads store, computes score)
data/
observations.jsonl Append-only history (git-ignored; compounding)
```
## Algorand network ids: both forms, during the transition
Algorand has two CAIP-2 ids in use for each network. The spec form (`algorand:` plus the first 32
characters of the genesis hash) is what `@x402/avm` exports as `ALGORAND_MAINNET_CAIP2` /
`ALGORAND_TESTNET_CAIP2`, and since `@x402/core` / `@x402/avm` 2.29.0 (`x402-foundation/x402` #3894)
it is the only form the x402 SDK accepts. The legacy full-genesis-hash form is what the GoPlausible
facilitator originally required (reported in `x402-foundation/x402` #3528). The facilitator now lists
the spec form first and still accepts the legacy form until it is switched off with notice.
So every 402 from this server offers **both**, spec form first, otherwise identical (same price,
payTo, asset and tag): clients on current SDKs pay the spec form, and older installs of our own
clients keep paying the legacy form. `src/config.ts` imports the spec form from `@x402/avm` and checks
at startup that it is exactly the legacy form truncated to 32 characters. The legacy option will be
dropped, and this server's `@x402` packages upgraded to 2.29+, in step with the facilitator's
switch-off. Paid settlements on both ids are verified on mainnet.
To run this server against mainnet yourself: set `NETWORK=mainnet` and `AVM_ADDRESS` to a
**fixed** payTo address opted in to mainnet USDC (ASA `31566704`, already set in `src/config.ts`).
The `tag` field in `routes.config.ts`'s `extra` attributes activity to the Algorand Global x402
Challenge.
## Notes
- Tracks x402 protocol `2.26.0` (`package.json` pins `^2.26.0` for `@x402/core`, `@x402/avm`, and
`@x402/hono`; the Algorand discovery/Bazaar package `@x402-avm/extensions` versions separately,
currently `^2.6.1` — run `pnpm ls` for exact resolved versions).
- Run `pnpm typecheck` after `pnpm install` to catch any API drift if you bump dependency versions.
## Architecture as code
[`calm/hosannaith.architecture.json`](calm/hosannaith.architecture.json) models Hosannaith in
[FINOS CALM](https://calm.finos.org) (nodes, relationships and the paid-check, monitoring and
verification flows), validated in CI with the official CALM CLI. See [`calm/README.md`](calm/README.md).
How Hosannaith relates to the [FINOS AI Governance Framework](https://github.com/finos/ai-governance-framework)
is set out in [`docs/aigf-mapping.md`](docs/aigf-mapping.md): which mitigations apply, the evidence,
what is not done, and what does not apply. The same mitigations are attached to the CALM model as
controls.
## Security
To report a vulnerability, email security@hosannaith.com or use GitHub's private vulnerability
reporting. Please don't open a public issue. Scope and what to expect: [SECURITY.md](SECURITY.md).
Machine-readable: [`/.well-known/security.txt`](https://api.hosannaith.com/.well-known/security.txt).
## License
Licensed under the [Apache License, Version 2.0](LICENSE). See [NOTICE](NOTICE).
This repository was previously MIT-licensed. Code and npm releases published under MIT before the
change (`hosannaith-client` 0.3.0 and earlier, `hosannaith-mcp` 0.2.1 and earlier) remain
available under the MIT License.
TDQS
Scored across 3 tools
Each tool has a clearly distinct role: one provides documentation, one checks a single endpoint, and one checks many endpoints in a batch. There is no overlap in purpose, so an agent can easily choose the right tool.
All names use snake_case and follow a verb_noun style, with the batch tool predictably extending the single-check name. The only minor inconsistency is the differing verbs 'get' and 'check', but the meanings remain clear.
Three tools perfectly match the narrow scope of a reliability oracle: an info tool, a single-check tool, and a batch-check tool. Each earns its place without redundancy or bloat.
The surface covers the core workflow—learn how to interpret scores, check one endpoint, and check many endpoints. A minor gap is the lack of per-score detail or historical lookup, but agents can still complete the primary task.