hosannaith-mcp
Use this MCP server to learn how Hosannaith scores x402 endpoints and to buy reliability checks for one or many x402 URLs before routing payments to them.
Get free guidance on what Hosannaith returns and how to interpret/act on a reliability score.
Check a single x402 endpoint URL for its reliability score via a paid x402 USDC micropayment on Algorand.
Batch-check 1–50 x402 endpoint URLs in one paid call for a flat $7 USDC payment.
Requires
AVM_MNEMONICfor paid checks; target URLs must be public http(s) URLs.
Integrates with Algorand for x402 pay-per-call micropayments, enabling paid reliability checks and batch checks to be settled in USDC on Algorand mainnet or testnet via the GoPlausible facilitator.
Hosannaith
A pay-per-call x402 reliability oracle — live on Algorand Mainnet.
🔗 Live app: hosannaith.com · API: api.hosannaith.com ·
Repo: 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.
Related MCP server: fry-x402-mcp
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
{
"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 |
|
|
| 0–100 composite: 0.6 × uptime + 0.4 × correct-402 − a latency penalty (up to 20). |
| Probes where the endpoint was serving: reachable and not a 5xx. |
| Of the probes where the endpoint made a payment decision (a |
| Latency percentiles of serving probes. |
|
|
| Of the |
| Of those |
| Payment networks those |
| Like |
| Which Algorand mainnet id the endpoint offers: |
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 |
| = |
error rate |
| = 100 − |
protocol conformance |
| = |
latency |
| as above |
registry score |
|
|
Machine-readable contract
/openapi.json: OpenAPI 3.1 description of every route, with each paid route's x402 terms inx-x402.JSON Schemas (draft 2020-12):
/schema/check-result.json,/schema/batch-result.json,/schema/problem.json.Errors are RFC 9457 Problem Details (
application/problem+json). The402 Payment Requiredresponse 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. Format, verification and key policy: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:
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/ 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/ — published to npm as
hosannaith-mcp and listed in the official
MCP Registry 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:
{
"mcpServers": {
"hosannaith": {
"command": "npx",
"args": ["-y", "hosannaith-mcp"],
"env": { "AVM_MNEMONIC": "<25-word Algorand mnemonic, funded with USDC>" }
}
}
}See 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
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 dotenv2. Configure
cp .env.example .envThen edit .env:
AVM_ADDRESS— a testnet account funded with ALGO and opted in to testnet USDC.Leave
NETWORK=testnetand the GoPlausibleFACILITATOR_URLas-is for now.MONITOR_TARGETSalready 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)
pnpm monitor # terminal 1 — starts collecting observations immediately
pnpm dev # terminal 2 — starts the paid resource server on :4021Sanity checks:
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.jsonpins^2.26.0for@x402/core,@x402/avm, and@x402/hono; the Algorand discovery/Bazaar package@x402-avm/extensionsversions separately, currently^2.6.1— runpnpm lsfor exact resolved versions).Run
pnpm typecheckafterpnpm installto catch any API drift if you bump dependency versions.
Architecture as code
calm/hosannaith.architecture.json models Hosannaith in
FINOS CALM (nodes, relationships and the paid-check, monitoring and
verification flows), validated in CI with the official CALM CLI. See calm/README.md.
How Hosannaith relates to the FINOS AI Governance Framework
is set out in 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.
Machine-readable: /.well-known/security.txt.
License
Licensed under the Apache License, Version 2.0. See 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.
Available Tools
3 toolscheck_x402_reliabilityCheck an x402 endpoint reliability scoreA
Paid (small USDC payment via x402 on Algorand). Returns the Hosannaith reliability score for a target x402 endpoint URL so you can decide whether to trust it before routing payment to it. Requires the AVM_MNEMONIC environment variable on this server.
Inputs: targetUrl (required).
check_x402_reliability_batchBatch-check x402 endpoint reliabilityA
Paid (one small USDC payment via x402 on Algorand — $7 flat for up to 50 targets). Scores many x402 endpoints in a single call: pass a list of URLs, get a reliability score for each. Cheaper than checking each separately when you have a watchlist to vet before routing payments. Requires the AVM_MNEMONIC environment variable on this server.
Inputs: targetUrls (required).
get_hosannaith_infoAbout the Hosannaith reliability oracleA
Free. Explains what the Hosannaith x402 reliability oracle returns and how an agent should act on a score. Call this once before check_x402_reliability so you can interpret the result.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
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.
Maintenance
Related MCP Connectors
Programmatic web-scraping MCP server powered by x402 micro-transactions on Base.
Experimental MCP server for current empirical verification of explicit public HTTPS endpoint claims.
Broker + MCP server for last-bidder-wins on-chain games on Solana via x402 micropayments.
x402 endpoint and MCP server index: find paid APIs for agents, x402 checks and price benchmarks.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server that lets your AI coding agent (Claude Code, OpenClaw, Codex, Cursor, etc.) discover and pay on-chain agents registered on ERC-8004, using Coinbase's official x402 protocol. No smart account. No bundler. No relay. Just your EOA, an HTTPS request, and an automatic 402 → sign → retry flow.35MIT

fry-x402-mcpofficial
AlicenseAqualityDmaintenanceMCP server exposing fry.farm's x402 API as tools, enabling non-custodial blockchain interactions with pay-per-call endpoints on Algorand.17MIT- AlicenseNot gradedqualityDmaintenanceMCP server for the x402 protocol that lets AI agents discover and call payment-gated HTTP APIs automatically.Apache 2.0
- AlicenseNot gradedqualityCmaintenanceMCP server for the agentfeed-algo x402 API, enabling paid per-call access to cross-venue liquidation data on Algorand. Provides tools to query liquidation volumes, cascade scores, symbol coverage, exchange integrity, and manage payments from your own Algorand account.51 npmMIT