ptc_runner_mcp

Copy Markdown View Source

ptc_runner_mcp is a standalone MCP server release for coding agents and other MCP clients. In the MCP initialize handshake it advertises the server name ptc_lisp. It gives the client a safe code mode backed by PTC-Lisp, plus optional modes for aggregating upstream MCP tools, stateful Lisp sessions, diagnostics, and private-network HTTP deployment.

The server does not contain an LLM. Your MCP client or agent does the reasoning; the ptc_lisp MCP server runs bounded, deterministic work when the model needs help with counting, filtering, reshaping JSON, validating schemas, or composing MCP tool results.

For the deeper rationale, architecture, and security model, see docs/mcp-server.md.

Why Use It

PTC-Lisp is intentionally smaller than Python or JavaScript execution servers:

  • no filesystem, network, or process execution from the program;
  • per-call resource limits and bounded concurrency;
  • structured errors that an LLM can repair from;
  • optional JSON Schema validation for machine-readable results;
  • no cross-call state unless explicit session tools are enabled;
  • upstream MCP access only through configured, mediated calls in aggregator mode.

The practical advantage is that the sandbox is part of the language surface, not something you have to recreate with containers around a general-purpose interpreter.

Each program runs in its own lightweight BEAM process. If a program is slow, too large, or crashes, the server can kill just that worker and keep serving other requests. This gives PtcRunner process-level isolation without the startup cost of a container or Python sandbox per call, and lets the server handle concurrent calls while keeping MCP and upstream connections warm.

Core Ideas

Code mode. The default tool, lisp_eval, accepts a PTC-Lisp program plus optional JSON context and output_schema. The program runs in an isolated BEAM process and returns a compact MCP tool result. Use it for deterministic computation that LLMs often do unreliably: counts, sums, filters, schema-shaped extraction, and data reshaping.

MCP aggregation. With an upstream config file, PTC-Lisp programs can call other MCP servers through (tool/call ...). One sandboxed program can search, filter, join, and reduce upstream tool results before the final answer reaches the LLM. This reduces round-trips and context size without exposing arbitrary I/O to the program.

Server deployment. The same executable can run as a local stdio MCP server for desktop/coding agents, or as a Streamable HTTP MCP endpoint for private-network deployments.

Modes

ModeEnable withWhat it adds
Stdiodefault startLocal MCP subprocess for Claude Desktop, Cursor, Cline, Claude Code, and similar clients.
HTTP--httpStreamable HTTP endpoint with bearer auth, health/readiness endpoints, and session ids.
Aggregator--upstreams-config <path>Lets lisp_eval programs call configured upstream MCP servers.
Sessions--sessionsAdds lisp_session_* tools with explicit persisted Lisp bindings and bounded history.
Agentic--agenticAdds experimental lisp_task, a natural-language task tool backed by a planner LLM. Requires aggregator mode.
Diagnostics--debug-tool, --trace-dirAdds lisp_debug and/or per-call JSONL traces for troubleshooting.

Full flag reference: docs/mcp-server-configuration.md.

Install on macOS

Current packaged support is macOS. Download the ptc_runner_mcp archive for your Mac from the project release artifacts, unpack it, and use the executable inside the release directory.

Smoke test:

/absolute/path/to/ptc_runner_mcp/bin/ptc_runner_mcp version

If macOS blocks an unsigned local binary, right-click it once and choose Open, or remove the quarantine attribute:

xattr -d com.apple.quarantine /absolute/path/to/ptc_runner_mcp/bin/ptc_runner_mcp

Building from source, release internals, and remote IEx debugging are covered in DEVELOPMENT.md.

Use The Docker Image

When published, the MCP Docker image is available from GitHub Container Registry:

docker pull ghcr.io/andreasronge/ptc-runner-mcp:TAG

Docker defaults to HTTP mode and binds inside the container on 0.0.0.0:7332:

export PTC_RUNNER_MCP_HTTP_AUTH_TOKEN="$(openssl rand -base64 32)"

docker run --rm -p 7332:7332 \
  -e PTC_RUNNER_MCP_HTTP_AUTH_TOKEN="$PTC_RUNNER_MCP_HTTP_AUTH_TOKEN" \
  ghcr.io/andreasronge/ptc-runner-mcp:TAG

Health checks:

curl http://127.0.0.1:7332/health
curl http://127.0.0.1:7332/ready

For local MCP clients that launch a stdio subprocess through Docker:

docker run --rm -i \
  ghcr.io/andreasronge/ptc-runner-mcp:TAG \
  start

To run as an HTTP aggregator with a mounted upstream config:

docker run --rm -p 7332:7332 \
  -e PTC_RUNNER_MCP_HTTP_AUTH_TOKEN="$PTC_RUNNER_MCP_HTTP_AUTH_TOKEN" \
  -v "$PWD/upstreams.json:/etc/ptc-runner/upstreams.json:ro" \
  ghcr.io/andreasronge/ptc-runner-mcp:TAG \
  start --http --http-host 0.0.0.0 \
  --upstreams-config /etc/ptc-runner/upstreams.json

The base image does not include Node, npm, Python, or uv. Stdio upstreams that depend on those runtimes should use a derived image.

