Run materials simulations from your AI agent.
Your agent connects to one MCP server. Each run starts with a binding token quote and ends with a record that lists every artifact hash.
claude mcp add --transport http mcg https://api.materialscodegraph.com/mcp \ --header "Authorization: Bearer $MCG_MCP_KEY"
export MCG_MCP_KEY=mcg_sk_... # or put it in your shell profile codex mcp add mcg --url https://api.materialscodegraph.com/mcp --bearer-token-env-var MCG_MCP_KEY
curl -s https://api.materialscodegraph.com/mcp \
-H "Authorization: Bearer $MCG_MCP_KEY" -H "content-type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"mcg_rates","arguments":{}}}'
How an agent uses it
A run takes three calls: price it, launch it, read the record. The field names below are the ones the server returns.
1. mcg_quote
- request
{ "kind": "bulk_kappa", "name": "Si HNEMD 300 K", "material": "Si", "conditions": { "T": 300 }, "spec": { "params": { "production_steps": 10000000, "equilibration_steps": 100000, "n_atoms": 4096 } } }- returns
- quote_id
- quote_hash
- tokens
- rate_card_version
- wall_s
- expires_at
- plan
- app_url
- warnings
- spends
- nothing; no hardware starts
2. mcg_run
- request
{ "quote_id": "...", "quote_hash": "...", "idempotency_key": "...", "max_tokens": 7000 }- returns
- run_id
- app_url
- refuses
- a repriced or expired quote; a quote above max_tokens
- replays
- the same idempotency_key returns the same run
- spends
- the quoted tokens, bound to quote_hash
3. mcg_get_run
- request
{ "run_id": "..." }- returns
- summary.state
- summary.current_stage
- summary.billing
- record
- openmaterials_url
- openmaterials_label
- app_url
- labels
- openmaterials_label is null unless the record cites a model, configuration or code that is not in the public registry
- then
- mcg_fetch_artifacts returns {artifacts: [{path, bytes, stage, sha256}]}
- spends
- nothing
mcg_quote response for the request above, captured 2026-09-19, fixture.
- quote_id
- sim_c6e0f076b69d4720b0a6
- quote_hash
11ad852a8c04a5b7a018ce431e898863e6ee7b1c68d54983d42e5894dec35a23- tokens
- 4,637 tokens
- rate_card_version
- 6
- wall_s
- 13,827 s
- expires_at
- 2026-09-19T23:51:23.817Z
- plan
- bulk_kappa / gpumd_hnemd / single_material_thermal plan.kind, plan.engine, plan.template
- app_url
https://app.materialscodegraph.com/#/simulations/sim_c6e0f076b69d4720b0a6- warnings
- ["study"]
warnings: study means the quote names no study; pass one so the app can group the run.
From the catalog
An agent reads the catalog live through mcg_catalog. These are five of its rows: kind, engine, codes, and the price and time the agent gets back.
| agent is asked | kind / engine | codes | est_tokens | est_wall_s |
|---|---|---|---|---|
| Bulk thermal conductivity of a crystal from molecular dynamics (HNEMD or Green-Kubo) | bulk_kappa / gpumd_hnemd, gpumd_gk | GPUMD v4.7, NEP89 nep89_20250409 | 4,637 to 6,557 | 13,827 s (3.8 h) |
| Bulk thermal conductivity by phonon BTE in the relaxation-time approximation | bulk_kappa / meskal_rta | MESKAL 1.1.0, NEP89 nep89_20250409 | 252 to 299 | 337 s (6 min) |
| Filled-polymer composite conductivity plus monomer Cp(T) | composite_kappa / xtb_gfn2 | xtb | 307 | 504 s (8 min) |
| Isothermal cure schedule: conversion, Tg, vitrification | cure_schedule / xtb_gfn2 | xtb | 155 | 306 s (5 min) |
| Neural-accuracy sensitivity to device statistics (closed-form estimate, uncalibrated constants) | accuracy_study / accuracy_study_gpu | MaterialsCodeGraph | 155 | 360 s (6 min) |
est_tokens and est_wall_s from mcg_catalog, read 2026-10-07 at rate card version 6; token_usd 0.001 from /api/rates the same day. mcg_quote returns the binding price for every kind, including ones this table omits.
mcg_catalog also lists lineages, solvable OpenMaterials graphs and recipes; mcg_clusters lists your connected clusters.
The record
A done run answers mcg_get_run and mcg_fetch_artifacts with the fields below. This is one of ours: bulk silicon by BTE-RTA, run on 2026-09-07 at smoke-test settings. At these settings the value is unconverged; a converged silicon kappa needs a larger supercell and q-mesh.
Run record, captured 2026-10-07, fixture.
- run_id
- run_5cd6499a3f454c0d9f1f
- state
- done summary.state
- billing
- 285 quoted, 285 billed tokens summary.billing.quoted_tokens, summary.billing.charged_tokens
- engine
- meskal_rta record.execution.code
- image_digest
ghcr.io/dvnclabs/meskal-gpu@sha256:01c8d8cebd89c279bceed4c771bf2e8ec2a499b60d564419bcf8a46e3e6e02e0- registry
- meskal 1.1.0, nep89 nep89_20250409 record.execution.registry
- node
- ThermalConductivity[bte_solver=rta] record.lineage.node
- map_version
9802d9e854c915eb47d867575730a556ab7f4a565e392bf5b29da58338f08434the openmaterials graph version this run was pinned to; the current one is published at openmaterials.ai/data/version.json events[map_pin].map_version- conditions.temperature_K
- 300 K record.lineage.conditions.temperature_K
- conditions.supercell
- 3 x 3 x 3 record.lineage.conditions.supercell
- conditions.mesh
- 5 x 5 x 5 record.lineage.conditions.mesh
- conditions.third_bandwidth_THz
- 1 THz
- result
- 20.160749543739275 W/(m K) record.results[0].value
- gpu_type
- NVIDIA GeForce RTX 5090
- started_at
- 2026-09-07T15:34:28.341Z
- finished_at
- 2026-09-07T15:38:21.305Z 233 s after started_at
- record.id
96622c0855f8d220f5aef9d84e3302ae18205e8c00162a6c46a410892b49b079- artifacts
- results/kappa.json271 bytesresults
497c8c3416e696f7f1b7ccd57ae18d683040fe52ca0e212652cefd5d5589b1ffresults/meskal_kappa.json746 bytesresultse6575c1ddc988d197efabb10e3ba13cee2f15a37f478026298c127d769887336 - openmaterials_url
- openmaterials.ai lineage view
- openmaterials_label
- null openmaterials_label
Pricing
| plan | price | tokens per period | academic email (.edu, .edu.xx, .ac.xx) | status |
|---|---|---|---|---|
| Signup | 0 | 0 | 5,000 once | available today |
| Monthly | 20 USD | 20,000 | 40,000 | opens with billing |
| Yearly | 200 USD | 240,000 | 480,000 | opens with billing |
Today you sign up with an academic email and receive 5,000 tokens. Subscriptions open when billing goes live.
One token is 0.001 USD (rate card version 6, /api/rates, 2026-09-19): the 4,637-token quote above is 4.64 USD. Tokens are consumed at the price quoted before each launch and stay usable to the end of the paid period. Once any token of a purchase is used, the purchase is non-refundable, including the unused remainder of a yearly grant. Signup tokens are a gift and carry no payment obligation.
Connect
- endpoint
https://api.materialscodegraph.com/mcp- transport
- Streamable HTTP, POST-only JSON-RPC: initialize, ping, tools/list, tools/call
- tools
- mcg_catalog
- mcg_rates
- mcg_quote
- mcg_clusters
- mcg_stage
- mcg_run
- mcg_list_runs
- mcg_get_study
- mcg_get_run
- mcg_cancel_run
- mcg_fetch_artifacts
- mcg_get_artifact
- key scopes
- read, quote, spend (a new key defaults to read and quote)
- daily_token_cap
- required on every spend key: the most tokens it may commit per UTC day