MCP Gateway v4.0 + v2.1 Guardians

One endpoint — https://hypermove.duckdns.org/api/mcp — makes cross-chain web3 agent-callable. 40 tools today (verified live via /api/mcp/health): search + catalog discovery, daily news + AI insight, tiered multi-chain payment, XRPL/Flare/GOAT builder briefs and deep reads, confidential compute, and Dream Cycle — an offline memory-consolidation pipeline agents use to learn from their own episode logs. WorkOS or wallet sign-in, 5 free queries / 24h, then metered $0.001–$0.10 via x402/MPP. As of 2026-08-01, every tool call also passes through Gateway Guardians (deterministic cost caps + circuit breaker + prompt-injection defense) — enforcement lives in code, not in a prompt.

The whole gateway lives behind FEATURE_HYPERMOVE_MCP_GATEWAY_V1. When off, /api/mcp serves the legacy 2-tool surface unchanged (60-second rollback). Every capability below ships behind its own additional sub-flag, documented inline — flip any one off without touching the others.

Tools (40, grouped by purpose)

Discovery — always on

Payments (n-payment, x402/MPP)

Live cross-chain reads

News + agentic synthesis — FEATURE_MCP_NEWS_V1 / FEATURE_MCP_AGENTIC_V1

Agent-skills discovery — FEATURE_HYPERMOVE_TOOLS

Skills install and run in your own workspace — the gateway is not their execution host. See "Agent-skills" below.

Builder briefs — FEATURE_MCP_BUILDER_BRIEF

XRPL deepening — FEATURE_MCP_XRPL_V3

xrpl.vault.info / xrpl.lending.status never return a raw RPC error while XLS-65/66 is still mid-vote — they return a structured {ok:false, reason:'amendment_not_active'} instead, so an agent can branch on it deterministically.

Flare — FEATURE_MCP_FLARE_V1

Confidential compute — FEATURE_MCP_CONFIDENTIAL_V1

Flare Compute Extension + Token Profiles — FEATURE_MCP_INSTRUCT_V1 / FEATURE_MCP_TOKEN_PROFILE_V1

flare.token.save is verified end-to-end (see Gateway Guardians below) — its own handler output is checked before it ships.

Dream Cycle — offline memory consolidation — FEATURE_MCP_DREAM_CYCLE

Dream reads and ingestion are unmetered. start_dream requires a Dream-tier payment whenever MCP auth and the paywall are enabled; its per-cycle budget_usd remains an independent cost guardrail.

When FEATURE_MCP_DREAM_PAYMENT_BINDING=true, first call start_dream without payment to receive a quote. Submit the quoted RLUSD payment with its nonce memo, then retry the same call with X-Payment-Quote-Id, X-Payment, X-Payment-Chain, and X-Payment-Asset. The quote is bound to the authenticated user and agent_id. guardrail, not the gateway's free-tier metering. See "Dream Cycle" below for the full learn-loop walkthrough.

Gateway Guardians — deterministic enforcement (2026-08-01)

Every tool call above now passes through two code-level checks before and after dispatch — not prompt instructions an LLM could ignore, but the same sentinel.ts + output-enforcer.ts modules the platform-layer observability stack already used, now wired directly into /api/mcp's dispatch path:

FEATURE_MCP_GUARDIANS=true    # default — sentinel pre-call check + record, per-tool verify
FEATURE_MCP_GUARDIANS=false   # opt-out — byte-identical to the pre-2026-08-01 gateway

Pre-call: cost caps (per-agent daily/hourly USD), a circuit breaker (opens after a sliding-window error-rate threshold), an optional endpoint allowlist, and a prompt-injection heuristic scan the call arguments. A blocked call never reaches the tool handler and returns:

{ "error": { "code": -32000, "message": "blocked by guardian policy",
             "data": { "policy": "cost_cap", "reason": "daily_cap_exceeded" } } }

