Docs / Reference

The thirteen-tool MCP grammar.

Bhārata Strata is served as a Model Context Protocol grammar over Streamable-HTTP — not a REST API. Connect an MCP-native client and call thirteen typed tools (eight read/analysis + five navigability); every answer is a witness envelope.

Connect

MCP endpoint · https://api.gridrock.ai/mcp

Descriptor · /.well-known/mcp.json

OpenAPI · /openapi.yaml · llms.txt · /llms.txt

Anonymous read is available and rate-limited. Send X-API-Key for higher tiers (provision in the console).

resolve_locality(lat, lng) → { admin_code, cluster_id, anchor_key }

Resolve a coordinate to the locality cell it falls in (exact coarse-H3 nearest-cell). Refuses a point beyond MH-36 rather than snapping it to a far cell.

read_witnesses(admin_code, cluster_id) → the 492-column cube row + coverage.has_flags

The full witnessed cube row for a cell, with three-way coverage honesty (observed / witness-absent / present-but-uncertain). Missing is never zero.

read_at

(lat, lng, at, signal ∈ { rainfall, aqi, temperature }) → { value | null, valid_time: { served_window, cadence }, support, witness } — or a typed R7 refusal

Valid-time witness read — "what was TRUE at instant T" — the bitemporal dual of read_witnesses (whose as_of is transaction-time). Returns the witnessed pin whose own natural window brackets T (rainfall via GPM-IMERG, aqi via CPCB IDW, temperature via IMD city-station IDW). Outside the observed window it refuses (R7): before/after_observed_window or a cadence gap — never interpolated, never back-cast. A pre-genesis (deep-history) refusal carries the authoritative Q/U/V/W trajectory trend (slope ± GUM SE + Mann–Kendall) for rainfall/temperature.

find_twins(admin_code, cluster_id) → { twin_keys, twin_admin_codes, twin_sims, twin_dists, n_dims_used, mean_confidence }

Top-K morphological twins from the exact R24 v2 GUM-confidence-weighted, magnitude-aware standardised-Euclidean index over the 45-dim vector (exact, no ANN).

rank_by_weights(weights (+ admin_codes, k, min_witnesses)) → ordered set + per-column contribution components

Rank cells by YOUR weighted combination of cube columns, with per-column contribution decomposition. The engine supplies no goodness prior — the criterion is yours.

explain(a_admin, a_cluster, b_admin, b_cluster) → per-feature decomposition of the recorded pairing

Per-feature decomposition of the R24 distance for a recorded twin pair. Reads the authoritative similarity; never reconstructs it.

attest(subject ∈ { cell, artefact } (+ ids)) → a recomputable warrant (lineage + verdict)

The warrant behind a claim: recomputed shard sha256 + ancestry lineage (cell), or sha-verify + falsifier verdict (artefact). Fail-closed.

aggregate_region(feature (+ admin_codes)) → one pooled, confidence-weighted claim

Pool a feature over a region into one confidence-weighted claim with descriptive dispersion but NO standard error / CI (cells are spatially autocorrelated).

route(a_lat, a_lng, b_lat, b_lng) → { distance_km (±σ), duration_s_free_flow, k_band, stability_certificate, reachable }

Free-flow road route between two points + a stability-certified k-band (never a brittle single arrow). Disconnected → reachable:false, never ∞/0. Free-flow only; traffic is the Ola witness (D9).

reach(lat, lng, budget_minutes) → { reachable_cells, n_reachable, n_unreachable_typed }

The reachable-cell catchment (isochrone) within a free-flow minute budget; monotone in the budget, unreachable cells typed (R3).

relate(a_admin, a_cluster, b_admin, b_cluster) → { relation (RCC-8 base-8), basis, support_m }

The RCC-8 topological relation between two locality cells, from the rcc8_lattice witness — the P4 pillar served.

visibility(observer_lat/lng, target_lat/lng) → { visible, distance_m, support_m, admin_code }

Curvature-corrected line-of-sight over the 30 m DEM + building heights. Support-gated — refused outside the raster, never silently visible.

anchor(lat, lng (+ radius_m, k)) → { landmarks: [{ name, d_f_m, bearing_compass, fame_score:null }] }

The measured distance + bearing to nearby landmark objects; fame stays a declared witness (null), never fabricated (R1).

Calling a tool

Initialize once (keep the Mcp-Session-Id header), then issue a tools/call:

curl -s https://api.gridrock.ai/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "Mcp-Session-Id: $SID" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"resolve_locality",
                 "arguments":{"lat":19.0760,"lng":72.8777}}}'

Valid-time coverage — read_at

read_at serves a value only where a tier actually observed the instant. The per-instant window is the live cadence chain — roughly the last two weeks and growing (rainfall via GPM-IMERG ~30-min, aqi via CPCB hourly, temperature via IMD hourly). Outside it the engine refuses, typed (R7): a cadence gap, after the latest pin, or before genesis — and a before-genesis (deep-history) refusal carries the authoritative Q/U/V/W trajectory trend (slope ± GUM SE + Mann–Kendall), never a per-instant back-cast. Coverage is disclosed per call (station / pixel support); a gap is a typed refusal, never a fabricated zero. For deep history and the long-term norm, read the trend — not a per-instant value the engine never observed.

Refused by doctrine (R1)

score_site and assess_risk do not exist: the engine supplies no goodness, suitability, or risk prior. Use rank_by_weights with your own weights — the value judgment stays yours, and provenanced to you.