Use Lispex with an AI Assistant

Before you connect

Install the Native product from Downloads and check it.

lispex --version

The MCP server is part of that executable. Reference, evaluation, diagnostics, and the built-in comparison between the tree run and Rust need no repository checkout, Node package, network service, extra engine, or API key.

The lispex command in the MCP configuration must be the Native executable from that download.

Add the server

In an assistant that accepts an MCP command, add this local stdio server.

JSON

{
  "mcpServers": {
    "lispex": {
      "command": "lispex",
      "args": ["mcp", "serve"]
    }
  }
}

The exact settings filename differs between assistants. The important contract is the command and its arguments, which are lispex mcp serve. Do not add a URL, workspace root, source path, or a path to another engine.

After reconnecting, the assistant should see exactly four tools.

lispex_reference checks forms, procedures, reader spellings, resources, and the overview of the ways a program can be run.
lispex_eval runs size-capped trusted source with the built-in Rust tree reference.
lispex_diagnostic explains one exact diagnostic code such as E302.
lispex_compare_routes runs one named comparison from a fixed list and reports agreement or disagreement without choosing an answer.

A useful first request

Ask the assistant this.

Use the Lispex tools. Check that if is admitted, write a rule that returns approve when the input is at least 10 and review otherwise, run it with input 12, and repair any diagnostic before answering.

The assistant can confirm the form, evaluate the program, and use the diagnostic catalog if its first attempt is wrong. This is more reliable than asking it to remember a Scheme dialect. Lispex requires an else arm on if, has no #; datum comment, and treats only #f as false.

What leaves your machine

Nothing is sent by the Lispex server over a network. It uses local stdio and grants submitted programs no file, clock, random, network, database, or host callback capability. The server returns a source hash, observations, and diagnostics. It does not return, log, cache, or retain the submitted source.

The surrounding assistant application has its own data policy. If the assistant itself is remote, text you type into that application may still be sent to its provider. The Lispex server neither adds nor hides that fact.

Compare execution routes

The built-in comparison needs no setup.

JSON

{
  "court": "tree-rust",
  "source": "(+ input 1)",
  "input": "41"
}

It compares the tree reference and the Rust virtual machine over the same source, input, Core IR, bytecode, and resource request. The two optional comparisons require exact extra products selected when the server starts.

JSON

{
  "command": "lispex",
  "args": [
    "mcp", "serve",
    "--topaz-vm", "/absolute/path/to/topaz-vm",
    "--topaz-compiler", "/absolute/path/to/topaz-compiler",
    "--rust-tools", "/absolute/path/to/rust-tools"
  ]
}

Then rust-topaz compares the two virtual machines, while all-four adds the tree run and a product compiled ahead of time just for that request. A missing extra product makes the requested comparison unavailable. It never turns all-four into a smaller comparison.

Limits and honest failures

One request admits at most 65,536 source bytes and 16,384 input bytes. Evaluation has a 1 MiB result and five-second wall-clock bound. Route comparison has a 4 MiB result bound. all-four has an eleven-minute window because it builds a fresh compiled product. The language's fixed transition and control limits still apply. Timeout, cancellation, malformed input, unavailable comparisons, build failure, cleanup failure, and an unknown tool remain visible.

These are authoring and operational caps, not a repeatable count of all guest work or logical allocation. The current server assumes trusted source, so do not submit a hostile rule as if the worker were a sealed sandbox. Timeout, cancellation, process termination, host OOM, panic, or trap yields no decision and no portable receipt.

The server validates optional products only from the absolute startup paths. It never discovers, installs, repairs, substitutes, retries, or falls back to another engine. Comparison results are authoring observations, not Vouch evidence, a gate grant, or a proof of semantic equivalence.

Verify the installed loop

After setup, give the assistant this short request.

List the Lispex tools. Confirm that if and + exist and that eval does not. Run (+ input 1) with input 41, explain any diagnostic by its code, then compare the same program with tree-rust.

A complete installation reports exactly four tools, returns 42, and reports the two-way comparison as completed. If an optional comparison is unavailable, the result has no attempted runs. If the runs disagree, the result says agreement: false while partial_comparison and answer_selected remain false. That is the intended result, because the assistant reports the disagreement instead of choosing a convenient answer.

Stop the MCP client or disconnect the server when you finish. Stdio closure ends the local process. There is no background service or retained project state to clean up.

Keep going

Keep the MCP Tool Reference open when building an integration. For ordinary language learning, return to the Learning Path.