Post-call (opt-in per tool): a handler's own output can be checked against a declared contract (schema / nonempty / JSON-serializable / math) before the result ships to the caller. Most tools declare nothing and are unaffected; flare.token.save is the one tool wired today as a live example — its response envelope's ok field is verified present before the caller ever sees it.

This is independent of FEATURE_HM_PLATFORM (the broader observability/sentinel layer used elsewhere in the app, off by default) — FEATURE_MCP_GUARDIANS alone controls whether /api/mcp enforces, so turning MCP guardrails on does not require opting into the whole platform-observability stack. Admin sessions bypass the check the same way they bypass metering. Full detail: docs/observability.md in the repo.

Dream Cycle — how an agent learns across sessions

Dream Cycle turns an agent's own past episode logs into small, durable, retrievable memories — without an LLM in the read path and at near-zero cost:

# 1 — log what happened (zero LLM calls, idempotent per episode_id)
curl -s https://hypermove.duckdns.org/api/mcp -H 'authorization: Bearer <token>' -d '{
  "jsonrpc":"2.0","id":1,"method":"tools/call",
  "params":{"name":"submit_episode_log","arguments":{
    "agent_id":"robot-42",
    "episodes":[{"episode_id":"ep-1","agent_id":"robot-42","timestamp":"2026-08-01T10:00:00Z",
                 "steps":[{"action":"grip","result":"timeout"}],"outcome":"failure"}]
  }}}'
 
# 2 — run the pipeline (preprocess -> cluster -> extract -> consolidate -> prune),
# bounded by budget_usd — never spends more than this per call, independent of the
# gateway's own free-tier metering.
curl -s https://hypermove.duckdns.org/api/mcp -H 'authorization: Bearer <token>' -d '{
  "jsonrpc":"2.0","id":2,"method":"tools/call",
  "params":{"name":"start_dream","arguments":{
    "agent_id":"robot-42","config":{"budget_usd":0.05,"preset":"balanced"}
  }}}'
 
# 3 — ask what it learned, any time later
curl -s https://hypermove.duckdns.org/api/mcp -H 'authorization: Bearer <token>' -d '{
  "jsonrpc":"2.0","id":3,"method":"tools/call",
  "params":{"name":"query_dream","arguments":{"agent_id":"robot-42","query":"gripper timeout"}}}'

config must be nested exactly as shown — {agent_id, config: {budget_usd, preset}}, not flattened. preset is one of frugal | balanced | thorough; outcome in an episode is one of success | failure | timeout (no partial — map ambiguous outcomes to the closest of the three). get_dream_stats reports the same cost/token figures the gateway's own per-call audit ledger (mcp_calls.tokens_used / cost_usd, added 2026-08-01) records for that start_dream call — the two are guaranteed to agree, since they're written from the same run.

Resources and prompts compose on top of the tools above (FEATURE_MCP_RESOURCES): hypermove:///agents/{agent_id}/dream/{summary,rules,errors,stats} and the dream/summarize_today, dream/suggest_policy_updates, dream/compare_before_after prompt templates.

Agent-skills install & run locally — MCP is optional

HyperMove agent-skills are self-contained:

1. Fetch a skill's SKILL.md from GET /api/skills/<name>?format=md (or the skills.install tool above).
2. Save it into your host's skills directory.
3. It autoloads and runs in your own workspace by following its procedure — no MCP connection required.

The gateway above is only for the external-protocol layer: connect it when a skill needs live cross-chain data (data.call) or a payment (payments.settle). Browse the catalog at GET /api/skills.

1 — Connect your wallet (required by default)

/api/mcp requires a key — there is no anonymous free tier.

hypermove.duckdns.org/mcp-connect is the fastest path:

• Connects your wallet.
• Has you sign one free message (no gas).
• Issues a bearer token from that signature.

Email-only sign-in via WorkOS is also available from the same page for users without a wallet. No wallet and no browser at all? See Get a key — no wallet needed for a terminal-only flow.

