MCP Server Configuration Reference

Canonical reference for every flag, environment variable, response profile, catalog mode, tracing setting, and lifecycle command exposed by ptc_runner_mcp. For installation and client wiring see mcp-server-cli.md; for the conceptual overview (when to use the server, security model, architecture) see mcp-server.md. Aggregator concepts live in aggregator-mode.md, agentic mode in agentic-mode.md, and lisp_debug in mcp-debug.md.

Boot-time configuration model

All configuration is read once at boot, either from a CLI flag or the equivalent environment variable. CLI flags win when both are set. Aggregator-mode defaults only apply when no explicit value is given. To pass flags through Claude Desktop / Cline / Cursor, append them to the args array, for example:

"args": ["start", "--max-frame-bytes", "8388608"]

Core flags

The debug ring is also byte-bounded internally: individual records are summarized above 256 KiB, and the in-memory ring is capped at 8 MiB of stored record data before oldest records are evicted. These internal caps are independent of the response-size cap above.

--trace-dir and --turn-log-dir are separate on purpose. Trace files are per-request MCP debug envelopes. The turn log is the cross-session record used by PtcRunner.TraceLog.Analyzer and the log/ introspection prelude: it records accepted session eval attempts with the client-visible ptcs_... session id, monotonic attempt number, committed turn counter, status, result preview, credential-free tool-call summaries, and session-level failure/limit reasons. Owner mismatches, stale request ids, expiry races, and aborted evals do not emit turn events because no accepted session work can be attributed.

Streamable HTTP flags

HTTP mode is opt-in. Without --http, the release starts exactly as a stdio MCP server. With --http, the process starts a Streamable HTTP listener and does not attach stdio. See mcp-server-http-deployment.md for the deployment runbook.

HTTP emits sanitized telemetry under [:ptc_lisp, :http, ...] and logs request stop lines to stderr. Raw bearer tokens and raw MCP-Session-Id values are not logged.

When the HTTP listener is bound to loopback, /mcp also requires a loopback Host/authority value. This lets non-browser clients omit Origin while still rejecting DNS-rebinding requests that arrive with a public attacker-controlled host. POST requests with a present Content-Type must use application/json or a +json media type.

Response profiles

lisp_eval and lisp_session_eval render their eval results according to a boot-time response profile (--response-profile). The default is slim: optimized for the model consuming the tool result, not for an operator reading a trace. Session utility tools such as lisp_session_start, lisp_session_inspect, and lisp_session_forget keep structured responses in all profiles.

For lisp_session_eval, normal slim/structured responses expose only the next-step contract: result text, compact session metadata, and changed binding names. Binding values, full upstream-call ledgers, and ptc_metrics are retained for explicit diagnostics instead of being echoed in every eval response.

--debug-tool implies --response-profile debug unless a profile is set explicitly. If you combine --debug-tool --response-profile slim, the client-facing response stays slim while the lisp_debug recorder still gets the full pre-slim payload internally for both stateless and session evals.

Client-facing output limits

MCP tool results are additionally shaped by profile-derived output limits before they are returned to the client. These limits are not separate CLI flags yet; they are intentionally tied to --response-profile.

validated is exact-or-absent. The server does not put partial values under validated; when the exact value is omitted, clients should look for validated_preview, validated_bytes, validated_preview_truncated, truncated, and output_truncated. feedback is also capped by profile (8 KiB / 16 KiB / 64 KiB). The final envelope guard is a last resort: it drops heavy optional fields and, for structured / debug, keeps machine-readable structuredContent with at least status, truncated, and output_truncated.

Why slim by default — wire cost. Measured by the local payload bench (drives a real @modelcontextprotocol/server-filesystem upstream; bytes ÷ 4 ≈ tokens; deterministic frame-byte counting, not LLM authoring cost):

slim is approximately 13–28x smaller than debug per call — debug's mirrored payload + ptc_metrics + upstream_calls is a roughly fixed ~800–950-token tax regardless of result size, which is exactly why it's opt-in (--debug-tool). Versus calling the upstream MCP tool directly, slim wins whenever the program collapses several calls into one and/or filters the result down (here: ~8x on the 3-file case, 1 round-trip instead of 3; ~4x on the one-line grep), and is about break-even for a single verbatim pass-through. The one-time tools/list ("cold") cost is comparable to a native server's (~2.7 K vs ~3.1 K tokens here); debug adds ~1.2 K tokens of outputSchema there. These ratios are illustrative — actual savings scale with payload size and how much the program reduces it; see aggregator-mode.md for the honest framing of what the server can and cannot measure, and re-run the bench against your own fixtures.

Catalog modes

The --catalog-mode flag (env: PTC_RUNNER_MCP_CATALOG_MODE) controls how upstream tools are exposed. Default is auto.

In lazy (or auto-resolved-lazy) mode, programs discover tools via PTC-Lisp REPL discovery forms that run inside lisp_eval — no extra MCP tool calls:

Discovery forms have a separate budget from upstream calls: --max-catalog-ops-per-program (default 25) and --max-catalog-result-bytes (default 256 KiB).

