MCP Tool Reference

Use this reference to construct a Lispex tool request and read its response. It also explains how the calling application controls tools and external actions.

Install the Native executable and follow the connection guide first. lispex mcp serve exchanges JSON messages through local standard input and output. The server provides MCP protocol version 2025-11-25; the client initializes the connection before listing or calling tools.

A request and its response

To explain a reader error, call lispex_diagnostic with {"code": "E100"}. The full JSON-RPC request after connection initialization is shown below. The client chooses id to match a response to its request.

JSON

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "lispex_diagnostic",
    "arguments": {
      "code": "E100"
    }
  }
}

The response uses the same id. Its result.structuredContent.result contains the following fields, among others.

JSON

{
  "known": true,
  "code": "E100",
  "severity": "error",
  "phase": "reader",
  "family": "illegal-token-or-structure",
  "exit_status": 1,
  "raising_condition": "The reader cannot form one admitted datum."
}

This means the reader could not parse one valid data value. Here, exit_status: 1 describes the diagnosed error, not a server shutdown. The lookup succeeds, creates no output file, and leaves the connection open.

Tool arguments

Tool arguments are JSON objects. Extra argument fields are rejected.

Tool	Arguments	Result
`lispex_reference`	Optional `topic`; optional exact `name` requires `topic`	Installed language entries
`lispex_eval`	Required `source`; optional `input`	Lispex Interpreter values, output, warnings, and diagnostics
`lispex_diagnostic`	Required `code`, an `E` or `W` followed by three digits	Catalog entry and cause, or `known: false`
`lispex_compare_routes`	Required `court` and `source`; optional `input`	Compared results, resource use, and product identifiers

source is the complete UTF-8 source as a string. input is a string containing one Lispex data value, such as "41". The program receives that value under the name input.

For lispex_reference, use these topic names.

Topic	Contents
`forms`	Language forms and their shapes
`procedures`	Built-in procedures and their arguments
`reader`	Accepted source spellings, including comments
`resources`	Resource profiles
`routes`	Execution methods

An empty argument object lists topics. A topic without a name lists its entries. An unknown name returns known: false; for example, {"topic": "procedures", "name": "eval"} returns disposition: "absent".

Reading an evaluation result

A tool response puts its JSON result in structuredContent and a text copy in content. The connection guide includes a complete evaluation example.

Field in `structuredContent`	Meaning
`schema`	`lispex.mcp-eval-result/v1`, the version of this result format
`status`	Evaluation outcome, such as `ok` or `runtime-error`
`values`	Returned values written as Lispex text
`stdout`	Captured output, including printed top-level values
`diagnostics`, `warnings`	Errors and warnings to inspect
`exit_status`	Evaluation status, separate from the server process
`source_sha256`, `input_sha256`	Source and input identifiers for the evaluated request
`resource_profile`	Limits and the resource outcome
`source_retained`	`false`; the server releases request source after the call
`vouch_authority`	`false`; the Vouch workflow handles authentication and acceptance separately

For example, {"source": "(car)"} returns status: "runtime-error", diagnostic E302, and exit_status: 1. Look up {"code": "E302"} to learn that the call has the wrong number of arguments.

Selecting a comparison

The court argument selects one fixed set of implementations.

`court`	Products
`tree-rust`	Built-in Lispex Interpreter and Lispex VM

A virtual machine executes compiled instructions.

The server uses the same source, input, and requested resources for the comparison. It records the identifiers of Core IR, the intermediate program with resolved name references, and the compiled bytecode.

Each implementation's entry in observations contains semantic results and resources. Product identifiers appear in products.

Result field	How to read it
`required_routes`	The complete selected set
`status`, `comparison_completed`	Whether the comparison finished
`agreement`	Whether results and resource observations match under the comparison rules
`mismatch_axes`, `resource_mismatch_axes`	Compared properties that differ
`partial_comparison`	`false`; missing products stop the selected comparison
`answer_selected`	`false`; inspect the recorded results when they disagree

Other `court` values

tree-rust is available with the base server. The tool schema also lists rust-topaz and all-four. They run only with Topaz companion products supplied when the server starts. Without those products the tool returns status: "unavailable", for example missing_prerequisites: ["topaz-vm"] and attempted_routes: [].

Resource profile

Use these tools for reviewed source while writing programs. The profile ID is lispex-mcp-local-authoring/v1.

Resource	Limit
Source per request	65,536 bytes
Input per request	16,384 bytes
Evaluation result	1 MiB
Evaluation wall time	5 seconds
Comparison result	4 MiB

The server reports timeouts, cancellation, malformed input, and missing products. Comparison results also report build, cleanup, and process failures. Read the status before interpreting a result as a completed computation. For application rules supplied by untrusted users, use the resource-controlled evaluator.

Data and permissions

Source and optional input reach the local server through stdio. A worker process holds request data in memory and releases it when the request ends. Results include source identifiers, computed values, output, resource observations, and diagnostics. The assistant application applies its own policy to text entered into it.

The calling application controls tool access and permissions for external actions. A rule's return value is data that the application can use in its decision. Lispex Vouch adds publisher authentication, binding to the exact request, and re-execution. The receiving application applies its acceptance rules and decides whether to perform an external action.

Connection guide · Runtime implementations · Diagnostic catalog