Aimarket Oracle Gateway README

aimarket-oracle-gateway — MCP server

🔄 Synced from the AI-Factory monorepo (append-only history). Pull requests are welcome — merged PRs are imported back and re-synced here. Issues · Pull requests

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, 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`
Extended tool surface	`aimarket_oracle_gateway/mcp_tool_surface.py`
Glama / Docker run	`Dockerfile`, `glama.json`

A passthrough MCP server — the discovery + consumption storefront for the entire oracle-as-a-service specs. 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.

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:

Terminal

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:

Terminal

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="<source_hub from the selected catalog result>"
AIMARKET_HUB_URL=https://modelmarket.dev python -m aimarket_oracle_gateway.stdio_server

Claude Desktop (mcpServers entry):

config.json

{ "mcpServers": { "aimarket-oracle-gateway": {
  "command": "python", "args": ["-m", "aimarket_oracle_gateway.stdio_server"],
  "env": {
    "AIMARKET_HUB_URL": "https://modelmarket.dev",
    "AIMARKET_SOURCE_HUB": "<source_hub from the selected catalog result>"
  } } } }

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

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/