# Wallet flow happens in-browser at /mcp-connect. Scripted equivalent (WorkOS):
open https://hypermove.duckdns.org/api/mcp/authorize
# → WorkOS AuthKit → /api/mcp/callback → redirects to /mcp-connect?token=…
# (send `Accept: application/json` to get { "token": "…" } back instead of the redirect)

Both FEATURE_HYPERMOVE_MCP_GATEWAY_V1=true and FEATURE_MCP_AUTH_WORKOS=true must be set — the master flag alone routes to the legacy 2-tool surface, which never checks auth.

Local dev needs no WorkOS: set HYPERMOVE_DEV_UNAUTHENTICATED=true and call from localhost.

2 — Search (free tier: 5 / 24h)

curl -s https://hypermove.duckdns.org/api/mcp \
  -H 'authorization: Bearer <token>' \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"search","arguments":{"query":"token balances base","limit":5}}}'

Every response follows the envelope contract — read payloads via .data:

{ "ok": true, "data": { "hits": [ /* … */ ], "total": 5, "nextSteps": "…" } }
// on failure:
{ "ok": false, "error": { "service": "moralis", "kind": "soft-empty", "message": "…", "hint": "…" } }

kind: "soft-empty" means the service returned nothing — NOT an error. Never treat it as absence.

3 — Daily news + insight

# search today's news
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"news.search","arguments":{"query":"restaking"}}}'
# AI insight for one project
-d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"codemode.news.insight","arguments":{"project":"x402"}}}'

4 — Choose a network, then pay

Discover options, then select chain + rail + asset via headers:

# what can I pay on?
-d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"codemode.payments.networks","arguments":{}}}'
 
# after the free tier, the gateway returns JSON-RPC error -32402 with an x-payment-required
# challenge listing chains + assets + amounts. Select and pay:
curl -s https://hypermove.duckdns.org/api/mcp \
  -H 'authorization: Bearer <token>' \
  -H 'x-payment-chain: xrpl-mainnet' \
  -H 'x-payment-rail: x402' \
  -H 'x-payment-asset: RLUSD' \
  -H 'x-payment: <signed-proof>' \
  -d '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"search","arguments":{"query":"nft"}}}'

One settlement opens a session bundling 100 queries at that tier — per-query gas stays viable.

Rollback runbook (under 60s)

1. Set FEATURE_HYPERMOVE_MCP_GATEWAY_V1=false (or flip any single sub-flag) in the host env.
2. Redeploy / restart. /api/mcp immediately returns to the legacy 2-tool surface.
3. No data is dropped — flags never touch tables or sessions.

Sub-flags for partial rollback: FEATURE_MCP_AUTH_WORKOS, FEATURE_MCP_RATE_LIMIT, FEATURE_MCP_PAYWALL, FEATURE_MCP_DATA_ADAPTERS_V1, FEATURE_MCP_VECTOR_SEARCH, FEATURE_MCP_NEWS_V1, FEATURE_MCP_AGENTIC_V1, FEATURE_HYPERMOVE_TOOLS, FEATURE_MCP_BUILDER_BRIEF, FEATURE_MCP_XRPL_V3, FEATURE_MCP_FLARE_V1, FEATURE_MCP_CONFIDENTIAL_V1, FEATURE_MCP_INSTRUCT_V1, FEATURE_MCP_TOKEN_PROFILE_V1, FEATURE_MCP_DREAM_CYCLE, FEATURE_MCP_RESOURCES, FEATURE_MCP_GUARDIANS.

Health & spec (public, no auth)

curl https://hypermove.duckdns.org/.well-known/webmcp.json  # manifest: tools, endpoints, auth mode
curl https://hypermove.duckdns.org/api/mcp/health   # { ok, gateway_enabled, tools[], commit, deployed_at }
curl https://hypermove.duckdns.org/api/mcp/spec     # OpenAPI-3.1-style super spec

/api/mcp/health's commit / deployed_at fields let you confirm which build is actually live before trusting any "should be fixed now" claim — check it first.