Routavo MCP

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Free text when you do not know the capability name, e.g. \"turn an address into coordinates\" or \"will it rain tomorrow\". Matched against names, aliases, tags and descriptions; results come back ranked with a score."
    },
    "capability": {
      "type": "string",
      "description": "What you need done, e.g. \"geocode\" or \"forecast\". Omit to list everything."
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "required": [
    "providers",
    "count",
    "routing"
  ],
  "properties": {
    "count": {
      "type": "integer"
    },
    "routing": {
      "type": "object"
    },
    "providers": {
      "type": "array",
      "items": {
        "type": "object"
      }
    }
  }
}

{
  "type": "object",
  "properties": {
    "plan": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "maxItems": 8,
      "description": "Instead of one call, a sequence of up to 8 steps: [{ id, capability | provider, arguments, max_price?, max_latency_ms? }]. A later step may take a value from an earlier one with { \"$ref\": \"<step id>.output.<path>\" }, e.g. { \"$ref\": \"geo.output.results[0].lat\" }. The whole plan is quoted before anything runs; with dry_run it is only quoted. Steps run in order and stop at the first failure. Each step returns its own receipt and the response carries one total."
    },
    "batch": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "maxItems": 50,
      "description": "Instead of one arguments object, up to 50 of them for the same capability or provider. Run in parallel, each with its own receipt, one total. Failed items cost nothing and do not stop the others."
    },
    "budget": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "max": {
          "type": "string"
        },
        "statement": {
          "type": "boolean"
        }
      },
      "description": "A task budget: { id, max }. Spend under this id is tracked across any number of calls, plans and batches, and a call that would take it past max is refused with code \"budget\". { id, statement: true } returns what the budget has spent and the receipts behind it.",
      "additionalProperties": false
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Return only these output paths, e.g. [\"results.name\", \"results.lat\", \"results.lng\"]. Saves tokens; the receipt still hashes the full answer."
    },
    "quorum": {
      "type": "integer",
      "maximum": 3,
      "minimum": 2,
      "description": "Ask 2 or 3 providers the same question and get an agreement score with every answer. Each provider is charged. Refused if fewer providers clear your constraints, so quote it first with dry_run."
    },
    "recipe": {
      "type": "string",
      "description": "A named, published plan, e.g. \"weather_for_place\". Give its arguments and it runs the steps for you, quoted first, with the last step's output on top. discover() lists recipes with their inputs and estimated price."
    },
    "wallet": {
      "type": "string",
      "description": "Your wallet address, asserted. Attributes metering and a daily cap on the free tier; it proves nothing. To pay from a balance, prove the wallet once at /api/wallet and send the key it returns as wallet_key or as Authorization: Bearer rw_...",
      "x-mcp-header": "Wallet"
    },
    "country": {
      "type": "string",
      "description": "Two letter code for where this request is, e.g. \"FR\". A routing hint, not an argument to the API: it lets a provider that covers only that country be chosen, and keeps one that does not out of the running. Unnecessary when the arguments already carry coordinates."
    },
    "dry_run": {
      "type": "boolean",
      "description": "Quote only: which provider would be chosen, at what price, with what latency, and why. Nothing is called, charged or counted."
    },
    "payment": {
      "type": "object",
      "properties": {
        "rail": {
          "type": "string"
        },
        "payload": {
          "type": "object"
        }
      },
      "description": "Pay this one call with x402: { rail: \"x402\", payload: <PaymentPayload> }, an EIP-3009 authorization to the pay-to address for at least the price, signed by your wallet. The requirements to sign are in discover() and in any payment_required error. A facilitator verifies and settles it; the receipt carries the transaction.",
      "additionalProperties": false
    },
    "failover": {
      "type": "boolean",
      "description": "Default true when routing by capability: if the chosen provider fails, the next eligible one is tried and only the one that answered is charged. Set false to fail fast."
    },
    "provider": {
      "type": "string",
      "description": "Provider id, e.g. \"open-meteo.geocode\". Omit to route by capability.",
      "x-mcp-header": "Provider"
    },
    "arguments": {
      "type": "object",
      "description": "Arguments in the capability contract shape from discover(). Learn geocode once; every provider behind it takes the same input and returns the same output.",
      "additionalProperties": true
    },
    "max_price": {
      "type": "string",
      "description": "Do not route above this price per call, e.g. \"0.0030\""
    },
    "max_total": {
      "type": "string",
      "description": "For a plan: do not run if the quoted total exceeds this, e.g. \"0.0100\"."
    },
    "capability": {
      "type": "string",
      "description": "Capability to route on, e.g. \"geocode\". Ignored when provider is given."
    },
    "wallet_key": {
      "type": "string",
      "description": "A wallet key (rw_...) from /api/wallet. Proves the wallet, and calls are paid from its deposited USDC balance. Prefer sending it as the Authorization: Bearer header."
    },
    "max_latency_ms": {
      "type": "integer",
      "description": "Do not route to a provider slower than this p50"
    },
    "idempotency_key": {
      "type": "string",
      "description": "Your own id for this call, up to 64 characters. A retry with the same key within 24 hours returns the same result and receipt and is never charged again. The output is kept for those 24 hours only because you asked for replay."
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "required": [
    "receipt"
  ],
  "properties": {
    "receipt": {
      "type": "object",
      "description": "The receipt object from a call() result.",
      "additionalProperties": true
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "required": [
    "receipt",
    "reason"
  ],
  "properties": {
    "reason": {
      "type": "string",
      "description": "What was wrong, in plain words. Up to 500 characters. Do not paste the response body."
    },
    "receipt": {
      "type": "object",
      "description": "The receipt object from the call() result you are disputing.",
      "additionalProperties": true
    }
  },
  "additionalProperties": false
}