# aimarket-oracle-gateway โ MCP server
> ๐ Synced from the [AI-Factory monorepo](https://github.com/alexar76/aicom) (append-only history). **Pull requests are welcome** โ merged PRs are imported back and re-synced here. [Issues](https://github.com/alexar76/aimarket-oracle-gateway/issues) ยท [Pull requests](https://github.com/alexar76/aimarket-oracle-gateway/pulls)
**One MCP server. Seventeen oracle families. Pay-per-call.**
Transport: **stdio** (`aimarket_oracle_gateway/stdio_server.py`). Built with the official
**Model Context Protocol** Python SDK ([`mcp`](https://github.com/modelcontextprotocol/python-sdk), `FastMCP`).
Compatible hosts: Claude Desktop, Cursor, Glama, and any MCP client that supports stdio servers.
| Item | Location |
|------|----------|
| MCP entrypoint | `aimarket_oracle_gateway/stdio_server.py` |
| Tool routing core | [`aimarket_oracle_gateway/gateway_core.py`](aimarket_oracle_gateway/gateway_core.py) |
| Extended tool surface | [`aimarket_oracle_gateway/mcp_tool_surface.py`](aimarket_oracle_gateway/mcp_tool_surface.py) |
| Glama / Docker run | [`Dockerfile`](Dockerfile), [`glama.json`](glama.json) |
---
A **passthrough MCP server** โ the discovery + consumption storefront for the entire
[oracle-as-a-service specs](https://github.com/alexar76/aicom/blob/main/docs/specs/README.md). One server, **35 oracle capabilities plus a free discovery tool** (36 MCP tools), every result
**independently verifiable** (signatures, VDF proofs, classical certificates, deterministic replay).
## Tools (35 capabilities plus discovery)
| Category | MCP tool | capabilityId | price |
|----------|----------|--------------|-------|
| **Randomness** | `get_random` | `platon.random@v1` | $0.004 |
| | `get_randomness_beacon` | `platon.beacon@v1` | $0.004 |
| | `ask_oracle` | `platon.ask@v1` | $0.003 |
| | `verify_random` | `platon.verify@v1` | $0.001 |
| **Delay** | `compute_vdf` | `chronos.eval@v1` | $0.01 |
| | `verify_vdf` | `chronos.verify@v1` | $0.001 |
| **Reputation** | `get_reputation_scores` | `lumen.reputation@v1` | $0.005 |
| | `get_agent_trust` | `lumen.score@v1` | $0.003 |
| | `verify_reputation` | `lumen.verify@v1` | $0.002 |
| **Consensus** | `aggregate_values` | `murmuration.aggregate@v1` | $0.002 |
| **Thermodynamics** | `audit_compute_cost` | `landauer.audit@v1` | $0.01 |
| | `verify_compute_cost` | `landauer.verify@v1` | $0.001 |
| **Routing** | `compute_least_time_route` | `fermat.route@v1` | $0.01 |
| | `verify_least_time_route` | `fermat.verify@v1` | $0.001 |
| **Cascade risk** | `analyze_cascade_risk` | `ablation.cascade@v1` | $0.01 |
| | `verify_cascade_risk` | `ablation.verify@v1` | $0.001 |
| **Sampling** | `get_quasirandom_sequence` | `lattice.sequence@v1` | $0.002 |
| | `get_blue_noise` | `turing.bluenoise@v1` | $0.002 |
| **Optimization** | `optimize_route` | `colony.optimize@v1` | $0.005 |
| **Resilience** | `analyze_network_resilience` | `percola.threshold@v1` | $0.01 |
| | `verify_network_resilience` | `percola.verify@v1` | $0.001 |
| **Randomness** | `sortes_draw` | `sortes.draw@v1` | $0.006 |
| | `sortes_verify` | `sortes.verify@v1` | $0.001 |
| **Learning** | `gauss_field` | `gauss.field@v1` | $0.006 |
| | `gauss_suggest` | `gauss.suggest@v1` | $0.006 |
| | `gauss_verify` | `gauss.verify@v1` | $0.001 |
| **Time-lock** | `aestus_seal` | `aestus.seal@v1` | $0.006 |
| | `aestus_open` | `aestus.open@v1` | $0.01 |
| | `aestus_verify` | `aestus.verify@v1` | $0.001 |
| **Topology** | `betti_homology` | `betti.homology@v1` | $0.008 |
| | `betti_distance` | `betti.distance@v1` | $0.004 |
| **Transport** | `kantor_transport` | `kantor.transport@v1` | $0.006 |
| | `kantor_verify` | `kantor.verify@v1` | $0.001 |
| **Spectral** | `fourier_spectrum` | `fourier.spectrum@v1` | $0.005 |
| | `fourier_verify` | `fourier.verify@v1` | $0.001 |
| **Discovery** | `list_oracle_capabilities` | โ | free |
### Subscription tiers (optional Hub bundles)
High-volume tools also advertise monthly bundles in `list_oracle_capabilities`:
| Tool | Starter | Pro |
|------|---------|-----|
| `aggregate_values` | 10k calls / $10 | 100k / $50 |
| `get_reputation_scores` | 5k / $20 | 50k / $100 |
| `audit_compute_cost` | 10k / $15 | 100k / $75 |
| `compute_least_time_route` | 10k / $25 | 100k / $120 |
| `analyze_cascade_risk` | 5k / $50 | 50k / $250 |
Pay-per-call remains the default; bundles are Hub-side packaging.
## Configure (env)
| var | meaning |
|-----|---------|
| `AIMARKET_HUB_URL` | AIMarket Hub base URL โ **recommended**: metered + paid |
| `AIMARKET_SOURCE_HUB` | Copy the selected Hub search result's `source_hub` for federated oracles; defaults to `local` |
| `AIMARKET_ORACLE_URL` | direct oracle-family URL (if no hub) โ demo/free path |
| `AIMARKET_PAYMENT_CHANNEL` | optional pre-opened payment channel id |
| `AIMARKET_PAYMENT_CHANNEL_SECRET` | per-channel debit secret |
| `AIMARKET_API_TOKEN` | optional bearer token |
| `AIMARKET_MAX_PER_CALL_USD` | hard cap per call (default `0.10`) |
| `AIMARKET_MAX_SPEND_USD` | hard cumulative budget (default `5.0`) |
| `AIMARKET_PRICE_TOLERANCE` | reject overcharge vs advertised (default `0.10`) |
If neither URL is set the server fails closed with a clear message.
**Payment safety (spec 03):** spending caps are enforced client-side and cannot be overridden by a
prompt-injected agent. See [docs/specs/03-mcp-payment-and-security.md](https://github.com/alexar76/aicom/blob/main/docs/specs/03-mcp-payment-and-security.md).
Hub invokes include `max_price_usd`, bounded by the per-call limit, remaining budget,
and advertised-price tolerance. A supporting Hub checks this ceiling before work or
payment. The Gateway also rejects an over-limit response and preserves an explicit
zero price. Direct oracle endpoints do not use the Hub's atomic ceiling contract;
the client-side response checks alone cannot undo work or charges at a provider.
## Run
Install the published server:
```bash
pip install aimarket-oracle-gateway==0.3.3
```
Set `AIMARKET_HUB_URL` and, for a federated result, `AIMARKET_SOURCE_HUB` as above,
then run `aimarket-oracle-gateway`. For a source checkout instead:
```bash
pip install -r requirements-mcp.txt && pip install --no-deps -e .
# Set this to the exact source_hub returned by the Hub's oracle search.
export AIMARKET_SOURCE_HUB=""
AIMARKET_HUB_URL=https://modelmarket.dev python -m aimarket_oracle_gateway.stdio_server
```
Claude Desktop (`mcpServers` entry):
```json
{ "mcpServers": { "aimarket-oracle-gateway": {
"command": "python", "args": ["-m", "aimarket_oracle_gateway.stdio_server"],
"env": {
"AIMARKET_HUB_URL": "https://modelmarket.dev",
"AIMARKET_SOURCE_HUB": ""
} } } }
```
## Test MCP startup locally
From this package directory, in an environment with the package's runtime and `dev`
dependencies installed:
```bash
python -m pytest tests/test_stdio_startup.py tests/test_stdio_schema.py -q
```
The startup regression launches the real stdio server in a separate process, completes
`initialize` and all `tools/list` pages, and checks the full catalogue, reported version
and constrained schemas. It uses an isolated directory and a clean environment, with
network connections and child processes denied. It does not invoke oracle tools or require
API credentials. Process lifetime and cleanup are bounded.
Release 0.3.1 could exit before `initialize`: postponed annotations left function-local
aliases such as `ValuesList` as strings that FastMCP could not resolve. Release 0.3.2
evaluates annotations in `mcp_tool_surface.py` when the nested functions are defined,
preserving their types and validation constraints. Keep these registrar annotations
evaluated; an import-only check does not cover the complete stdio startup lifecycle.
Release 0.3.3 adds the outbound Hub price ceiling, preserves zero-priced responses,
enforces the actual per-call cap independently of quote tolerance, and accepts the
federated source through `AIMARKET_SOURCE_HUB`. A strict ceiling can refuse a
cent-rounded Hub admission quote; it never silently raises the configured budget.
Direct oracle providers do not implement this Hub ceiling contract.
## Publish on Glama
Listing: **[glama.ai/mcp/servers/alexar76/aimarket-oracle-gateway](https://glama.ai/mcp/servers/alexar76/aimarket-oracle-gateway)**
## Verifiability
- **Platon** โ Ed25519 signature over `(random_hex โ proof)`
- **Chronos** โ Wesolowski VDF proof, cheap `verify_vdf`
- **LUMEN** โ re-derive PageRank from committed graph
- **Murmuration** โ deterministic re-aggregation from input values
- **Landauer** โ bit-for-bit erasure count from ops DAG + `circuit_commitment`
- **Fermat** โ dual certificate `T(v)` checked in O(E)
- **Ablation** โ sandpile replay, order-independent `topple_total` + `tau`
- **Lattice / Turing** โ deterministic from `(count, dim, skip)` / `seed`
- **Colony** โ admissible `lower_bound` + `gap` certificate
- **Percola** โ recomputable percolation sweep + `f_c`
- **Sortes** โ ECVRF 80-byte proof, verifiable offline by anyone (RFC 9381)
- **Gauss** โ deterministic replay of GP posterior + Expected-Improvement suggestion
- **Aestus** โ RSW time-lock puzzle re-derivable; modulus factorization burned each seal
- **Betti** โ recomputable Vietoris-Rips persistence diagram + bottleneck distance
- **Kantor** โ Kantorovich dual potentials checked in O(m*n) without re-solving
- **Fourier** โ recomputable Laplacian spectrum + Fiedler value `lambda-2`
## Tests
```bash
PYTHONPATH=. pytest tests/
```