Skip to content

Latest commit

 

History

History
281 lines (223 loc) · 15.7 KB

hosted-mcp-endpoint.md

File metadata and controls

281 lines (223 loc) · 15.7 KB

The hosted MCP endpoint — https://modelmarket.dev/mcp

🟢 One URL. No wallet, no Docker, no clone.

   https://modelmarket.dev/mcp

Paste it into any MCP client and the marketplace comes down to two tools: market_search to find a capability, market_invoke to run one and get back the hub's signed receipt (direct tools for weather, air quality, sensors and randomness, pipelines and account_status come with them). A few trial invokes per caller are free. After that, one API key from modelmarket.dev/start, sent as the X-API-Key header of the same connection, pays priced calls from a prepaid USDC balance.

This is the shortest path from "never heard of this" to "I just invoked something on a live agent marketplace and hold a signed receipt for it". Everything else in the ecosystem — the factory, the oracles, the escrow, the verifier — is reachable from behind that one paste.


Add it to your client

Claude Desktop / Claude Code — claude_desktop_config.json:

{
  "mcpServers": {
    "aimarket": {
      "type": "streamable-http",
      "url": "https://modelmarket.dev/mcp"
    }
  }
}

Cursor — .cursor/mcp.json, same shape. Any other client: it speaks Streamable-HTTP MCP (JSON-RPC 2.0 over POST, SSE data: framing, Mcp-Session-Id), protocol version 2025-03-26.

A GET with Accept: text/event-stream answers 405 — this endpoint offers no server-initiated stream, and 405 is what the spec says to reply so a client stops looking for one. A plain GET returns an info document instead, for humans and monitoring.

By hand, to see it work before trusting it with a config file:

curl -s https://modelmarket.dev/mcp
curl -s -X POST https://modelmarket.dev/mcp -H 'content-type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

After the trial: one key on the connection

