Guide

Operating the tools from an agent

Give an agent access to the Yichus engine, call a tool, and replay the result on the command line. Choose the Node server or the browser connection; both expose the same tool catalog.

Both are npm packages that your MCP client starts with npx; neither needs Java or a build. The measured walkthrough below shows calls from a recorded experiment's harness log.

Words used below. MCP is the Model Context Protocol, the interface an agent calls tools through. A stdio server is a local process the agent's client starts and talks to over its standard input and output. WebMCP is the browser interface that lets an open page register tools on navigator.modelContext; a relay is the local process that carries those page tools to an MCP client. Sources are the program's Bosatsu files, passed to every tool as a JSON array of {fileName, source}.

1. Connect over stdio: the Node server

@yichus/api-mcp, the Node engine server, runs the engine compiled to JavaScript inside a Node 20+ process. Confirm it starts, then add it to your MCP client's server configuration.

npx -y -p @yichus/api-mcp@0.1.11 yichus-api-mcp --help
{
  "mcpServers": {
    "yichus-api": {
      "command": "npx",
      "args": ["-y", "-p", "@yichus/api-mcp@0.1.11", "yichus-api-mcp"]
    }
  }
}

Restart the client. The connection works when the server's tool list includes api_guide, api_verify, and api_why, and api_guide returns its guide. The connect reference carries the recovery steps for a server that does not appear.

2. Connect over WebMCP: the page and the relay

The WebMCP workbench opened with ?webmcp=1 registers the same catalog on navigator.modelContext and embeds the relay endpoint. The browser relay, @yichus/mcp, is the stdio server your client starts; it carries the page's tools to the agent and the agent's calls to the page.

{
  "mcpServers": {
    "yichus-browser": {
      "command": "npx",
      "args": ["-y", "@yichus/mcp@0.1.4"]
    }
  }
}

With the relay running and the page open, the client's tool list shows the relay's own tools (webmcp_list_sources, webmcp_list_tools, webmcp_call_tool, webmcp_open_page) and, through webmcp_list_tools, the page's catalog. The page also registers application tools that run a generated app in an iframe (yichus_app_open and its siblings); the connect reference lists them. Analysis runs in the page; source arguments and results pass through the relay to the client, so the relay and the client are the privacy boundary.

3. Call one tool: api_why

api_why evaluates one binding of the program on inputs you give, in a fresh in-memory world seeded with the rows you give, and reports the output, the facts that hold for every input, the facts observed on this run, the run in sentences (narrative), and the experiments the run's facts make discriminating (proposals, each a complete request; none is run unasked). Its arguments, from the catalog:

argumentrequiredmeaning
sourcesyesthe program's files, a JSON array of {fileName, source}
bindingyesthe binding to evaluate, as Pkg/Name::binding
inputsnoa JSON object of provided inputs; a missing one is filled from the seed, not from a default
rowsnoa JSON object {table: [row, ...]} seeding the world for a handler run
seed, variations, observenothe run seed (the whole run replays from it), variations per axis, and whether to run the differentials at all

The same call from a shell, through the yichus npm command line (Node 20+), which runs the same catalog. Its --source flag builds the sources array from files, so no source is pasted, and --args reads the other arguments from a JSON file; carol.json is the request on the builder page:

curl -O https://yich.us/demos/service/forum.bosatsu
npx yichus@0.3.9 call api_why --source forum.bosatsu --args carol.json --output carol-result.json

Reading the result. Show narrative verbatim to a reader who will not read JSON; the reviewer page reads one aloud. Treat soundFacts and observed as disjoint: an observed-constant result is never independence. An MCP client has no --source: the agent pastes the sources into the argument, and the parameter's declared type says it is an array.

4. The measured walkthrough: one agent's calls, from the harness log

The WebMCP cell of 2026-09-10 ran sixteen fresh agents over this connection and the command line, one task each, and the harness logged every call an agent made with its tag, the tool, the milliseconds, and the size of its arguments. Below, the rows of one agent asked to verify a program and read its conventions and routes: it opened the page, listed the tools, and made four calls. These are whole-call timings; the log does not isolate compilation time from analysis or relay overhead.

Verbatim from docs/agent-era/webmcp-cell/w1-harness-log.json; a test holds this page to that file. Lines elided are marked ....

    {
      "at": "2026-09-10T03:16:12.309Z",
      "event": "open-by",
      "path": "/api-mcp.html",
      "agent": "A-T2-s1"
    },
