# The Affine.Earth MCP — full user guide **One endpoint. 49 tools. Three courts — Math, Quantum, Code. Every answer an exact decimal string you can replay.** Open MCP: `https://affine.earth/language-invariant/mcp` · transport: streamable HTTP, JSON-RPC 2.0 Served by nine cells behind one apex. No key. No account. No rate card. **Validation record — [MCP court validation, 2026-09-02](MCP-Court-Validation-2026-09-02.md).** 49 tools on 9/9 cells with one response digest, and the declared manifest matching the live set exactly. It also names three defects found the same day, two of which were fixed at HEAD and pending a fleet roll: the crucible refusing the very brief the apex serves, and `math_court` declaring 54 properties for a catalogue that needs 81 more. **Read that page before trusting a `may_ingest` list on this one** — sixteen roles publish a contract their own grader refuses. --- ## What this is An MCP server that **refuses to guess**. Every tool takes decimal strings and integers, returns decimal strings and integers, and answers one of four ways: a verdict, a refusal that names the missing thing, `NOT_KNOWN`, or an error. There is no fifth way, and in particular there is no "approximately". That makes it a coding co-partner of a specific kind. It will not autocomplete your function. It will tell you — mechanically, reproducibly, on a surface anyone can re-run — whether two implementations carry the same values, whether a claimed factorisation holds, whether two trajectories are separated, whether a rendered frame matches its law. It is the half of pair programming that checks, not the half that types. **It is not Affine-only.** `code_ir_equiv` rules on any LLVM IR from any language — C, C++, Rust, Swift, Zig, anything clang or a Swift toolchain can emit. The quantum verifiers take presented witnesses from any source. The aviation and weather lanes take real coordinates. Nothing about the surface requires you to be running Affine.Earth. --- ## Quick start The smallest useful call — list what is served: ```bash curl -sS -X POST https://affine.earth/language-invariant/mcp \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' ``` Measured 2026-09-02: HTTP 200, **49 tools**, and identical on all nine A records of `affine.earth` (SNI pinned per cell; one sha256 of the sorted name list on all nine). It read 48 on 2026-08-30 and 23 on 2026-08-27; the 49th is `execute_artifact_crucible`, the Coding Court. Per-cell parity is checked rather than assumed — see *Validation*. **Do not want to write JSON-RPC by hand?** The [Court Client](Affine-Court-Client-Template.md) at `https://affine.earth/language-game/court-client.html` renders a form for every one of these tools from the tool's own schema, turns local files into long-running language games, and loads what the Coding Court returns. Calling a tool is the standard MCP shape: ```bash curl -sS -X POST https://affine.earth/language-invariant/mcp \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/call", "params":{"name":"verify_shor_witness", "arguments":{"N":"15","halfPow":"4","factor":"3","cofactor":"5"}}}' ``` Returns, verbatim: ```json {"detail":"factors=3*5","energy_den":"1","energy_num":"3","ground":"15", "ok":true,"proven":"AFFINE_QC_SHOR_WITNESS","status":"CALORIE", "subject":"fixture_N","tool":"verify_shor_witness","verdict":"WIN"} ``` Every field is a string or an integer. `energy_num`/`energy_den` is an exact rational. There is no float anywhere in the response, by construction. --- ## The refusal contract This is the part that makes the rest worth trusting, so it comes before the tool list. | Outcome | Means | Example | |---|---|---| | `WIN` / `CALORIE` | The presented claim holds, exactly | `verify_shor_witness` on 15 = 3×5 | | `MISS` / `..._DIVERGED` | The claim is false, and the response names where | `code_ir_equiv` names the constant that moved | | `REFUSED_*` | The input cannot be read — never a verdict by omission | `REFUSED_MISSING_ARG`, `REFUSED_UNDER_READ` | | `NOT_KNOWN` | Nothing was compared; not evidence either way | two empty constant pools | **Floats are refused at the wire.** A JSON `Float64` in a schema is rejected by the registry before the tool is ever served — that is a control arm, not a convention (`control_arm_float_schema_refused`, below). The reason is Constraint 3: two cells replaying a proof on different libm versions reach different answers, so a float anywhere upstream of a sealed value destroys byte-identity across the mesh. **A refusal is not a failure to be worked around.** `REFUSED_UNDER_READ` from the Code Court means the module was not fully read, so ruling on it would be a verdict by what it failed to see. That distinction is enforced in code and measured — see *Code Court* below. --- ## Surface 1 — The Code Court **`code_ir_equiv`** — are two implementations equivalent by the exact value multiset their LLVM IR carries? Not "the diff looks safe" and not "the tests passed on one runner". The court lifts every constant in both modules to an exact rational, canonicalises to gcd-reduced `num/den`, and compares the multisets. Identical ⇒ `CALORIE_CODE_IR_EQUIV`. Different ⇒ `CODE_IR_DIVERGED`, naming the value that moved. **The payload is the code file.** Arguments are whole files — `left_file` and `right_file`, each `{path, content}` where `content` is the entire file body — and the result echoes those same whole files back under `files`, so a reviewer can replay the ruling from the response alone without holding the sources. ```bash # Reordered constants — EQUIVALENT. Order is not identity; the multiset is. -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"code_ir_equiv","arguments":{ "left_file":{"path":"left.ll", "content":"%v = add <2 x i64> , zeroinitializer\n"}, "right_file":{"path":"right.ll", "content":"%w = add <2 x i64> , zeroinitializer\n"}}}}' ``` `files` is advertised as a two-element array and the parser accepts it — **but on the fleet today the membrane strips a top-level `files` key before the tool sees it** (it is on the raw-context "elephant" list), so that shape answers `REFUSED_MISSING_ARG` on all nine cells, measured 2026-09-02. Use `left_file` + `right_file`. The repair — a key the tool's own schema declares is not an elephant — is committed with a membrane-level test and lands with the next binary roll. A bare string is read as the file body with a defaulted path. The older `left_ir` / `right_ir` fragment keys still work and are lifted into whole files — nothing built against them breaks — but they carry no path, so the echoed identity defaults. The ruling digests content, so every one of these shapes reaches the same verdict. ```json {"status":"CALORIE_CODE_IR_EQUIV","ok":true, "detail":"constant pools identical over 2 distinct exact values", "left_digest":"b4912995202e2370069c6b3e5a03482f2cd26fdebcd0549f2a7fcde052a39450", "right_digest":"b4912995202e2370069c6b3e5a03482f2cd26fdebcd0549f2a7fcde052a39450", "files":[{"path":"left.ll","content":"%v = add <2 x i64> , zeroinitializer\n"}, {"path":"right.ll","content":"%w = add <2 x i64> , zeroinitializer\n"}], "reproducible":true,"stateless":true} ``` Both digests are the same because the two modules carry the same constant multiset — that identity IS the verdict. `files` is the echo: the ruling and the exact bytes it ruled on travel together. Move one constant and it locates it: ```json {"status":"CODE_IR_DIVERGED","ok":false, "detail":"constant pools differ: left has 5/1×1 not matched on right; right has 6/1×1 not matched on left", "left_digest":"b4912995…","right_digest":"5e12f9cb…"} ``` The digests are content-addressed: the same two inputs digest identically on every cell, forever. A reviewer re-checks by re-digesting, not by re-reading a diff. ### How the Code Court was validated Its own unit tests could pass while it read almost nothing, so it is measured against **real production IR** nobody here wrote: | Module | lanes lifted | read | |---|---|---| | `boringssl-fipsmodule.ll` | 25,776 | COMPLETE+DECLINED | | `llhttp.ll` | 0 | NO_VECTORS | | `pid1-shim.ll` | 0 | NO_VECTORS | | `secp256k1-precomputed-ecmult-gen.ll` | 2,816 | COMPLETE | | `secp256k1-precomputed-ecmult.ll` | 131,072 | COMPLETE | | `sqlite3-zero-float.ll` | 8,672 | COMPLETE+DECLINED | **168,336 lanes over ~27 MB, 0 UNDER_READ, verdict `CODE_COURT_READS_THE_CORPUS_WHOLE`.** Three distinctions that measurement forced, and they are why the number above is trustworthy: - **NO_VECTORS is not UNDER_READ.** `llhttp` and `pid1-shim` carry no vector constants at all. Reporting "nothing to read" as "failed to read" would blame the court for its input. - **A declination is not a limit.** `poison`, link-time constant expressions and string data carry no exact literal; declining them is Constraint 3 working. boringssl declines 78 and sqlite3 16, with **zero** limits between them. - **Scalars count.** The court originally lifted only `` vectors and `[N x T]` arrays, and a float implementation compiled to `store double 0x3FD5555555555555` — a scalar. Two artifacts that differ in every value digested identically and ruled equivalent. Scalar lifting closed that. --- ### `execute_artifact_crucible` — the verdict IS the artifact The second Coding Court tool ingests the twelve-field **ARTIFACT INGESTION BRIEF** plus the artifact an agent generated for it, rules on an eight-rung ladder, and seals the artifact **only on the top rung**: ``` 7 CALORIE_AFFINE_ARTIFACT_DELIVERED 6 ARTIFACT_ASSEMBLED_NOT_DELIVERED 5 ARTIFACT_WIN_UNVERIFIABLE 4 ARTIFACT_PROTOCOL_CONTRADICTED 3 ARTIFACT_TARGET_ABSENT 2 ARTIFACT_LAW_BROKEN 1 NOT_KNOWN 0 REFUSED_* (the brief is not a brief) ``` Two payload shapes go in the same `artifact` field. **Source** is judged line by line — the brief's Losing Moves plus Affine law that holds unasked (Constraint 3 zero floats, 4 no stubs, 5 determinism, LAW 4/9 no classical search) — and caps at rung 6 on a cell, because no cell carries a compiler and the court will not certify a build it never performed. **A compiled wasm module** goes in as base64: the court walks the section table, seals the bytes, and returns them as an MCP `resource` with `blob`, `mimeType application/wasm`, `artifact_kind wasm.module`, `byte_count` and `sha256` — with `law_checked false`, because it did not read source and says so. Measured on the apex 2026-09-02: | call | result | |---|---| | the court's blank template, unfilled | `REFUSED_UNFILLED_PLACEHOLDER` naming `Purpose` | | prose without a brief | `REFUSED_NO_BRIEF` | | AArch64 brief + `ld1 {v0.2d…}, [x0]` / `ret` | `ARTIFACT_ASSEMBLED_NOT_DELIVERED` (`hasAssembler=false`) | | same, with a contradicting `target_architecture` argument | `REFUSED_ARCHITECTURE_CONFLICT` | | `cbz x0, 1f` under a brief that bans branches | `ARTIFACT_LAW_BROKEN · branch` | | `var scale: Double = 1` under a Swift brief | `ARTIFACT_LAW_BROKEN · Constraint 3` | | the served 4,946-byte `affine_wasm_ide.wasm`, base64 | rung **7**, returned byte-exact; receiver re-digest equals the declared sha256 | The brief the court recognises, verbatim, and the whole ladder: [Affine Coding Court](Affine-Coding-Court-Architecture.md). A filled brief for a generic wasm IDE client, and the page that loads and runs what comes back: [Court Client](Affine-Court-Client-Template.md). ## Surface 2 — Classical vs Affine.Earth codegen The court's companion study compiles **one computation for two targets** and reads what the compiler actually put in the binary. ``` CLASSICAL (poison-ieee754) vs AFFINE.EARTH (vqbit-exact) float constants in artifact classical 4 affine 0 exact constants lifted classical 2 affine 14 court CODE_IR_DIVERGED intended classical artifact actually holds error 1/3 6004799503160661/18014398509481984 1/54043195528445952 proven: CLASSICAL_ARTIFACT_HOLDS_INEXACT_CONSTANTS ``` `0x3FD5555555555555` is not a description of rounding. It **is** the rounding, frozen into the object file. The error is computed with integer arithmetic only — the nearest double to a rational is found by scaling into `[2^52, 2^53)` and rounding half-to-even, never by constructing a `Double`. Measuring float error with a float would be measuring the thing with itself. **The counter-example matters as much.** A dyadic computation (`1/2`, `3/4`, `2`) is exactly representable and the study says so — `BOTH_ARTIFACTS_EXACT`. A study that reported every classical artifact as broken would be worthless. --- ## Surface 3 — Quantum verification (QC-001 … QC-021) Twenty tools that certify a **presented witness** exactly. They do not search. That is the honest claim and it is stated on every tool. | Tool | Certifies | |---|---| | `verify_shor_witness` | `(N, halfPow, factor, cofactor)` — a claimed factorisation | | `verify_period` | `a^r ≡ 1 (mod N)`, `gcd(a,N)=1` | | `verify_grover` | presented 0/1 oracle (length 2..8) vs the marked INDEX — `oracle=0001 marked=3` is WIN; `marked=2` is MISS | | `verify_qft_phases` | `phase[j] = (j·k)/n` as exact rationals | | `verify_qpe_phase`, `verify_phase_kickback` | phase equals `k/2^m` exactly | | `verify_hhl` | `A x = b` exactly, integer `A`, rational `b`,`x` | | `verify_deutsch_jozsa`, `verify_bernstein_vazirani`, `verify_simon` | oracle-class claims | | `verify_amplitude_amplification`, `verify_amplitude_estimation`, `verify_quantum_counting` | count/fraction equals `M/N` exactly | | `verify_quantum_walk`, `verify_teleport`, `verify_superdense`, `verify_bell_measurement` | reconstruction and class bits | | `verify_vqe_energy`, `verify_qaoa_energy` | the problem, not the pulse schedule | | `verify_topological_word` | sealed Eisenstein `(q,r)` for cited words | | `verify_presented_pair` | two-way affine pair; either face posts | Every one refuses floats. The response carries `energy_num`/`energy_den` as an exact rational. ```bash # QC-001 — a real factorisation of 15 {"name":"verify_shor_witness","arguments":{"N":"15","halfPow":"4","factor":"3","cofactor":"5"}} # -> verdict WIN, status CALORIE, detail "factors=3*5" ``` A false claim returns `MISS` **with the arithmetic that refutes it**, not a bare rejection: ```json {"tool":"verify_grover","verdict":"MISS","status":"MISS","detail":"marked=2 ones=1"} ``` --- ## Surface 4 — QMA and complexity | Tool | What it locks | |---|---| | `execute_2local_hamiltonian` | ZZ terms as exact rational Jordan exclusions on the UUM-8D torus | | `route_spin_glass_manifold` | frustrated Ising as discrete ±1 torus vectors | | `verify_n_representability` | 2×2 rational 2-RDM | | `execute_exact_permanent` | exact integer permanent, n ≤ 3 | These are the four studies the Math Court page walks. Fixture energies: 2-local **−1/1**, spin-glass **−1**, N-representability **WIN**, 3×3 permanent **6**. --- ## Surface 5 — UUM-8D lattice and the affine key | Tool | Use | |---|---| | `verify_jordan_bond` | J_Z shear: `(A·K + A_p1·K) − (K·B + K·B_p2) = 0^8` | | `lattice_op` | `verify · shear · add · sub · mul · distance · locking_*` on 8-lane decimal lattices | | `project_affine_key` | post `A`, receive `Q = A·G` (WIN, measured: `A=1` → the generator). Post `q_hex` ALONE and the reverse face is the discrete log: verdict **`CHI_EXHAUSTED`**, `energy_num` = n (~1.16e77, the bond dimension this instance requires) over `energy_den` = 4096 (the ceiling), `ground` = x(Q) which is public. A cost report at the current probe — not a claim of impossibility, not a graded pair; the wire `status` reads MISS today | | `project_shor_twin` | QC-001b: post `N=3233 halfPow=794` → factors `61*53`; post the factors → `a=794`. A bijection (two gcds forward, CRT back), never a period search | | `expose` | generic court ingest — strobe → emit → seal | | `math_court` | domain + role + source across every court domain | Lattices are `x0,x1,x2,x3,x4,x5,x6,x7|z` decimal strings — eight lanes and a homology `z`. **The quarantine is live and it fires.** A naive uniform lattice is not admitted: ```json {"tool":"verify_jordan_bond","admitted":false,"bonds_scanned":1,"matched_index":-1, "quarantine_mask":1,"proven":"AFFINE_MCP_QUARANTINE_PROJECTED"} ``` That is the surface declining to seal something it has not matched against the sealed corpus — the mechanism working, not an error. --- ## Surface 6 — Corpus and mining census | Tool | Returns | |---|---| | `corpus_bonds` | sealed bonds from `GAIA_SPATIAL_BOND_WIRES`, filterable by `mined_from` | | `corpus_coverage` | fleet-wide mining coverage from the KV cursor bucket, per target and per cell | | `corpus_capability_map` | census of what the corpus captured over a bounded window | | `feeds_catalog` | every feed a client can drive a game from | These are read surfaces over what the nine cells have actually sealed. `corpus_coverage` reports per-cell so a gap in one cell cannot hide behind eight healthy ones. --- ## Surface 7 — Real-world exact geometry | Tool | Domain | |---|---| | `atc.assert_4d_deconfliction` | exact 4D separation over declared trajectories, integer-scaled geodetic | | `weather.convective_containment` | exact containment of a track against convective boundaries | | `noaa_goes_r_weather` | live NOAA feed for the aviation radar lane | | `twin.robotics.evaluate_exact_ik` | exact integer inverse kinematics over a declared piece chain | Coordinates are integer-scaled (milli-degrees, micro-units). Separation is an exact inequality, not a tolerance — which is the whole reason to do it this way for anything that has to be right. --- ## Surface 8 — Rendering and language games | Tool | Use | |---|---| | `critique_frame` | grade a rendered frame, return **integer** corrections | | `game_frame_meta` | run a language-game context, return state plus the cell's self-evaluation | `critique_frame` is deterministic: the same frame yields the same corrections on every cell. A critic that returned a different opinion per host could not be used to close a loop. --- ## Surface 9 — Membrane and controller | Tool | Use | |---|---| | `membrane_health` | stateless membrane identity — mode, genesis epoch, subjects, cell listen | | `umc_status` | UMC tip, documented tool surface, NATS subjects | | `umc_direct` | GAV direct: seed → decompose → measure. **Grant class mesh** — an anonymous call is `REFUSED_GRANT_MESH_IDENTITY_REQUIRED` (measured 2026-09-02); send `user_vqbit_hash` (32 lowercase hex), `entity_id` or `wallet_hash` | | `umc_resume` | resume Long Play from the latest tip; same identity requirement | | `execute_transition` | certified membrane: rational S4/C4 lanes → SCF boundary | | `ide_rebuild_mesh` | founder-cell only | --- ## Validation — how every surface is checked The surface validates itself on each request, and the result is public at `https://affine.earth/language-invariant/alive`. **Five control arms, all of which must FIRE for the registry to read healthy.** A gate that has never fired is not a passing gate: | Arm | Proves | |---|---| | `control_arm_float_schema_refused` | a schema declaring `type:number` is refused | | `control_arm_register_schema_refused` | a register-shaped schema is refused | | `control_arm_empty_refused` | an empty capability is refused | | `control_arm_asymmetric_fires` | an asymmetric declaration is caught | | `control_arm_mine_unexposed` | a miner verb on the public court is refused | Plus `wire_structured_parity` — the parsed face must carry exactly the servable population — and `a2a_tasks_resolve`, which requires every advertised A2A task to resolve to a servable tool. **The registry is one table with five generated faces.** MCP `tools/list`, the cell wire, REST routes, A2A tasks and the UI catalog are all derived from the same `CapabilityRegistry`. There is no second place to edit, so the MCP surface cannot drift from the REST surface — they are the same rows. **Honest population accounting.** 54 entries, **49 servable**, 5 absent (`/language-invariant/alive`, measured 2026-09-02: `entries 54 · servable 49 · absent 5 · CAPABILITY_REGISTRY_ONE_HOME_OK`, all five control arms fired, `a2a_task_count 45`). The absent five are declared and not served, and the surface says so rather than advertising them. An MCP that lists a tool it cannot perform is worse than one that lists fewer. **Test coverage backing the surface:** `LanguageLedgerTests` 652 tests, `GaiaFTCLCoreTests` 13, `VQbitSubstrateTests`, `GymWasmClientTests`, `IntegrationTests` — all bundles passing, 0 failures. The Code Court's reach is measured over the 27 MB IR corpus on every run rather than asserted. **Per-cell, not round-robin.** `tools/list` is checked against all nine A records with pinned SNI, because nine correct answers through a load balancer do not prove nine correct cells. That method is what found a cell serving a month-stale build while answering 200 the whole time. --- ## Honest limits - **The verifiers certify presented witnesses. They do not search.** `verify_shor_witness` checks a factorisation you supply; it does not factor `N`. Deriving an unknown `k` from a bare `Q` is a measured wall and is reported as *not known*, never as solved and never as impossible. - **`code_ir_equiv` compares the constant pool.** That is a necessary condition for equivalence and a strong one for numeric kernels; it is not full behavioural equivalence. Anything outside it returns `NOT_KNOWN`. - **Five registry entries are absent**, listed above. - **`code_ir_equiv` `files` array is refused on the fleet today** (stripped before the tool sees it); use `left_file`/`right_file`. Fixed at HEAD, live after the next roll. - **`verify_presented_pair` answers WIN `co_presented_QA` when the posted face equals x(Q)** — measured on the apex 2026-09-02 with the lock `0494b9d3…`. x(Q) is public and x(Q)·G is a different point, so that WIN is a false face reaching the pair court (the founder's "the key was tested against the keyway, not the lock"). `project_affine_key` on the same face correctly answers `A_bonds_to_`. The repair binds the pair court to the strict cross-bond Face·G == Q_live (ALIGNED only on exact projective equality, APART otherwise, never a self-consistency check of the posted face) and is in the law commit riding the next binary roll; until then read `project_affine_key` for the bond, not `verify_presented_pair`. - **`project_affine_key` with `q_hex` alone answers `CHI_EXHAUSTED` with `status MISS`.** The tool's served description still says `NOT_KNOWN`; the corrected description is at HEAD. Read the `verdict` field. - **Glama's tool-definition grades, read 2026-09-02:** 24 tools A, 15 B, 15 C, 1 D (`umc_direct`); the C/D grades cite undocumented parameters (the `math_court` schema declares ~60 properties with no per-field description, `lattice_op`, `verify_jordan_bond`, the `umc_*` trio) and inconsistent naming (`atc.*` / `twin.*` dotted, `verify_*` snake, bare verbs). Glama also scores "Tool Count 2/5 — 49 tools is far above the typical well-scoped server". Those are the registry rows to describe next. - **`ide_rebuild_mesh` is founder-cell only** and will refuse elsewhere. --- ## Replaying any claim on this page ```bash # every number above came from this surface; re-take any of them curl -sS https://affine.earth/language-invariant/alive | jq . | head -40 ``` The apex answers on nine cells. Pin SNI to any one of them with `--resolve affine.earth:443:` and you get that cell's own answer, not a balanced one.