Snapshot REPL Quick Start

This is for human testing and debugging of the MCP server, agentic workflows, and upstream server wiring. It is not the normal agent integration path.

docker pull ghcr.io/andreasronge/ptc-runner-mcp:snapshot

export RELEASE_COOKIE="$(openssl rand -base64 48)"
export PTC_RUNNER_MCP_HTTP_AUTH_TOKEN="$(openssl rand -base64 32)"

docker run --rm -it \
  --name ptc-mcp-debug \
  -p 7332:7332 \
  -e RELEASE_DISTRIBUTION=name \
  -e RELEASE_NODE=ptc_runner_mcp@127.0.0.1 \
  -e RELEASE_COOKIE="$RELEASE_COOKIE" \
  -e PTC_RUNNER_MCP_HTTP_AUTH_TOKEN="$PTC_RUNNER_MCP_HTTP_AUTH_TOKEN" \
  ghcr.io/andreasronge/ptc-runner-mcp:snapshot

In another terminal, open the bundled PTC-Lisp REPL inside the same container:

docker exec -it ptc-mcp-debug \
  /opt/ptc_runner_mcp/bin/ptc_lisp_repl --display envelope

Try:

(+ 1 2)
(apropos "mcp")
:tools
:quit

Use --display envelope while debugging because it shows the full MCP tool response envelope that clients receive. The docker exec approach does not publish EPMD or BEAM distribution ports; keep the Erlang cookie private because it grants full VM RPC access inside the node.

Remote PTC-Lisp REPL

For human debugging without installing Erlang or Elixir on the host, run the bundled REPL wrapper from the release:

/absolute/path/to/ptc_runner_mcp/bin/ptc_lisp_repl

The REPL evaluates through the same MCP tool facade as clients. In aggregator mode it can call configured upstream MCP tools from PTC-Lisp programs, and its success/error text is the same feedback shape the LLM sees, adjusted for an interactive terminal. Use --display envelope to show the full pretty JSON MCP tool response envelope, or switch while running with :display envelope. --display json emits the same envelope as compact JSON.

The running server must have distributed Erlang enabled. The wrapper uses the Erlang/Elixir runtime bundled inside the release. The Erlang distribution cookie grants full VM RPC access, not only PTC-Lisp access, so use a high-entropy cookie and do not expose EPMD or BEAM distribution ports publicly.

For Docker, use the same bundled wrapper inside the container:

docker exec -it ptc-mcp-debug \
  /opt/ptc_runner_mcp/bin/ptc_lisp_repl --display envelope

Advanced users can still attach remote IEx and start the REPL manually:

PtcRunnerMcp.Repl.start(display: :envelope)

For local development from this repository, the same REPL is also available as a Mix task from mcp_server/:

mix mcp.repl --display envelope
mix mcp.repl --upstreams-config ./upstreams.json --display envelope
mix mcp.repl --stateless --eval "(+ 1 2)"

Use From A Coding Agent

Most local MCP clients should run the server in stdio mode:

{
  "mcpServers": {
    "ptc-runner": {
      "command": "/absolute/path/to/ptc_runner_mcp/bin/ptc_runner_mcp",
      "args": ["start"],
      "env": {}
    }
  }
}

Use the same shape for Claude Desktop, Cursor, Cline, and other clients that accept MCP JSON config. For Claude Code:

claude mcp add ptc-runner \
  /absolute/path/to/ptc_runner_mcp/bin/ptc_runner_mcp \
  start

To pass options, append them after start:

"args": ["start", "--sessions", "--trace-dir", "/tmp/ptc-traces"]

The release defaults RELEASE_DISTRIBUTION=none, so multiple clients or health probes can launch independent stdio subprocesses without colliding on an Erlang node name.

Aggregator Example

Create an upstream config:

{
  "upstreams": {
    "fs": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp/sandbox"]
    }
  }
}

Start the MCP server with:

"args": ["start", "--upstreams-config", "/absolute/path/to/upstreams.json"]

lisp_eval can now use (tool/call ...) to call the configured fs server from inside one bounded PTC-Lisp program. See docs/aggregator-mode.md for the authoring model, catalog discovery, error semantics, credentials, and HTTP / OpenAPI upstreams. For a coding-agent setup where PtcRunner talks HTTPS to a JSON API described by OpenAPI, see HTTPS OpenAPI Upstream For Coding Agents.

Deploy As A Server

HTTP mode is opt-in and intended for private-network deployments behind a trusted TLS edge or load balancer:

export PTC_RUNNER_MCP_HTTP_AUTH_TOKEN="$(openssl rand -base64 32)"

/absolute/path/to/ptc_runner_mcp/bin/ptc_runner_mcp start \
  --http \
  --http-auth-token "$PTC_RUNNER_MCP_HTTP_AUTH_TOKEN"

Defaults:

  • MCP endpoint: POST /mcp
  • bind: 127.0.0.1:7332
  • liveness: GET /health
  • readiness: GET /ready

Non-loopback binds always require a bearer token. Use docs/mcp-server-http-deployment.md as the deployment runbook.

More Docs

License

Apache-2.0. See LICENSE at the repo root.