mcg_quote
Price a simulation. FREE: no hardware starts. Returns quote_id, quote_hash, tokens, rate_card_version, wall_s, expires_at, resource_class, resource_label and sku (the GPU class the quote is bound to, its name, and the offer SKU it priced; null when none was chosen), resource_options (one row per class the run can rent at this venue: resource_class, label, sku, tokens, wall_s, available; tokens and wall_s are what this quote would be on that class, null when it has no live offer now; re-quote with resource_class to pick one), pricing {hours_factor, potential_cost_ratio, note} when a potential staged at slots/potential was priced by its predicted per-step cost over the default's (the hours, the wall time and the run's wall limit are multiplied by hours_factor, at least 1, the factor on the quote's resource_class: each resource_options row is priced at its own class's factor; the per-second rate is unchanged), the plan, and record: {traced: true, node, node_uid, map_version (the openmaterials graph version the node is pinned at; the commons map version is published at openmaterials.ai/data/version.json), material (the material the pinned conditions name: what the run computes), potential {label, sha256} when the run's staged potential is not NEP89} when the completed run's OpenMaterials record is keyed on that public map node (measured instances cite the method that ran), else {traced: false, reason}, which only the graph arm, research coordinators and the untraced preview kinds (the reason is the kind's traced_note) return: a kind-arm spec no record can name is refused with the reason, and one naming several materials or interfaces carries detail.split: one {material, spec} per simulation, each ready to quote (pass the same study to group them). Research coordinators remain traced:false because they have no single public-node pin, but add record.record_contract: per-task omai completion requirements and the approved contract_sha256. Scientific tasks require simulation records; source-integrity QA requires node-less light_evidence, not scientific results. This is a required contract, not evidence that a run has completed; read it before you spend. The price is a binding ceiling: never more than this. A quote with billing.policy metered_v1 (D-083) carries billing {billing_mode, rate_tokens_per_s, boot_tokens, gate_tokens_per_stage, laws, liability_table, waiver_remaining_today, statement, dispute}: a metered run pays the lower of its work and its time, and a refusal the liability table names as the caller's, after the code computed, pays its work, never more than the quote. mcg_run accepts only this quote_id with this quote_hash before expires_at and REJECTS a stale hash (quote_mismatch) or an expired quote (quote_expired). Arms, exactly one: kind from mcg_catalog (spec passed through verbatim, spec.params set the price, engine overrides the default only with a known engine id); external_frontier, an OpenMaterials external-solve envelope from mcg_catalog's graphs (also returns request_id, plan_digest and the compiled plan; an envelope not byte-equal to a supported graph REJECTS with unsupported_graph); draft_id (see the parameter). Also returns app_url, the owner's page in the app (for the human, never fetched by the agent) and, on the kind arm, warnings: the inputs the app cannot render without (material or structure_xyz, study); pass them. key_cap {tokens, daily_token_cap, message} appears when the quote alone is above this key's daily_token_cap: mcg_run with this key would be refused.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"name": "<name>"
},
"name": "mcg_quote"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | Simulation kind from mcg_catalog, e.g. bulk_kappa. | |
| name | Yes | A human label for the simulation. | |
| spec | No | The spec object, e.g. {params: {...}, spec_yaml: '...'}. params drive the price. interface_tbc: params.production_steps, equilibration_steps, nx, ny, n_z_per_side, n_bins and delta_T_K set the NEMD budget, junction and thermostat offset within the bounds the reply's certification.settable states (a refused run's summary.next names the key to raise); the price follows the steps and the junction's atom count. On a native engine a params key the kind neither prices nor runs is refused (invalid_request, detail.unknown and detail.accepted), never run at the defaults. | |
| study | No | The study (project) this simulation belongs to: the id of a study you own (std_ plus 20 hex), or an exact name, created if absent. A value shaped like a study id never creates a study: one that is not yours is refused. Every quote for one investigation should name the same study so the app groups them together. | |
| engine | No | Optional engine id override (rejected if unknown). | |
| target | No | Run on one of your connected clusters (see mcg_clusters) instead of the cloud: hardware cost 0, gate fee per the rate card and plan, wall time includes the scheduler's queue-wait estimate. The cluster's status must be connected. | |
| draft_id | No | Third arm: price a draft that mcg_stage created and whose inputs have been uploaded (refuses with inputs_missing while any declared input is absent). Also re-prices an already-quoted simulation, after its quote expired or to reproduce a run (pass the run's quote_id, its simulation_id): it clones the spec, the map pin and the staged inputs (not contract files, nor structure files the engine does not read; more than 25 inputs refuse) and returns the clone's fresh quote_id (reply carries requoted_from, and rerun_notes naming skipped inputs, structure overrides and an om_graph re-pin to the active bundle's graph snapshot when the envelope is unchanged; after a map train the envelope moves and the clone is refused with unsupported_graph, so quote with external_frontier instead). Mutually exclusive with every other argument but name, target and resource_class; a re-price keeps the quoted class on the same target unless resource_class names another. | |
| material | No | Kind arm only: the material or formula being simulated (e.g. Si, MoS2). Also selects the reference structure. On a traced run whose engine fixes its own conditions it must match the spec's material. | |
| conditions | No | Kind arm only: physical conditions as key/value pairs, e.g. {T: 300}. Values are numbers, strings or lists of up to 16 of them, except on an adapter engine, which runs them: there any value its conditions schema allows (lists, booleans, null) over the keys it declares, judged at quote. On a traced run whose engine fixes its own conditions, a key or value its record does not hold is refused; the error names what to send or omit. | |
| max_tokens | No | Graph arm only: quote-time hard ceiling; a quote above it REJECTS (never clamps). | |
| structure_xyz | No | Kind arm only: the simulated structure as extended-XYZ text; staged as the input structure.xyz so the app renders the exact geometry (takes precedence over the material reference). | |
| resource_class | No | The GPU class to run on, from a previous reply's resource_options (e.g. gpu-ampere-80). The quote prices that class only and the run rents only it: no fallback to another class, so it waits in quoted while the class has no capacity. Omit to price the cheapest class; the run may then take any class the engine runs on. A class the run cannot rent at this venue REJECTS with the allowed list. | |
| external_frontier | No | The OpenMaterials #110 external-solve envelope, verbatim: mcg_catalog graphs[].envelope for the active bundle. Mutually exclusive with kind/spec/engine. | |
| potential_from_run | No | Kind arm only: a done nep_train or nep_campaign run id whose trained NEP model this simulation runs; staged as its potential (with its license notice) before pricing. |