The MCP server uses the root upstream runtime machinery in frozen snapshot mode, while the server owns deployment selection and MCP presentation. At boot, ptc_runner_mcp translates its CLI/env flags into PtcRunner.Upstream.Runtime options, starts the selected root runtime as a supervised child, and registers deployment secrets with the MCP-side redaction ETS. Configured MCP stdio/http client upstreams are started and listed during server boot, and the scrubbed root snapshot is reused for tools/list. Root mix ptc.repl uses the same upstream config format but defaults to live snapshot mode, where MCP client startup/listing is attempted on discovery or call.

Aggregator-mode flags

These come into effect when at least one upstream is configured. The first two override the v1 1 s / 10 MB defaults to be more realistic for programs that orchestrate real subprocess upstreams. See aggregator-mode.md for the conceptual reference (PTC-Lisp authoring against tool/call, catalog format, error model, example programs).

CLI flag wins over env var; aggregator-mode defaults only apply when no explicit value is given.

Upstream Config Format

The upstream JSON format is owned by the root ptc_runner upstream runtime and shared by mix ptc.repl and ptc_runner_mcp. The MCP server keeps its own flag/env names, including PTC_RUNNER_MCP_UPSTREAMS, because deployment selection is server-owned, but the selected config is parsed by root upstream modules and translated into root runtime options at boot. MCP-local config remains for MCP presentation concerns such as response profiles, sessions, debug/trace, HTTP transport, agentic mode, and server-side redaction. See upstream-runtime.md for the root REPL entrypoint and snapshot-mode behavior.

Use the explicit root transport names in new configs:

• "openapi" for curated read-only JSON OpenAPI operations.
• "mcp_stdio" for external MCP servers launched over stdio.
• "mcp_http" for external MCP servers reached over Streamable HTTP/SSE.

See aggregator-mode.md for complete examples, credential emitters, static-header restrictions, and the tool/call authoring model.

OpenAPI Upstreams

An upstream entry with "transport": "openapi" exposes a curated set of read-only JSON GET operations through the same tool/call path as MCP upstreams. Required fields:

• base_url: HTTPS origin used for all operation calls.
• exactly one of schema_file or schema_url: OpenAPI schema source.
• include_operations: non-empty list of OpenAPI operationId strings to expose.

Optional fields include auth, static_headers, operation_overrides, request_timeout_ms, connect_timeout_ms, max_response_bytes, and schema_max_bytes. schema_file is the recommended production shape; schema_url is fetched during upstream startup and can delay boot up to its request timeout if the schema host hangs.

See docs/examples/observatory-openapi-upstreams.json for a production-shaped Observatory config. The matching test fixture schema lives at mcp_server/test/fixtures/openapi/observatory.openapi.json.

Tracing

Setting --trace-dir /tmp/ptc-traces writes one JSONL file per tools/call invocation under that directory. Each file contains the lifecycle telemetry events (lisp.execute.start, lisp.execute.success / lisp.execute.fail, plus per-tool-call rows when relevant) emitted by :ptc_runner. Tracing is opt-in and OFF by default — there is zero overhead when --trace-dir is unset.

--trace-payloads full includes the verbatim program, context, and rendered result bytes; summary (the default when tracing is on) records sizes and SHA-256 digests only. Pick summary unless you are actively debugging a specific call.

For local evaluation of aggregator benefits, run with:

--trace-dir /tmp/ptc-traces --trace-payloads full

Then inspect the JSONL trace file to see the generated PTC-Lisp program, program_bytes, total call duration, and result size. In debug responses, or through lisp_debug records when enabled, upstream_calls records each upstream call's server, tool, status, reason on failure, and duration. To estimate token savings, compare:

• aggregator tools/list bytes vs the sum of native upstream tools/list bytes;
• aggregator final result bytes vs the sum of native upstream raw result bytes.

Use --trace-payloads full only for local debugging or measurement; it records source programs and payload values. Use summary or none for normal operation.

Reading traces without writing code

With --trace-dir set you do not need a bespoke trace reader: point a generic filesystem MCP server (e.g. @modelcontextprotocol/server-filesystem) at the trace directory and let the client read the raw per-call JSONL. The zero-code escape hatch — fine for ad-hoc digging, but lisp_debug (see mcp-debug.md) is the purpose-built interface, and ptc_viewer (mix ptc.viewer in the repo) is the human-facing web UI for the same trace files.

Lifecycle commands

The release binary defaults RELEASE_DISTRIBUTION=none so MCP clients can run multiple stdio subprocesses concurrently without Erlang node-name collisions:

ptc_runner_mcp start      # foreground, stdio attached (what MCP clients use)
ptc_runner_mcp version    # print "ptc_runner_mcp <version>"
ptc_runner_mcp eval "..."  # run an expression in a one-shot VM

For remote IEx debugging, start the process with distribution enabled and a unique node name, then attach with the same settings:

RELEASE_DISTRIBUTION=sname RELEASE_NODE=ptc_runner_mcp_debug_1 ptc_runner_mcp start
RELEASE_DISTRIBUTION=sname RELEASE_NODE=ptc_runner_mcp_debug_1 ptc_runner_mcp remote