/start (five languages) does three things on one page:

  1. Key. POST /ai-market/v2/accounts behind a button: no email, the key starts at $0 and is shown once.
  2. Connection. The client config with the key already in it — Claude Code (claude mcp add --transport http aimarket https://modelmarket.dev/mcp --header "X-API-Key: aimk_…"), mcp.json with "headers": {"X-API-Key": "aimk_…"}, VS Code, Claude Desktop through mcp-remote, or plain HTTP.
  3. Top-up. USDC on Base from a browser wallet: the hub quotes an EIP-3009 authorization bound to this key's account, the wallet signs it and sends the transaction, the hub reads the chain and credits the account. The hub holds no key and pays no gas.

On the MCP side the gateway reads X-API-Key (or Authorization: Bearer aimk_…; a bearer of any other shape is never forwarded) and:

the key's balance what happens
covers the price the call is charged to the balance, no trial is spent
is short, or credits cannot buy this listing the free trial applies as if there were no key
short and trial spent 402 whose first next_steps line names the balance and the top-up page
the key is unknown 401 with a fix — no silent fallback to free calls

For clients that take only a URL and no header — the custom-connector box in claude.ai and Claude Desktop, ChatGPT developer-mode connectors, agent platforms — the same key goes in the path: https://modelmarket.dev/mcp/k/<key>. The hub cuts the key out of its access log and nginx logs a redacted request line, but treat that URL as a secret.

A keyed connection also lists account_status (balance, spent, top-up link). A keyless 402 names the key path first while signup is open, then the on-chain path.

A real run on Base mainnet — key, $1 top-up, a paid call — with every record and transaction: start-onboarding-demo.md.

The trial, precisely

⚠️ The allowance is per caller, and it is small on purpose

A few invokes per caller — the hub publishes the live number as free_trial.max_invokes_per_visitor in /.well-known/ai-market.json, which is the value to trust. It is keyed on an opaque digest of the caller's address; the address itself never reaches the hub's ledger. Spend them on something you actually want to see. After that every invoke answers 402 with the price and next_steps.

Free capabilities do not touch the allowance — the trial identity is attached only to priced ones. The hub consumes a trial before it ever looks at the price, so sending it unconditionally would both cap free capabilities at the trial allowance and replace the eventual 402 with a 429 trial_quota_exhausted that carries no price at all.

Why so little? Because the wallet friction downstream is deliberate — this is a crypto-native circuit and the trial is a taste, not a free tier. What the trial has to prove is only that the thing is real: a capability executed, and a receipt you can verify against the hub's published key at verify.modelmarket.dev.

Two things follow from one process serving everybody, and both are load-bearing:

why it matters
identity per caller one shared identity would spend the entire allowance on whoever arrived first, and 402 every stranger after — a reachable endpoint that demos nothing
address only from a trusted hop a forwarding header from an unlisted peer is ignored, so the allowance cannot be farmed by rewriting one request header

Both are pinned by tests in aimarket-hub/tests/test_mcp_gateway.py; the same properties for the self-hosted gateway are pinned in aimarket-mcp/tests/test_hosted.py.


Using it

market_search first — it returns the source_hub each capability lives on, and market_invoke needs that value verbatim for anything the hub does not execute itself. Most of the catalogue is federated, so an invoke without it looks locally and answers 404.

market_search  { "intent": "verifiable random number", "budget": 0.05 }
market_invoke  { "product_id": "prod-platon",
                 "capability_id": "platon.oracle@v1",
                 "source_hub": "https://oracles.modelmarket.dev/family",
                 "input": {} }

Each search match also carries input — the fields the capability's input object takes (type, description, whether required) — and max_price_usd, the cent-ceiled total to paste into market_invoke unchanged.

The invoke returns a compact result: the capability's output, what you were charged (charged_usd, 0 on the trial), the list price, the trial counter, and a receipt summary (the signed fields, the Ed25519 signature, and the provenance receipt_url / verify_url). The ML-DSA-65 half of the hybrid signature is about 7 KB, so it is summarised as its digest and length; pass include_full_receipt: true for the hub's raw response. Paid callers pass payment_channel (+ payment_channel_secret, and payment_authorization for escrow channels), or an on-chain x402 payment as x_payment (the transaction hash) + x_payment_nonce (the invoice nonce from the 402) + x_payment_secret (the 402's payment_secret), and are never placed on the trial tier. The secret is what shows the caller is the one who paid: once the payment is mined its transaction hash and nonce are public, and the hub refuses a bound payment without the secret whose sha256 is the nonce. The gateway checks that x_payment_secret is 0x + 64 hex and passes it on as X-Payment-Secret, only together with x_payment. A 402 leads with next_steps: what the 402 actually offers, in the order an agent can act. For an on-chain invoice that names the retry in full — x_payment=<transaction hash>, x_payment_nonce=… and, when the 402 carried one, x_payment_secret=… — with a reminder to keep the secret to yourself until you redeem.

Direct tools

A model calls a tool when the user's task matches its name. Two marketplace tools match no task, which is why ~240 clients in 15 days listed the tools and two called one. So the gateway also lists a few tools named after the need, whenever this hub can route the capability behind them (each maps to one catalogued capability; same trial, price ceiling and receipts as market_invoke):

tool capability input
weather_now gaia.weather.read@v1 latitude+longitude, or city
air_quality_now gaia.air.read@v1 latitude+longitude, or city
nearby_sensors atlas.nearest.read@v1 latitude, longitude, optional layers, max_km
fair_random sortes.draw@v1 seed, optional num_bytes

Their definitions are written in the gateway, not generated from the catalogue: a peer-controlled description in tools/list would be a tool-poisoning channel into every connected model. initialize also returns instructions saying what the server is for. The funnel is counted as aimarket_hub_mcp_requests_total{method,tool,client} (client families from an allowlist, never raw names or addresses).


Two paths, one protocol

https://modelmarket.dev/mcp pip install aimarket-mcp
install none a package, or a container
tools market_search, market_invoke, plus the direct tools above market_search, market_invoke, web_fetch, web_search, metis_verify
hub this one any, via AIMARKET_HUB_URL
trial identity derived per caller one per installation
for trying it, and agents that just want the market self-hosting, and pointing at your own hub

https://modelmarket.dev/ai-market/mcp is the same gateway under its older path. It stays because peers read it out of mcp_endpoint in the well-known manifest; humans should be given the short one.


Operating it

The endpoint is the hub itself — no separate service, port, container or certificate. aimarket_hub/mcp_gateway.py is mounted twice by create_app: once under /ai-market for peers, once at the apex for people.

Deploy is therefore just a hub deploy. Use scripts/deploy_hub_rebuild.sh on the hub host: it copies the live container's environment into the new one, refuses to start if the payment interlock did not survive the copy, verifies /mcp and payment_configured before declaring success, and rolls back automatically if either fails. That refusal exists because a hub redeploy has twice silently switched payments off (payment-enable-runbook.md).

Watch it with scripts/payment_canary.py, which asserts from outside that a priced capability still answers 402, that the manifest still says payment_configured, and that /mcp still answers with a per-caller trial:

scripts/payment_canary.py --publish /var/www/verify.modelmarket.dev/status.json

Exit 1 means a critical check failed; exit 2 means the report could not be published (a missing directory must not read like a payment regression, since cron sees only the code). Stdlib only — no venv needed on the host.

It probes the cheapest priced capability of each provider, because enforcement is not one switch: AIMARKET_SELLS_FOR decides it per federated peer and the local branch has a gate of its own. Probing one capability is how a $0.03 atlas capability came to be served free while the oracle family was correctly answering 402.

It also probes each peer's liveness, separately, because the payment checks are structurally blind to it — the hub answers 402 before it ever contacts the provider, so a priced capability reads as perfectly gated while the satellite behind it is down.

🔴 A served manifest is not a live satellite

On 2026-08-16 GAIA answered /.well-known/ai-market.json with a clean 200 while its invoke endpoint hung. Every gaia capability returned 502 through the hub for the whole outage, and a manifest-only check would have called it healthy. The liveness probe therefore asks the peer's own /ai-market/v2/invoke for a capability that cannot exist: any HTTP answer means the service is serving, and only silence counts as dead. It is retried once, so a single blink does not page anyone.

It deliberately does not use the mcp_endpoint the peer advertises. Trusting that value reported three healthy peers as dead, because magic-ai-factory.com publishes http://localhost:9080/… to the whole internet — the probe dialled its own machine. That advertisement is itself reported, as a warning: no peer can route an invoke to it.

Peers that carry priced capabilities fail the run; the rest only warn. The published JSON carries a peers array alongside the prose checks, so a dead satellite names exactly one host — the shape a node agent's allowlisted restart command already takes.

To install it on the hub host — copy the script beside the build tree first, then schedule it (MAILTO matters: on a box with no mail transport the output goes nowhere):

scp scripts/payment_canary.py factory-vps:/root/aicom-hub-build/payment_canary.py
ssh factory-vps "( crontab -l 2>/dev/null; echo '[email protected]'; echo '17 6 * * * /usr/bin/python3 /root/aicom-hub-build/payment_canary.py --publish /var/www/verify.modelmarket.dev/status.json' ) | crontab -"

Once a day is the right cadence: the failure it watches for is introduced by a redeploy, not by traffic, and a check that runs constantly is a check whose mail gets filtered.

🔴 payment_configured: true is not evidence that anyone is being charged

Those two facts came apart once already — the flag was true while forty-two federated capabilities were free to call. The canary probes behaviour, not the manifest's opinion of itself, and its tests in tests/test_payment_canary.py assert that a hub serving paid work for free fails the check.

Configuration

variable where effect
AIMARKET_TRUSTED_PROXIES hub which peers may name a caller, matched by exact string. Unset means every limit keys on the peer the hub sees — the whole internet in one bucket, and one shared trial identity. In a container the peer is the docker bridge gateway, not 127.0.0.1: scripts/deploy_hub_rebuild.sh reads it from docker network inspect and sets both.
AIMARKET_INTERNAL_BASE hub where the MCP gateway posts its own invoke. Loopback (http://127.0.0.1:9083) on purpose: routed through the public URL, nginx appends its own hop and the caller the gateway named is discarded.
AIMARKET_MCP_PUBLIC self-hosted aimarket-mcp only explicit opt-in that lets a production deployment answer anonymous callers. Production without it stays fail-closed.
AIMARKET_MCP_TRUSTED_PROXIES self-hosted aimarket-mcp only same idea, and loopback only by default. A containerised deployment behind nginx must name the bridge gateway (172.17.0.1, or its CIDR); trusting the private ranges by default would let any host on the same network name any caller.
AIMARKET_MCP_LOCAL_RELAY self-hosted aimarket-mcp only unset. Without a key, a caller on this machine counts as local only if its socket belongs to the server's user and its process is not a relay (a proxy or tunnel program such as nginx, caddy, cloudflared or ssh, or a process that listens on a non-loopback address). 1 takes this user's relays for local again (since 0.6.4).
AIMARKET_MCP_LOCAL_UNVERIFIED self-hosted aimarket-mcp only unset. Where the socket owner cannot be read (macOS, Windows) keyless access is refused; 1 takes loopback callers for local there (since 0.6.4).
AIMARKET_MCP_VISITOR_SALT self-hosted aimarket-mcp only pin it to keep trial allowances across restarts; unset re-rolls them on every boot.