...
    {
      "at": "2026-09-10T03:16:16.028Z",
      "event": "list",
      "ms": 0.42077,
      "agent": "A-T2-s1"
    },
...
    {
      "at": "2026-09-10T03:16:22.125Z",
      "event": "call",
      "name": "api_guide",
      "ms": 13.858102,
      "agent": "A-T2-s1",
      "argChars": 2,
      "isError": false
    },
...
    {
      "at": "2026-09-10T03:16:36.583Z",
      "event": "call",
      "name": "api_verify",
      "ms": 10671.764459,
      "agent": "A-T2-s1",
      "argChars": 26924,
      "isError": false
    },
...
    {
      "at": "2026-09-10T03:16:41.538Z",
      "event": "call",
      "name": "api_organize",
      "ms": 349.747888,
      "agent": "A-T2-s1",
      "argChars": 26931,
      "isError": false
    },
...
    {
      "at": "2026-09-10T03:16:54.320Z",
      "event": "call",
      "name": "api_permissions",
      "ms": 114.190715,
      "agent": "A-T2-s1",
      "argChars": 26910,
      "isError": false
    },
...

How to read a row. event is what the harness saw (open-by: the agent opened a page; list: it asked for the tools; call: it called one). ms is the round trip through the relay and the page; argChars is the size of the arguments, which for a call over the forum's source is the source itself. isError is the tool's own verdict on the call.

The cell's record scores this agent's run in one row of its results table:

Verbatim from docs/agent-era/2026-09-08-webmcp-cell.md; a test holds this page to that file. Lines elided are marked ....

| A-T2-s1 | sonnet | yes | no | 6 relay rows (open, list, guide, verify, conventions, permissions) + close | 75,570 | verify 10.7, conventions 0.35, permissions 0.11 | none |
...

What the cell found. The connection passed its pre-registered gate (every agent finished, none fell back to another surface, tokens within 1.15 of the command-line arm). Two findings are the operator's to know: an omitted api_why input is filled from the seed, not left at a default, which tripped both command-line agents on one task once; and the catalog's api_organize has no diff lens, so an agent reads family membership from the conventions page.

5. Replay the run on the command line

Every api_why response echoes its request and names its sources by hash. A record is that response with each source's text added (the builder page makes one), so it holds everything needed to run the call again. The page's Open record button re-runs one in the browser. On the command line, fetch the site's record of the run above, pass its request and sources back to api_why, and compare the new result with the record:

curl -O https://yich.us/evidence/forum-demo/records/read_thread-as-carol.json

Verbatim from docs/forum-demo/outputs/npm-step4-replay-record.txt, which scripts/forum-demo/replay-npm.sh regenerates and a test holds this page to.

$ node -e 'const r=require("./read_thread-as-carol.json");console.log(JSON.stringify({...r.request,sources:r.sources.files.map(f=>({fileName:f.name+".bosatsu",source:f.content}))}))' | npx yichus@0.3.9 call api_why --args - --output rerun.json
Wrote the api_why result to rerun.json.
$ node -e 'const a=require("./read_thread-as-carol.json"),b=require("./rerun.json");for(const f of a.sources.files)delete f.content;const d=Object.keys({...a,...b}).filter(k=>JSON.stringify(a[k])!==JSON.stringify(b[k]));console.log(d.length?"differs: "+d.join(", "):"identical")'
identical

The second command prints identical, or differs: and the top-level keys whose values changed. Engine or dependency changes can produce a difference. The forum's other nine records sit beside it under https://yich.us/evidence/forum-demo/records/, named by handler and caller, such as post_reply-as-dave--thread-full.json.

Where to go next

  • Connect: both routes in full, with recovery steps, and the page tools.
  • The tool reference: every catalog tool with its parameters, generated from the catalog.
Dig deeper: where the surfaces are implemented

The catalog is src/main/resources/yichus/mcp.bosatsu, one value both surfaces read. The stdio server is packages/yichus-api-mcp/src/server.ts over the engine's JavaScript build; the page is web/api-mcp.html with web/webmcp-register.js registering its tools; the relay is packages/yichus-mcp/; the npm command line is packages/yichus-cli/. The harness that logged the measured walkthrough is scripts/webmcp-eval/. Command-line and tool JSON are pinned equal by ArtifactParityTest; each tool's surfaces are listed by ToolSurface.scala.

Where this fits

What this is about: How the pieces fit