@logicpearl/mcp · stdio MCP server

Give your agent a deterministic decision tool.

One npx installs the LogicPearl MCP server into Claude Desktop and Cursor, with timestamped backups of each config. Every chat then has access to three tools. The LLM decides when to call them; LogicPearl decides what they return.

$ npx @logicpearl/mcp install

stdio transport · Claude Desktop + Cursor · MIT licensed · ~500 LOC

Install

One command, two hosts, reversible.

The install subcommand finds each host's MCP config, saves a timestamped backup, writes the logicpearl entry, and tells you what to relaunch. Pass --dry-run first to see exactly what would change.

terminal

$ npx @logicpearl/mcp install

LogicPearl MCP · install

Claude Desktop  ~/Library/Application Support/Claude/claude_desktop_config.json
  · backup saved: claude_desktop_config.json.2026-04-22T18-30-01.bak
  ✓ added logicpearl entry

Cursor  ~/.cursor/mcp.json
  ✓ added logicpearl entry

────────────────────────────────────────────────────

✓ Configured 2 hosts.

Next:
  1. Quit and relaunch the host app so it picks up the new config.
  2. In a chat, try: "List the rules in the refund-eligibility artifact."
  3. The host will call the logicpearl_list_rules tool.

Only want one host? --host claude or --host cursor. Want to preview first? --dry-run.

Tool surface

Three tools. Minimum to make the decision and explain it.

logicpearl_evaluate

Deterministically evaluate a compiled artifact against a feature vector. Returns {verdict, allow, fired_rules, counterfactual_hints, bitmask, latency_ms}. Same input always yields the same bitmask.

logicpearl_describe_artifact

Return the artifact's feature schema, allowed string codes, default action, and an optional extraction-prompt template. Agents call this first so they know what vectors to build.

logicpearl_list_rules

Enumerate every rule with id, action, human-readable label, the features it touches, and a counterfactual hint. The LLM uses this to explain a verdict without hallucinating rules.

The pattern

Free-form input → structured verdict.

Customers don't send JSON. The agent pattern is: the LLM plans, calls describe_artifact to learn the schema, extracts features from prose, calls evaluate, then calls list_rules only if it needs to explain. Copy-paste schemas below work with both Anthropic and OpenAI tool use.

Anthropic tool use

messages.create

tools: [
  {
    name: "logicpearl_evaluate",
    description: "Deterministically
      evaluate a rule artifact.",
    input_schema: {
      type: "object",
      properties: {
        facts: { type: "object" }
      },
      required: ["facts"]
    }
  }
]

OpenAI function calling

chat.completions.create

tools: [
  {
    type: "function",
    function: {
      name: "logicpearl_evaluate",
      description: "Deterministic rule
        evaluation.",
      parameters: {
        type: "object",
        properties: {
          facts: { type: "object" }
        }
      }
    }
  }
]

Why split it like this? The LLM is good at extracting structured data from prose and phrasing answers politely. It is not good at determinism, replayability, or applying a policy the same way every time. Put each on the side it's good at.

Manual setup

Not using Claude Desktop or Cursor?

Any MCP-compatible host can launch the server directly. Add this block to your host's MCP config — most use mcpServers as the top-level key.

mcp.json

{
  "mcpServers": {
    "logicpearl": {
      "command": "npx",
      "args": ["-y", "@logicpearl/mcp", "start"]
    }
  }
}

Pass --artifact <url-or-path> after start to override the default refund-eligibility artifact with your own.

FAQ

What this doesn't do (yet).

Auth

No server auth in v1.

stdio transport assumes the host is trusted — the host spawns the server as a child process. Multi-tenant hosting is a v2 problem, and it needs SSE or HTTP transport anyway.

Artifact registry

Bring your own URL or file path.

The default artifact ships with the package, but any artifact argument accepts a public https URL or a local path. A hosted registry with signature verification is planned; not here yet.

Transports

stdio only.

Enough for Claude Desktop, Cursor, and MCP Inspector. SSE / HTTP transport will land when there's a hosted use case. The three tool shapes won't change.

/ quickstart

Three npx commands to get the CLI feel before plugging the MCP server into a host.

/ healthcare

Live Wasm artifact in a browser with the governance trace view — same engine, different surface.

/ github

Source for the engine, the packages, and the examples. MIT licensed. Issues and PRs welcome.