STRATA · Docs
The STRATA data API: REST and MCP
STRATA's tools answer over two surfaces. The REST API at https://strata.brightquery.ai/api/v1 takes one POST per call and returns JSON pinned to the data release that produced it, for scripts that run the same query again and compare. The Model Context Protocol server at https://strata.brightquery.ai/mcp serves the same tools to an MCP client such as ChatGPT or Claude, whose model answers; a script can call it directly too. This page shows both, with the real replies trimmed to what matters. Every figure a result returns names its source, its date and what it measures; keep those with the number.
01 · The REST API
Plain HTTP, no model, the answers MCP gives
For a script that wants the data and nothing else: one POST per call, JSON in and JSON out, no key. Each answer is the answer the MCP server gives for the same call, byte for byte, and it names the data release and the build that produced it, so the same query can be run again and compared.
https://strata.brightquery.ai/api/v1| Method | Path | What it returns |
|---|---|---|
| GET | /api/v1/tools | The tools REST serves, each with its input schema and whether it is reproducible |
| POST | /api/v1/tools/{name} | One call. Body {"arguments": {...}, "pin": {...}}, both optional |
| GET | /api/v1/serving | The live pin (tier_id, web_sha) and the release's tier facts |
| GET | /api/v1/commodities/{id}/sections/{section} | Download a complete dossier section with its release pin and source fields. For example, use bauxite_alumina and production to retrieve Guinea’s company history. If a section is omitted because it exceeds the tool reply limit, follow the HTTP Link header for its pinned download. |
| GET | /api/v1/sites | A commodity's site table, one row per site and stage: JSON in pages of 100, or the whole table as CSV (format=csv) |
| GET | /api/v1/site_production | Copy the site_key from an aluminium site, e.g. ["al_site_id","ALS-M-IN-0029"], to download every whole-site production observation in JSON pages or CSV. Optional stage selects mine, refinery or smelter. Each row dates its reporting period and cites its source. Separate reports of the same period can differ. as_of dates the edition read. |
| GET | /api/v1/materials | STRATA's material registry: every form with its parent_chain, filter with commodity, form and grade; 404 on an edition without the registry |
| GET | /api/v1/materials/{id} | One registry form whole: definition and where it was read, parent_chain, constituents, grade classes, specs, HS lines per edition, aliases, replaced_by |
| GET | /api/v1/specs | One registry spec by spec_id (a query parameter, since spec ids hold / and >=): headline threshold, impurity and physical terms, who defines it |
| GET | /api/v1/site_roles | What each census site takes in and puts out (input or output, the material, the figure, the evidence and citation): JSON in pages of 100, or CSV |
| GET | /api/v1/sources | Every source with its licence: what kind of terms it publishes (open, attribution, non_commercial, no_redistribution, paid, unknown), what they say about commercial use, and where they were read; filter with licence_class |
| GET | /api/v1/releases | Every data release and web build this server has served, with when each was replaced |
| GET | /api/v1/openapi.json | The OpenAPI 3.1 document, for a client generator or a coding assistant |
REST serves the 22 data tools: search, the facility, entity, commodity and company lookups, every site of a commodity listed or ranked by capacity (list_facilities, rank_facilities), ownership chains, company events, the commodity and country tables, trade, restrictions, demand intensity, water stress, the food, water and land nexus, the data inventory and the source cards. The model-service tools (scenario runs) stay on MCP. Start from the tool list; its input schemas are the ones /mcp advertises, and the OpenAPI document wraps them for a client generator or a coding assistant.
GET /api/v1/tools
curl -s https://strata.brightquery.ai/api/v1/tools{
"api": "strata-rest/v1",
"tools": [
/* search_strata and lookup_commodity come first */
{
"name": "lookup_facility",
"title": "Lookup Facility",
"reproducible": true,
"reason": null,
"input_schema": { "type": "object", "required": ["facility_id"] }
/* "description": what the tool answers and how to read its fields */
}
/* 22 tools in all; reproducible: false says why in reason */
]
}Cut to one tool. Each entry carries the same input schema /mcp advertises (JSON Schema 2020-12), with every free string capped at 256 characters.
02 · The pin and the limits
Every answer names the release that produced it
An answer carries the pin of the data and code behind it: tier_id, a content hash of the published tables, and web_sha, the deployed build. Send the pin back with a later call to get an answer from that same pair or a refusal, never a quiet answer from different data.
GET /api/v1/serving
curl -s https://strata.brightquery.ai/api/v1/serving{
"api": "strata-rest/v1",
"pin": { "tier_id": "...", "web_sha": "..." },
"tier": { "synth_run_id": "...", "bqregno_run_id": "...", "bridge_vintage": "..." },
"seeds_match_tier": true,
"reasons": { "web": null, "tier": null, "seeds_match_tier": null }
}tier_id is a content hash of the release's published tables; web_sha is the deployed web build, which fixes the code and the bundled data that answer. Send both back as the pin.
reproducible: truemeans the same arguments on the same pin return the same bytes, whatever server process answers and whenever it is asked. Every pinned tool is reproducible; get_data_inventory and get_source read the live refresh log and say so inreason.- To pin a call, send
"pin": {"tier_id": "...", "web_sha": "..."}with the arguments. A pair that is no longer live answers 410 with the live pin to re-pin to, when the pinned release was replaced, and links to the releases and their notes. Only the live release answers: after a release, a script re-pins, and an earlier release cannot be replayed.pin.as_ofis the date the tools take as today (UTC): leave it out for today, and send theas_ofof an earlier answer to replay it on the same tier. Any date from the tier's publication to today is accepted. - Two dates share the name
as_of.pin.as_ofabove replays an answer; on /sites it is theas_ofquery parameter, and the own_* columns are read on it. Theas_ofargument of lookup_facility, lookup_entity and get_ownership_chain is the date ownership is read at: any past date, with the statements in force that day, still from the live tier. It moves ownership only; capacity, status and production keep their own dates (cap_as_of, status_date, a production row's year). - No key. Calls are limited per address: 60 a minute with bursts of 20, and 8 at a time across the server. A 429 or 503 carries Retry-After.
- Every answer, a refusal too, carries the address's bucket:
RateLimit-Limit(the burst, 20),RateLimit-Remaining(the calls it can make now) andRateLimit-Reset(the seconds until the bucket is full again), so a script can pace itself before it is refused. - Every answer carries
x-request-id: the one the call sent, when it is 1 to 64 letters, digits, dots, underscores or hyphens, else a new one. Quote it when a call fails; the server's log lines name it. - Calls from a web page are allowed: every /api/v1 answer carries
Access-Control-Allow-Origin: *and lets the page read the pin, Retry-After, x-request-id and RateLimit headers, and OPTIONS answers the preflight. The data is public and no answer reads a cookie. /mcp still refuses a page from another site. - For a monitor,
GET /api/readyanswers 200 with"ready": truewhen a call made now would be answered, else 503 with"ready": falseand its reasons: the serving record unreadable, seeds that are not the served tier's, a new release being published, or every in-flight slot taken. /api/health is the liveness probe and answers 200 either way. - A call answers within 60 s or returns 504; narrow it and call again. A body is at most 64 KiB, a string argument at most 256 characters, and the arguments at most 200 elements (array items and object keys).
- Refusals share one body,
{"api": "strata-rest/v1", "error": "..."}: 400 for a body or arguments the schema refuses (each issue listed), for an argument key the tool does not take (unknown argument ...: MCP drops such a key, REST refuses it, so a misspelled filter is never ignored), and for a /sites commodity or stage the data does not hold (the answer names the ones it does), 404 for a tool REST does not serve, 410 for a pin no longer live, 422 for a result over the 80,000-character limit, 503 while a new release is being published. Retry a 503 after Retry-After.
03 · Worked REST calls
A smelter, the aluminium smelters ranked and tabled, an ownership chain
Real replies from the live release, trimmed to what matters. The result field is the tool's JSON exactly as MCP returns it; every value in it names its source and its date.
POST /api/v1/tools/lookup_facility: the Bratsk smelter
curl -s -X POST https://strata.brightquery.ai/api/v1/tools/lookup_facility \
-H 'content-type: application/json' \
-d '{"arguments":{"facility_id":"fac_5VND6CMNFV5E5YA16JAVM5XG1H"}}'{
"api": "strata-rest/v1",
"tool": "lookup_facility",
"arguments": { "facility_id": "fac_5VND6CMNFV5E5YA16JAVM5XG1H" },
"pin": { "tier_id": "...", "web_sha": "...", "as_of": "..." },
/* "tier": the release's synthesis run, BrightQuery run and bridge vintage */
"reproducible": true,
"reason": null,
"result": {
"found": true,
"facility_id": "fac_5VND6CMNFV5E5YA16JAVM5XG1H",
"canonical_name": "Bratsk Aluminium Smelter",
"status": "operating",
"country_iso2": "RU",
"commissioning_year": 1966,
"status_line": "status operating, read 2026-10-24 (rusal.ru; page undated); USGS MRDS 1997-03-13 agrees",
"status_citation_url": "https://rusal.ru/en/about/geography/bratskiy-alyuminievyy-zavod/",
"commodities": [
{
"commodity_code": "aluminum",
"process_roles": ["primary_smelting"],
"hs_lines": [{ "code": "760110", "label": "unwrought aluminium, not alloyed" }]
/* and 760120, unwrought aluminium alloys */
}
],
/* operators, register identifiers, lifecycle events, the curated control bloc, the events hint and page_url */
"site_ownership": {
"rows": [
{
"standing": "current",
"owner": "United Company RUSAL, international public joint-stock company",
"owner_entity_id": "gleif_lei:213800WNO9IQTTI4PG55",
"stake_percent": 100,
"as_of": "2025",
"document": "UC RUSAL Consolidated Report 2025 (HKEX filing, 29 April 2026)"
/* its citation_url, page, quote and a one-line summary */
}
]
},
"site_production": {
"rows": [
{
"year": 2024,
"value_kt": 1002,
"basis": "reported",
"document": "UC RUSAL IPJSC Annual Report 2024 (HKEX filing 29 April 2025)"
},
{ "year": 2023, "value_kt": 1005, "basis": "reported" }
/* each with its period, citation_url, quote and a one-line summary */
]
}
}
}Cut from about 12,000 characters. result is byte for byte what /mcp returns as structuredContent for the same call. The status line dates the status by the page it was read from. site_ownership gives each owner's stake as the filing prints it, and site_production every year's output on a 100% basis, never summed. commissioning_year comes from a USGS MRDS record, which lifecycle_events marks LOW confidence. operators lists only register and source ties, so it is empty here: lookup_entity's owned_sites lists the sites a company holds.
POST /api/v1/tools/rank_facilities: the world's aluminium smelters by capacity
curl -s -X POST https://strata.brightquery.ai/api/v1/tools/rank_facilities \
-H 'content-type: application/json' \
-d '{"arguments":{"commodity_id":"aluminium","stage":"smelter","top_n":5}}'{
"api": "strata-rest/v1",
"tool": "rank_facilities",
/* "arguments" with the defaults filled in, "pin", "tier", "reproducible", "reason" as above */
"result": {
"found": true,
"commodity_id": "aluminum",
"stage": "smelter",
"basis": "nameplate",
"ranked": true,
"headline": "Aluminum smelter operating sites ranked by nameplate capacity in t/yr: 63 sites carry a source-checked figure on this basis, dated 2019-2026; Jharsuguda aluminium smelter (Vedanta) is first at 1,850,000 t/yr nameplate capacity (2026). ...",
"rows": [
{
"rank": 1,
"name": "Jharsuguda aluminium smelter (Vedanta)",
"operator": "Vedanta Limited (Vedanta Aluminium)",
"ultimate_parent": "Vedanta Limited",
"country": "India",
"status_line": "status operating, read 2026-10-25 (vedantaaluminium.com; page undated)",
"figure": "1,850,000 t/yr nameplate capacity (2026)",
"cap_source_url": "https://vedantaaluminium.com/about-us/our-operations/",
"cap_quote": "The plant has an aluminium smelting capacity of 1.85 MTPA and an associated 3615 MW thermal power generation facility.",
"verified": true
}
/* ranks 2 to 5 */
],
"total_on_basis": 63,
"shown": 5
/* company totals, the sites whose capacity is not disclosed, data limits, page_url */
}
}Cut from about 13,000 characters. Each figure carries its basis, its year, the page it was read from and the sentence it was read in. top_n is at most 50. list_facilities pages through every listed site of a commodity (25 a page) with the same fields, rank_exclusion saying why a site is not ranked. A row's verified says the site's stage and product were read on the operator's own website; it is not the figure check. Every ranked figure passed that check, and in the site table rank_eligible marks the rows that pass it.
GET /api/v1/sites: every aluminium smelter, one row each
curl -s 'https://strata.brightquery.ai/api/v1/sites?commodity=aluminium&stage=smelter'{
"api": "strata-rest/v1",
"table": "sites",
"query": { "commodity": "aluminum", "stage": "smelter", "page": 1 },
"pin": { "tier_id": "...", "web_sha": "...", "as_of": "..." },
"reproducible": true,
"columns": ["row_id", "name", "country", "country_iso3", "stage" /* 116 columns in all */],
"total": 118,
"rows": [
{
"name": "Al Taweelah aluminium smelter (EGA)",
"country_iso3": "ARE",
"stage": "smelter",
"operator": "Emirates Global Aluminium (EGA) PJSC",
"ultimate_parent": "EGA",
"status_line": "status operating, read 2026-10-25 (ega.ae; page undated)",
"status_line_basis": "read",
"status_date": "2026-10-25",
"status_source_url": "https://www.ega.ae/en/about-us/operations/al-taweelah",
"capacity_as_published": "1500000 t/yr nameplate",
"cap_value": 1500000,
"cap_basis": "nameplate",
"cap_quote": "~1.5m tonnes per year nameplate capacity",
"hs_lines": [{ "code": "760110", "label": "unwrought aluminium, not alloyed" }]
/* owners and stakes where STRATA's curated split names the site, the capacity's page and read date, rank_eligible */
}
/* sorted by country, name, stage: the same order on every call */
]
/* page, pages, page_size, next_page, and notes on what each column means */
}Add format=csv for the whole table as one file (the pin travels in the x-strata-tier-id, x-strata-web-sha and x-strata-as-of headers); leave stage out for every stage of the commodity. In a CSV cell a closed-vocabulary list (codes, numbers, dates) joins with "; ". A free-text list (product, URL, document, section, quote, prod_line) is a JSON array in the cell when it holds two or more values, bare when one. The pin goes in the query string: tier_id, web_sha, as_of.
curl -s -o strata-sites-aluminum.csv 'https://strata.brightquery.ai/api/v1/sites?commodity=aluminium&format=csv'POST /api/v1/tools/get_ownership_chain: from a Rusal subsidiary up to UC Rusal
curl -s -X POST https://strata.brightquery.ai/api/v1/tools/get_ownership_chain \
-H 'content-type: application/json' \
-d '{"arguments":{"entity_id":"gleif_lei:213800WP8KJ4Q1BKIJ87"}}'{
"api": "strata-rest/v1",
"tool": "get_ownership_chain",
"arguments": { "entity_id": "gleif_lei:213800WP8KJ4Q1BKIJ87" },
/* "pin", "tier", "reproducible" and "reason" as above */
"result": {
"entity_id": "gleif_lei:213800WP8KJ4Q1BKIJ87",
"edges": [
{
"from_name": "RUSAL MARKETING GMBH",
"to_entity": "gleif_lei:213800WNO9IQTTI4PG55",
"to_name": "INTERNATIONAL PUBLIC JOINT-STOCK COMPANY \"UNITED COMPANY \"RUSAL\"",
"kind": "ultimate_parent_via",
"valid_from": "2022-07-26",
"in_force": true,
"provenance": { "source_id": "gleif", "fetch_date": "2026-10-26" }
}
],
"edges_total": 1
}
}The walk follows control edges only (controls, consolidates, ultimate parent), and shows a dual_listed_pair edge without walking through it. UC Rusal's own chain ends here: STRATA records no control parent for it, and its largest shareholder on the HKEX register (En+, 56.88%) is a shareholding, which lookup_entity returns as register_stakes.
04 · The MCP endpoint
One URL, JSON-RPC 2.0 over HTTPS
STRATA's MCP server is an ordinary HTTP endpoint. Anything that can POST JSON can call it: curl, a notebook, a scheduled job. No model sits in between, and the reply is the same JSON an MCP client's model would read.
POST https://strata.brightquery.ai/mcpEach request is one JSON-RPC 2.0 message with a method and params. The transport is MCP's Streamable HTTP in stateless mode: every POST stands alone, there is no session to open or keep, and initialize is optional for a script (it is where a client reads the server's instructions). Send these three headers on every call:
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2025-06-18The reply arrives as a server-sent event stream with one event, whose data: line is the JSON-RPC response. Read that line and parse it; the examples below show its JSON pretty-printed, with cuts marked as comments.
event: message
data: {"result":{...},"jsonrpc":"2.0","id":1}The production endpoint answers without authentication while it is open, so the examples send no Authorization header. Should it be closed, add Authorization: Bearer <token>; a missing or wrong token answers 401 with a WWW-Authenticate challenge, and a browser Origin other than the site itself answers 403 (a script sends no Origin and passes).
05 · initialize
What the server says about itself
The handshake every MCP client starts with. Its result names the protocol version, the capabilities (tools, resources, prompts, completions) and the instructions: the working rules about provenance, shares, ownership and rankings that an MCP client's model reads before it answers. Read them once; they explain the field names in every result.
initialize
curl -sS -X POST https://strata.brightquery.ai/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'MCP-Protocol-Version: 2025-06-18' \
--data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0.1"}}}'{
"result": {
"protocolVersion": "2025-06-18",
"capabilities": {
"tools": { "listChanged": true },
"resources": { "listChanged": true },
"completions": {},
"prompts": { "listChanged": true }
},
"serverInfo": {
"name": "strata",
"title": "STRATA",
"version": "0.1.0",
"description": "Critical-mineral supply chains with provenance: commodity profiles, facilities, ownership, trade, and scenario models.",
"websiteUrl": "https://strata.brightquery.ai",
/* "icons": six PNG tiles, 128 to 512 px, light and dark */
},
"instructions": "STRATA is a federated, provenance-tracked dataset of critical-mineral supply chains: ..."
},
"jsonrpc": "2.0",
"id": 1
}Trimmed: the icons array and the instructions text, the working rules an MCP client's model reads (15,859 characters in process; 18,101 on production on 2026-10-25, before this release's rules, where the GCAM service appends its routing rules). Reply 17,143 characters in process, 19,648 on production.
06 · tools/list
48 tools, each with its input schema
The catalogue of calls. Each tool carries a description written for a model, a JSON Schema for its arguments, and read-only annotations: nothing here writes. The name and inputSchema are what a tools/call needs.
Find and look up · 6
search_stratalookup_commoditylookup_facilitylookup_entityget_ownership_chainget_company_events
Lists and comparisons · 7
list_companies_by_industrylist_consuming_companiesrank_facilitieslist_facilitieslist_commoditiescompare_commoditiestop_commodities_by
Countries, trade, export controls and demand · 5
get_country_profileget_bilateral_flowsget_customs_tradeget_restrictionsget_demand_intensity
Catalogue · 2
get_data_inventoryget_source
Scenario models (GCAM, Hector, Xanthos, Tethys, Demeter, Ambrosia, Moirai, GAIA) · 23
get_gcam_coverageget_gcam_scenario*compare_gcam_scenarios*get_hector_coveragerun_hector_scenariorun_hector_custom_scenarioget_xanthos_coveragerun_xanthos_scenariofind_xanthos_entityget_tethys_coveragerun_tethys_scenariofind_tethys_entityget_demeter_coveragerun_demeter_scenariofind_demeter_entityget_water_stressget_ambrosia_coveragerun_ambrosia_food_demandget_moirai_coverageget_moirai_land_profileget_gaia_coverageget_gaia_crop_yieldsget_food_water_land_nexus
Process flowsheets (PROMMIS) · 5
list_prommis_flowsheets*solve_flowsheet*sweep_flowsheet*optimize_flowsheet*flowsheet_diagram*
* Listed while the GCAM or PROMMIS service is up. get_bilateral_flows reads STRATA's CEPII BACI table (country by country, HS6 lines, 2022 to 2024); get_source returns one source's catalogue card. get_trade_anomalies is not on this endpoint.
tools/list
curl -sS -X POST https://strata.brightquery.ai/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'MCP-Protocol-Version: 2025-06-18' \
--data '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'{
"result": {
"tools": [
/* search_strata, lookup_commodity, lookup_facility, lookup_entity, get_ownership_chain, ... one entry per tool */
{
"name": "get_source",
"title": "Get Source",
"description": "Look up one source in STRATA's source catalogue by source_id (the source_id values tool results and get_data_inventory carry, e.g. 'usgs_mcs_2026', 'gleif', 'msha'). Returns the source's name, publisher, description, homepage and access_url (public links only), license (the terms in words) with licence_class, what kind of terms the source publishes (open: no conditions; ...",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"source_id": {
"type": "string",
"minLength": 1,
"description": "A source_id as tool results carry it, e.g. 'usgs_mcs_2026' (case-insensitive)."
}
},
"required": ["source_id"]
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}
}
]
},
"jsonrpc": "2.0",
"id": 2
}Trimmed to one of the tools. Production listed 44 on 2026-10-25 (reply 139,622 characters), before this release added get_customs_trade, get_company_events, rank_facilities and list_facilities; the in-process capture listed 39 (reply 93,507 characters) before rank_facilities and list_facilities, because the two GCAM scenario tools and the five PROMMIS flowsheet tools appear only while those services are up. Each tool carries its description, inputSchema and read-only annotations.
07 · A facility
search_strata, then lookup_facility
Names resolve to ids first. search_strata turns 'Bratsk' into a facility id; lookup_facility returns the record with every figure named for what it is: status with its source and date, operators and earlier attestations apart, the curated ownership statement with its as_of, each identifier with its register, and the HS lines the facility's stage trades under, marked as tariff lines rather than shipments.
tools/call: search_strata, to turn a name into an id
curl -sS -X POST https://strata.brightquery.ai/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'MCP-Protocol-Version: 2025-06-18' \
--data '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_strata","arguments":{"query":"Bratsk","limit":5}}}'{
"result": {
"content": [{ "type": "text", "text": "{\"hits\":[...]}" }],
"structuredContent": {
"hits": [
{
"entity_type": "facility",
"entity_id": "fac_5VND6CMNFV5E5YA16JAVM5XG1H",
"label": "Bratsk Aluminium Smelter",
"context": "RU",
"region": null,
"status": "operating",
"status_as_of": "1997-03-13",
"status_line": "status operating as of 1997-03-13 (USGS MRDS)",
"status_source": "usgs_mrds_facilities_2016",
"page_url": "https://strata.brightquery.ai/facility/fac_5VND6CMNFV5E5YA16JAVM5XG1H"
},
/* 1 more hit: the Bratsk Hydroelectric Power Station, a Wikidata facility record */
]
}
},
"jsonrpc": "2.0",
"id": 3
}Trimmed: the second of the two hits. Reply 1,419 characters. content[0].text is the same JSON as structuredContent, for clients that read text only.
tools/call: lookup_facility for Bratsk
curl -sS -X POST https://strata.brightquery.ai/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'MCP-Protocol-Version: 2025-06-18' \
--data '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"lookup_facility","arguments":{"facility_id":"fac_5VND6CMNFV5E5YA16JAVM5XG1H"}}}'{
"result": {
"content": [{ "type": "text", "text": "{\"found\":true,...}" }],
"structuredContent": {
"found": true,
"facility_id": "fac_5VND6CMNFV5E5YA16JAVM5XG1H",
"canonical_name": "Bratsk Aluminium Smelter",
"status": "operating",
"country_iso2": "RU",
"latitude": 56.12915348,
"longitude": 101.4394083,
"commissioning_year": 1966,
"match_tier": "HIGH",
"status_source": "usgs_mrds_facilities_2016",
"status_as_of": "1997-03-13",
"status_line": "status operating as of 1997-03-13 (USGS MRDS)",
"status_note": "This status is the USGS MRDS development status 'Plant' as recorded (2016 release, record content often decades older); it is not a current operating status.",
"status_source_url": "https://mrdata.usgs.gov/mrds/mrds-csv.zip",
"operators": [],
"current_operator_attested": false,
/* "earlier_attestations": two 1991 USGS MRDS point observations (Bratsk Aluminum Works as operator, Russia Government as 100% owner), in_force false */
"curated_ownership": {
"operation": "Bratsk Aluminium Smelter (BrAZ)",
"stage": "processing:smelting",
"owners": [{ "owner": "UC Rusal", "stake_percent": 100, "qualifier": "via PJSC RUSAL Bratsk" }],
"as_of": "2026-06-01",
"source_label": "https://www1.hkexnews.hk/listedco/listconews/sehk/2025/0429/2025042904964.pdf",
"next_call": "lookup_commodity {commodity_id: 'aluminum', sections: ['ownership']}",
/* as_stated, detail, control_bloc, match_basis, note */
},
"identifiers": [
{ "scheme": "icmm_id", "label": "ICMM", "value": "ICMM08036", "registry_url": null, "source_id": "icmm_global_mining", "confidence": "HIGH" },
{ "scheme": "usgs_mrds_dep_id", "label": "USGS MRDS", "value": "10206801", "registry_url": "https://mrdata.usgs.gov/mrds/show-mrds.php?dep_id=10206801", "source_id": "usgs_mrds_facilities_2016", "confidence": "HIGH" },
/* usgs_mas_id 4520007006 */
],
"commodities": [
{
"commodity_code": "aluminum",
"process_roles": ["primary_smelting"],
"source_id": "icmm_global_mining",
"hs_lines": [
{ "code": "760110", "label": "unwrought aluminium, not alloyed", "basis": "aluminum primary_smelting: the tariff line this stage's product trades under, not a declared shipment from this facility" },
{ "code": "760120", "label": "unwrought aluminium alloys", "basis": "aluminum primary_smelting: the tariff line this stage's product trades under, not a declared shipment from this facility" }
]
}
],
"hs_lines_note": "hs_lines are HS 2022 tariff lines the product of each listed stage trades under, from STRATA's commodity and stage map: not declared shipments from this facility and no trade figure for it. A commodity or stage the map does not name has none.",
"page_url": "https://strata.brightquery.ai/facility/fac_5VND6CMNFV5E5YA16JAVM5XG1H"
}
},
"jsonrpc": "2.0",
"id": 4
}Trimmed: lifecycle_events (one 1966 commissioning event), the two earlier attestations, the identifier dataset links and fetch dates, and the ownership_hint text. Reply 15,943 characters; structuredContent 7,636. Every figure names its source and date: the operating status is a 1997 USGS MRDS record, not a current observation.
08 · A commodity section
lookup_commodity with sections
A whole commodity profile runs to hundreds of thousands of characters, so ask for sections. Every reply carries identity and the concentration projection; sections_available lists the keys the profile holds. The trade section below is country-level trade plus the few named customs declarants STRATA holds.
tools/call: lookup_commodity, aluminum, sections ['trade']
curl -sS -X POST https://strata.brightquery.ai/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'MCP-Protocol-Version: 2025-06-18' \
--data '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"lookup_commodity","arguments":{"commodity_id":"aluminum","sections":["trade"]}}}'{
"result": {
"content": [{ "type": "text", "text": "{\"found\":true,...}" }],
"structuredContent": {
"found": true,
"page_url": "https://strata.brightquery.ai/commodity/aluminum",
"commodity_id": "aluminum",
"identity": { "kind": "identity", "display_name": "Aluminum", "symbol": "Al", "category": "base_metal", "critical_lists": ["DOE_2023", "USGS_2022", "USGS_2025"], /* ... */ },
"trade": {
"import_shares": [
{ "reporter_iso2": "US", "partner": "Canada", "partner_iso2": "CA", "sub_commodity": "All", "share_pct": 56, "year_start": 2021, "year_end": 2024, "is_headline": true },
/* 4 more USGS import-share rows: United Arab Emirates 8, ... */
],
"nir": [
{ "year": 2025, "reliance_pct": 60, "is_estimate": true, "product": "Aluminum", "consumption_basis": "apparent consumption", "source_label": "USGS Mineral Commodity Summaries 2026: salient statistics, Figure 2", "source_url": "https://doi.org/10.3133/mcs2026" },
/* 4 more years */
],
"flow_top_exporters": [
{ "exporter": "Canada", "value_usd": 8274107443.999999, "year": 2024 },
{ "exporter": "United Arab Emirates", "value_usd": 7359464686.000001, "year": 2024 },
/* 8 more: Russian Federation 7,255,892,704, ...; CEPII BACI, country level */
],
"flow_top_importers": [
{ "importer": "USA", "value_usd": 11147741077, "top_supplier": "Canada", "top_supplier_share_pct": 68.3, "supplier_hhi": 0.4838, "partner_count": 44, "year": 2024 },
/* 9 more */
],
"flow_latest_year": 2024,
"flows_refined_stage": true,
"customs_exporters": [
{ "operator": "C I ENERGIA SOLAR SAS E. S. WINDOWS", "reporter_iso2": "CO", "hs6": "761010", "form_label": "HS 761010 exports", "net_t": 24256.823, "year": 2026, "attribution": "declared" },
/* 11 more declarant rows */
],
"customs_note": "Rows span 2 customs reporters (CO, PE); the coverage window and attribution basis (declared vs derived) vary by reporter.",
/* customs_importers (12, AR, CO, PE), trade_edges (12 company-to-company edges from Colombian DIAN declarations), balance (10 USGS import/export rows), restrictions (15), restrictions_in_force, agreements (6) */
},
"concentration": { "year": 2025, "reporters": 10, "unit": "thousand metric tons", "top1_share_pct": 68.39, "top3_share_pct": 80.7, "top5_share_pct": 89.82, "hhi": 0.4816, /* breakdown, share_basis */ },
"sections_returned": ["trade"],
"sections_available": ["production", "reserves", "capacity", "concentration", "supply_inherited", "midstream_facilities", "midstream_components", /* ... 24 keys */]
}
},
"jsonrpc": "2.0",
"id": 5
}Trimmed inside every list. Reply 77,121 characters; structuredContent 36,480, under the cap. Trade here is country level (USGS import shares, BACI top exporters and importers over unwrought aluminium, HS 7601.10 and 7601.20, as flows_refined_stage says); the only company-named rows are customs declarations from Colombia, Peru and Argentina, and no source links a shipment to a facility.
09 · Resources
The same data by URI
Resources are read, not called: resources/list enumerates them, resources/templates/list gives the URI patterns, and resources/read returns one as a JSON text. A commodity overview, any profile section, the data inventory and every source card are resources.
resources/list
curl -sS -X POST https://strata.brightquery.ai/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'MCP-Protocol-Version: 2025-06-18' \
--data '{"jsonrpc":"2.0","id":6,"method":"resources/list","params":{}}'{
"result": {
"resources": [
{ "uri": "strata://inventory", "name": "data-inventory", "title": "Data inventory", "mimeType": "application/json", /* description */ },
{ "uri": "strata://commodity/aluminum", "name": "aluminum", "title": "Aluminum", "mimeType": "application/json", /* description */ },
/* one overview per commodity profile, then one card per catalogue source: 281 resources in all, the last strata://sources/zinc_lead_smelter_capacity */
]
},
"jsonrpc": "2.0",
"id": 6
}Trimmed to two of 281 resources. Reply 152,081 characters. resources/templates/list (id 7) returns the four URI templates: strata://commodity/{commodity_id}, strata://commodity/{commodity_id}/{section}, strata://commodity/{commodity_id}/{section}/full and strata://sources/{source_id}.
resources/templates/list
curl -sS -X POST https://strata.brightquery.ai/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'MCP-Protocol-Version: 2025-06-18' \
--data '{"jsonrpc":"2.0","id":7,"method":"resources/templates/list","params":{}}'{
"result": {
"resourceTemplates": [
{ "name": "commodity", "uriTemplate": "strata://commodity/{commodity_id}", "title": "Commodity overview", /* description */ "mimeType": "application/json" },
{ "name": "commodity-section", "uriTemplate": "strata://commodity/{commodity_id}/{section}", "title": "Commodity profile section", /* description */ "mimeType": "application/json" },
{ "name": "commodity-section-full", "uriTemplate": "strata://commodity/{commodity_id}/{section}/full", "title": "Commodity profile section, whole", /* description */ "mimeType": "application/json" },
{ "name": "source", "uriTemplate": "strata://sources/{source_id}", "title": "Source catalogue card", /* description */ "mimeType": "application/json" }
]
},
"jsonrpc": "2.0",
"id": 7
}Trimmed: the four descriptions. Reply 2,592 characters.
resources/read: one commodity section
curl -sS -X POST https://strata.brightquery.ai/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'MCP-Protocol-Version: 2025-06-18' \
--data '{"jsonrpc":"2.0","id":9,"method":"resources/read","params":{"uri":"strata://commodity/aluminum/trade"}}'{
"result": {
"contents": [
{
"uri": "strata://commodity/aluminum/trade",
"mimeType": "application/json",
"text": "{\"found\":true,\"page_url\":\"https://strata.brightquery.ai/commodity/aluminum\",\"commodity_id\":\"aluminum\",\"identity\":{...},\"trade\":{...},\"concentration\":{...},\"sections_returned\":[\"trade\"],\"sections_available\":[...]}"
}
]
},
"jsonrpc": "2.0",
"id": 9
}Trimmed inside text. A resource carries its JSON as one text string (36,480 characters here, the same object the tools/call above returned as structuredContent); parse it a second time.
10 · The 80k cap
Tool results stop at 80,000 characters
MCP hosts cap what they hand their model, so a tool result over 80,000 characters of JSON is never returned whole. The server first narrows a default roster itself, stating the cut in facilities_note. A lookup_commodity answer still over the cap is not an error: it returns the sections that fit, summary sections first, and a truncated block that names each section left out, the size of a call for it alone, and the resource that serves it. A midstream_components roster the cap cuts comes back as a page of its rows instead: the most that fit, in roster order, with facilities_page stating offset, returned, total and next_offset, and the truncated block naming it in sections_paged with its resource. Resources are not under the cap: append /full to the midstream_components URI and resources/read returns every roster row, unfiltered. A census stage in midstream_facilities holds at most 20 facility rows, with the other operating and pipeline rows named in omitted_names; /full adds no census rows there, and row_count against shown_count says how many are not listed.
tools/call over the cap: cobalt's operating refineries, 120 rows, paged
curl -sS -X POST https://strata.brightquery.ai/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'MCP-Protocol-Version: 2025-06-18' \
--data '{"jsonrpc":"2.0","id":10,"method":"tools/call","params":{"name":"lookup_commodity","arguments":{"commodity_id":"cobalt","sections":["concentration","midstream_components"],"midstream_country":null,"midstream_stage":"refinery","midstream_status":"operating","midstream_limit":120}}}'{
"result": {
"content": [{ "type": "text", "text": "{\"found\":true,...}" }],
"structuredContent": {
"found": true,
"page_url": "https://strata.brightquery.ai/commodity/cobalt",
"commodity_id": "cobalt",
"identity": { "kind": "identity", "display_name": "Cobalt", "symbol": "Co", /* ... */ },
"concentration_detail": { "kind": "concentration", "is_empty": false, /* mine, midstream and import blocks */ },
"midstream_components": {
"facilities": [
{ "name": "CNGR Advanced Material Co., Ltd. CNGR Morocco Industrial Base / COBCO battery materials plant", "country": "Morocco", "status": "operating", "status_line": "status operating as of 2025 (cobco.ma)", /* ... */ },
/* 34 more operating refineries, in roster order */
],
/* the section's profile-wide lists */
"facilities_total": 499,
"facilities_matched": 59,
"facilities_shown": 35,
"facilities_note": "matched 59 of 499 for stage=refinery, status=operating; ...; this page holds 35 of the 59 rows asked for, the most that fit in one result",
"facilities_page": {
"offset": 0, "returned": 35, "total": 59, "next_offset": 35,
"note": "rows 1 to 35 of the 59 that match, in roster order; call again with the same arguments and midstream_offset 35 for the next page"
}
},
"concentration": { "year": 2025, "top1_share_pct": 75.29, "top3_share_pct": 92.21, "hhi": 0.589, /* ... */ },
"sections_returned": ["concentration", "midstream_components"],
"sections_available": [/* the 24 section keys */],
"truncated": {
"limit_chars": 80000,
"answer_chars": 105387,
"sections_returned": ["concentration", "midstream_components"],
"sections_paged": [
{
"section": "midstream_components", "chars": 101361, "too_large_alone": true,
"resource": "strata://commodity/cobalt/midstream_components/full",
"resource_note": "chars measures this call (midstream_stage refinery, midstream_status operating, midstream_limit 120): 59 of 499 roster rows. The resource serves all 499 rows, unfiltered and uncapped, so it is larger; filter them on your side."
}
],
"sections_omitted": [],
"note": "The answer with every section asked for is 105.4k characters, over the 80k limit for one result, so it returns the sections that fit: summary sections first, then record lists, each in the order asked. The midstream_components roster comes back as a page, the most rows that fit: rows 1 to 35 of the 59 that match, in roster order; call again with the same arguments and midstream_offset 35 for the next page. ..."
}
}
},
"jsonrpc": "2.0",
"id": 10
}Trimmed inside identity, concentration_detail, concentration and the roster, and the note's last three sentences (sections_paged names the resource that serves every row, which resources/read returns outside the cap; for a roster, chars measures the call as asked while /full serves the section unfiltered; a roster can also be narrowed with midstream_limit, midstream_status, midstream_country or midstream_stage). Reply 162,523 characters; structuredContent 78,401. Not an error: isError is absent. A call for the 59 operating refineries alone runs to 100.8k characters, so concentration comes back whole and the roster as a page: its first 35 rows, the most that fit, with midstream_offset 35 fetching the rest. resource_note says that chars measured those 59 rows while /full serves all 499.
resources/read: the paged section whole
curl -sS -X POST https://strata.brightquery.ai/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'MCP-Protocol-Version: 2025-06-18' \
--data '{"jsonrpc":"2.0","id":11,"method":"resources/read","params":{"uri":"strata://commodity/cobalt/midstream_components/full"}}'{
"result": {
"contents": [
{
"uri": "strata://commodity/cobalt/midstream_components/full",
"mimeType": "application/json",
"text": "{\"found\":true,...,\"midstream_components\":{...,\"facilities\":[{\"name\":\"Tenke Fungurume (TFM) Copper and Cobalt Mine\",\"operator\":\"CMOC Group Limited (China Molybdenum)\",\"country\":\"Democratic Republic of the Congo\",\"stages\":[\"chemical_processing\",\"concentrator\",\"mine\"],...,\"status\":\"operating\",...,\"capacity_display\":\"450 kt/yr Cu operating\",...},...],...,\"facilities_total\":499,\"facilities_matched\":499,\"facilities_shown\":499,\"facilities_filter\":{\"country\":null,\"stage\":null,\"status\":null,\"limit\":null},\"facilities_note\":\"\"},...}"
}
]
},
"jsonrpc": "2.0",
"id": 11
}Trimmed inside text: 805,305 characters, all 499 roster rows (the 59 operating refineries the call above asked for among them), each with its operator, stages, status, capacity_display as the company published it and its source_urls. facilities_shown equals facilities_total and facilities_note is empty: nothing was cut. Without /full the same URI returns the default 40 rows with the note 'shown 40 of 499'. Aluminum's roster reads the same way: 244 rows, 334,241 characters.
To page through a roster with tools/call instead, pass midstream_offset: 0 first, then each answer's facilities_page.next_offset with the other arguments unchanged, until next_offset is null. A roster that midstream_limit or the server's narrowing of a default roster cut is not a page: from offset 0 it carries no facilities_page, and while its facilities_shown is below facilities_matched the next page starts at midstream_offset facilities_shown. Followed that way, every row comes once, in roster order. The aluminium smelter call (commodity_id 'aluminum', sections ['midstream_components'], midstream_stage 'smelter', midstream_limit 300) is one: the 124-row smelter roster arrives in pages under the 80k cap, so use midstream_offset, or GET /api/v1/sites?commodity=aluminium&stage=smelter&format=csv for the whole smelter table in one CSV, one row per site.
To narrow a roster instead: midstream_stage, midstream_country and midstream_status filter the rows and midstream_limit (at most 300) caps them, with facilities_total, facilities_matched and facilities_shown on every reply so a cut is never silent. A whole profile asked for without sections and over the cap comes back without its smallest record-list section, or as its section index when no single cut is enough; either way truncated.sections_omitted names what is missing and where to read it. For a roster, its chars measures the call as asked, filters and limit applied, while the /full resource serves the section unfiltered: resource_note gives both, as in the cobalt example (59 of 499 rows asked for, all 499 at /full). Any other tool over the cap answers isError with the levers that narrow it.
11 · Error shapes
Four kinds of no
A transport problem is an HTTP status. A request the server cannot route is a JSON-RPC error object. A call a tool cannot complete is a result with isError: true and a text that says why. A question outside the data is a normal result that says so: found: false, refused: true, or a withheld note. Only the last kind is an answer about the world; the other three are about the request.
JSON-RPC error: a tool that does not exist
curl -sS -X POST https://strata.brightquery.ai/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'MCP-Protocol-Version: 2025-06-18' \
--data '{"jsonrpc":"2.0","id":13,"method":"tools/call","params":{"name":"no_such_tool","arguments":{}}}'{ "jsonrpc": "2.0", "id": 13, "error": { "code": -32602, "message": "Tool no_such_tool not found" } }Untrimmed. The same shape answers a tool withheld from this endpoint: get_trade_anomalies is not registered while its catalogue is illustrative arithmetic on a sample of trade rows, so it is 'not found' here and absent from tools/list. get_bilateral_flows, which reads STRATA's CEPII BACI table, is listed and callable.
isError: arguments the tool's schema rejects
curl -sS -X POST https://strata.brightquery.ai/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'MCP-Protocol-Version: 2025-06-18' \
--data '{"jsonrpc":"2.0","id":14,"method":"tools/call","params":{"name":"lookup_commodity","arguments":{"sections":["trade"]}}}'{
"result": {
"content": [
{ "type": "text", "text": "Input validation error: Invalid arguments for tool lookup_commodity: commodity_id: Invalid input: expected string, received undefined" }
],
"isError": true
},
"jsonrpc": "2.0",
"id": 14
}Untrimmed. Validation failures come back as an isError tool result, not a JSON-RPC error.
JSON-RPC error: an unknown method
curl -sS -X POST https://strata.brightquery.ai/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'MCP-Protocol-Version: 2025-06-18' \
--data '{"jsonrpc":"2.0","id":15,"method":"no/such/method","params":{}}'{ "jsonrpc": "2.0", "id": 15, "error": { "code": -32601, "message": "Method not found" } }Untrimmed.
JSON-RPC error: a resource URI the server cannot read
curl -sS -X POST https://strata.brightquery.ai/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'MCP-Protocol-Version: 2025-06-18' \
--data '{"jsonrpc":"2.0","id":16,"method":"resources/read","params":{"uri":"strata://commodity/aluminum/not_a_section"}}'{ "jsonrpc": "2.0", "id": 16, "error": { "code": -32602, "message": "Unknown profile section \"not_a_section\"", "data": { "uri": "strata://commodity/aluminum/not_a_section" } } }Untrimmed. An unknown commodity id answers the same way, with the URI in data.
found: false, a lookup outside coverage
curl -sS -X POST https://strata.brightquery.ai/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'MCP-Protocol-Version: 2025-06-18' \
--data '{"jsonrpc":"2.0","id":18,"method":"tools/call","params":{"name":"lookup_commodity","arguments":{"commodity_id":"unobtainium"}}}'{
"result": {
"content": [{ "type": "text", "text": "{\"found\":false,\"commodity_id\":\"unobtainium\"}" }],
"structuredContent": { "found": false, "commodity_id": "unobtainium" }
},
"jsonrpc": "2.0",
"id": 18
}Untrimmed. lookup_facility answers {found: false, facility_id} the same way, and the model tools answer {refused: true, refusal: {code, message, suggestion}} for a scenario outside their coverage. None of these is an error: the question is outside the data, and the tool says so.
HTTP 400: a body that is not JSON
curl -sS -X POST https://strata.brightquery.ai/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'MCP-Protocol-Version: 2025-06-18' \
--data '{not json'{ "jsonrpc": "2.0", "error": { "code": -32700, "message": "Parse error: Invalid JSON" }, "id": null }Untrimmed; this reply is plain application/json, not an event stream. Without the Accept pair the server answers HTTP 406 with code -32000: 'Not Acceptable: Client must accept both application/json and text/event-stream'.
Withheld data inside a normal result reads the same way: get_country_profile answers anomalies_note in place of trade anomalies while that catalogue is illustrative, and lookup_facility counts ties it holds back in low_confidence_ties_withheld. A link the server will not give is null, never a guess. See the methodology for why.
12 · In ChatGPT and Claude
The same endpoint as a connector
A chat client calls these tools for you and lets its model do the reasoning. The data is the same; the difference is who reads the JSON.
ChatGPT
Add the endpoint once as a custom connector (Settings, Connectors, Create; URL https://strata.brightquery.ai/mcp, no authentication). STRATA is then not on by default in a new chat: open the composer's + menu and attach STRATA for that conversation, or its tools are not called. After STRATA ships a change to a tool's description, use Refresh tools on the connector so ChatGPT reads the new schema.
Claude
In Claude.ai, add it under Settings, Connectors as a custom connector with the same URL. In Claude Code, one command registers it for the project:
claude mcp add --transport http strata https://strata.brightquery.ai/mcpWhichever client you use, the server's instructions (section 05) are what its model reads first. When an answer surprises you, call the tool yourself with curl and compare: the model's answer should trace to a specific result, and the result names its source.
13 · Data dictionary
What the fields mean, and where each figure comes from
The field names are STRATA's own. These pages on this site are the dictionary.
- /docs/data-dictionary: every column of the REST site table (GET /api/v1/sites) in order, with the field it is read from, its type, how a CSV cell writes a list, and what an empty value means; the OpenAPI document's row schema states the same.
- /sources: every source_id a result carries, with its publisher, licence, vintage, cadence and authority tier. The same cards are the
strata://sources/{source_id}resources and the get_source tool. - /methodology: what a share is a share of, how concentration and the risk score are computed, how facilities and owners are resolved across registers, and the honesty rules (observed against imputed, in_force against history) that the result fields encode.
- /how-its-built: the pipeline from public registers to the graph, with copper worked through.
A script that wants plain HTTP without JSON-RPC uses the REST API in sections 01 to 03: the same tools and the same answers, each pinned to the data release that produced it. Over either surface, the 80k cap with /full is how to read a large roster whole.