> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twirx.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Frontier Agent and MCP

> How a frontier model consumes deterministic TWIRX state through the compact read-only MCP interface.

> **Authority:** Explanatory binding reference · **Status:** Protected E4.7 candidate, not deployed · **Applies to:** E4.7 · **Verified against:** current checkout · **Source:** `internal/semanticmcp`, `internal/frontieragent`, ADR 017 and ADR 020

## Purpose

The frontier model is a consumer of TWIRX, not part of the protocol authority:

```text theme={null}
human question
→ frontier model proposes tool calls and a typed query
→ deterministic TWIRX validates and executes
→ model proposes evidence-bound claims
→ deterministic reconciler accepts or withholds each claim
```

The binding has nine tools:

```text theme={null}
twirx_universes  twirx_search   twirx_describe  twirx_context
twirx_query      twirx_compare  twirx_trace     twirx_explain
twirx_stats
```

It deliberately has no URL, browser, payment, action, mutation, credential, or
canon-admission parameter.

The binding uses progressive disclosure. `twirx_universes` distinguishes
queryable snapshot slices from described future universes; `twirx_search`
identifies executable templates; and `twirx_describe` returns a fully defaulted,
ready-to-run query. `twirx_trace` returns a compact source/proof projection by
default and requires an explicit `full` request for the larger proof-complete
form. The active runtime traces packet identifiers only, so the tool schema does
not advertise frame identifiers.

## Task-ready agent context

`twirx_context` composes one exact typed query into a bounded LLM-facing
projection:

```text theme={null}
effective query
+ query/result identities and deterministic plan
+ reconciled source-bound claim candidates
+ query-local native-to-semantic bindings
+ lane, mapping, freshness and authority counts
+ exact proof-escalation calls
```

It accepts no natural-language question. A model may propose the Semantic
Query, but schema validation and deterministic snapshot execution remain the
only execution authority. The default context carries no packet trace bodies;
it provides exact packet identifiers for selective `twirx_trace` escalation.
The context is limited to 64 rows, 20 requested compact traces and 768 KiB of
encoded structured content.

The query-local semantic bindings report what the returned packets carry. They
are explicitly not normative concept definitions and cannot admit mappings.

## Run the local MCP candidate

This example uses the admitted FUTO snapshot described in the quickstart. The
snapshot is a generated artifact and must exist locally.

```bash theme={null}
make build
bin/twirx-semantic-mcp \
  --snapshot var/futo-public-snapshot-d13c0bf-rebuilt \
  --id sha256:54739822257ef617b136454285a8fd47802f0960c7cf53a49abd2d5d1f1389c5 \
  --listen 127.0.0.1:8091
```

The listener accepts literal loopback addresses only. A reverse proxy and
public deployment require a separate operational admission.

Discover the tool catalog:

```bash theme={null}
curl -sS http://127.0.0.1:8091/mcp \
  -H 'Content-Type: application/json' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```

Call `twirx_query` by placing the same bounded JSON query used by the Lab under
`params.arguments.query`. The result carries the snapshot, canonical query and
canonical result digests, native values, packet evidence identifiers, and an
execution plan. The plan must report zero origin-network requests for the
immutable runtime.

## Fresh agent audit

On 2026-08-13, an MCP client exercised all nine tools against snapshot
`sha256:54739822257ef617b136454285a8fd47802f0960c7cf53a49abd2d5d1f1389c5`.
The World Bank population template returned four source-bound rows after
scanning twenty packets and excluding five fixtures, with zero origin calls.

```text theme={null}
query:  sha256:8de55289ea3a3f83d68d0cad0c91d74570365a9feac41499a93beca8950b9647
result: sha256:8bf1241d59a595be8b70bbf3720ab4b50e55ad00d3d75870ba18b49bb42e7af4
```

The audit led to effective query defaults, explicit universe availability,
stable snake-case counters, readable economic telemetry, compact hex-digest
packet traces and deterministic explanation stages. The subsequent context
audit returned four reconciled claim candidates and four semantic bindings in
9,517 encoded JSON-RPC response bytes, compared with 13,089 bytes for separate
query, compact-trace and explain calls: 27.29% fewer encoded bytes for this
fixture. This is a binding-level measurement, not a model-token or end-to-end
performance claim. See `reports/e4-7-agent-context.md`.

## Frontier provider boundary

`twirx-frontier-agent inspect` validates the pinned provider configuration
without making a request. `run` additionally requires an explicit paid-execution
flag, an API key supplied only through the process environment, and a positive
USD ceiling. The candidate fixes the model, Responses endpoint, MCP endpoint,
answer schema, output bound, timeout, and one-repair limit.
The strict Agent Answer 0.2 schema closes every object and requires every declared field;
optional claim values are represented explicitly as an empty value or `null`.
The provider constructor rejects a relaxed schema before any paid request.
Every claim must repeat the evidence packet's exact epistemic lane, mapping
status, freshness status and authority class. Attempted strengthening fails
reconciliation.

No paid run is part of E4.7 yet. The model lock explicitly records that the
official catalog did not expose a verified dated snapshot identifier in this
environment.

## Failure behavior

* Unknown MCP fields and tools fail closed.
* Oversized or deeply nested JSON fails before execution.
* A caller-supplied URL is rejected.
* Unsupported evidence identifiers cause claims to be withheld.
* Source-stated, provisional, unresolved, withheld and conflicting
  qualifications cannot be silently exchanged.
* Lane, mapping status, freshness status and authority class cannot be silently
  strengthened or exchanged.
* The spend ceiling is checked conservatively before each provider call.
* One failed reconciliation permits one bounded repair; a second failure ends
  the run.

## Security and conformance

The MCP service is stateless and opens an admitted immutable snapshot with
fixtures excluded. The provider process has model credentials but no deployment
or origin-acquisition authority. The MCP process has snapshot read access but no
model credentials. Conformance requires the embedded nine-tool catalog,
bounded parser tests, evidence-escalation tests and local snapshot execution.

## Implementation status

Local MCP discovery and a two-origin query have passed. The public remote MCP
endpoint and frontier-provider run have not been deployed or executed. No
benchmark advantage is claimed.

The public explanatory paths are `/agent/` and `/bench/` on `twirx.org` after
the corresponding website release is admitted.