# Cl MCP Server Integration > For Claude agents using the cl-mcp-server REPL tools. Tool mental model, usage patterns, pitfalls. Use when this capability is needed. - Skill: `tomevault-io/cl-mcp-server-integration` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/cl-mcp-server-integration` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/cl-mcp-server-integration/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/cl-mcp-server-integration --- # cl-mcp-server — Integration Skill A running SBCL process with a persistent REPL exposed as 36 MCP tools. Definitions accumulate across calls — `defun` in call 1 is callable in call 2. ## Quick Start **Always call first**: ``` tool: get-usage-guide args: {} ``` Returns workflow guide with current best practices. **Minimal evaluation**: ``` tool: evaluate-lisp args: {"code": "(+ 1 2)"} → "=> 3" ``` ## Core Concepts ### Persistent Session State is global within a server process: - `defun`, `defvar`, `defclass`, `ql:quickload` → persist for all subsequent calls - `let`, `let*` bindings → scoped to one evaluation - `reset-session` clears everything ### Output Format `evaluate-lisp` returns a text string with labeled sections: ``` [stdout] Hello [stderr] WARNING: something [Backtrace] 0: ... => 42 ``` Only non-empty sections appear. Return value is always last. ### Error Behavior Errors do NOT crash the server. They return a formatted error string: ``` [ERROR] DIVISION-BY-ZERO arithmetic error DIVISION-BY-ZERO signalled Operation was (/ 1 0). [Backtrace] 0: (/ 1 0) ... ``` `isError: false` in the MCP response even on Lisp errors. Check for `[ERROR]` prefix to detect failures. ## Tool Categories Full reference: `.claude/skills/integration/references/tools-reference.md` | Category | Tools | |----------|-------| | Core evaluation | `evaluate-lisp`, `compile-form`, `time-execution` | | Syntax | `validate-syntax` | | Introspection | `describe-symbol`, `apropos-search`, `macroexpand-form`, `who-calls`, `who-references` | | CLOS | `class-info`, `find-methods` | | Error intelligence | `describe-last-error`, `get-backtrace` | | Session | `list-definitions`, `reset-session`, `configure-limits` | | ASDF | `describe-system`, `system-dependencies`, `list-local-systems`, `find-system-file`, `load-system`, `load-file` | | Quicklisp | `quickload`, `quicklisp-search` | | Profiling | `profile-code`, `profile-functions`, `memory-report`, `allocation-profile` | | Telos | `telos-list-features`, `telos-feature-intent`, `telos-get-intent`, `telos-intent-chain`, `telos-feature-members`, `telos-feature-decisions`, `telos-list-decisions` | | Workflow | `get-usage-guide` | ## Common Patterns ### PATTERN-001: Validate Before Evaluate Use `validate-syntax` before saving code to files: ``` tool: validate-syntax args: {"code": "(defun foo (x)\n (* x x))"} → "Syntax OK" ``` Does not evaluate — safe for untrusted/large code. ### PATTERN-002: Incremental Definition Define, test, refine without file I/O: ``` # Step 1 tool: evaluate-lisp args: {"code": "(defun square (x) (* x x))"} → "=> SQUARE" # Step 2 tool: evaluate-lisp args: {"code": "(square 7)"} → "=> 49" # Step 3: only write to file when working ``` ### PATTERN-003: Debug Last Error When evaluation returns `[ERROR]`: ``` tool: describe-last-error args: {} → detailed error with restarts tool: get-backtrace args: {"max-frames": 10} → stack trace ``` ### PATTERN-004: Load External System ``` # Check if available tool: quicklisp-search args: {"pattern": "alexandria"} # Load it tool: quickload args: {"system": "alexandria"} → "Successfully loaded: ALEXANDRIA" # Verify tool: evaluate-lisp args: {"code": "(alexandria:flatten '(1 (2 3) (4 (5))))"} → "=> (1 2 3 4 5)" ``` ### PATTERN-005: Profile Hot Code ``` tool: time-execution args: {"code": "(loop repeat 1000000 sum 1)"} → "Real time: 0.012s, GC time: 0.000s, Bytes: 0" # For deeper profiling tool: profile-code args: {"code": "(loop repeat 1000000 sum 1)", "mode": "cpu"} ``` ## Key Tool Signatures | Tool | Required args | Optional args | |------|--------------|---------------| | `evaluate-lisp` | `code: string` | `package: string`, `capture-time: bool` | | `compile-form` | `code: string` | — | | `validate-syntax` | `code: string` | — | | `describe-symbol` | `name: string` | `package: string` | | `apropos-search` | `pattern: string` | `package: string`, `type: string` | | `configure-limits` | — | `timeout: integer`, `max-output: integer` | | `quickload` | `system: string` | — | | `load-system` | `system: string` | — | | `load-file` | `path: string` | `compile: bool` | | `profile-code` | `code: string` | `mode: string` (cpu/wall/alloc) | | `get-backtrace` | — | `max-frames: integer` | | `telos-feature-intent` | `feature: string` | — | ## Pitfalls | Pitfall | Symptom | Fix | |---------|---------|-----| | Stale session | Undefined symbols from prior work | `reset-session` | | No timeout | Server hangs on infinite loop | `configure-limits {"timeout": 30}` | | Large output | Response truncated | `configure-limits {"max-output": 50000}` | | Missing package | `No package error` | `evaluate-lisp` with `"package": "cl-user"` | | `load-system` vs `quickload` | System not found | Use `quickload` for Quicklisp systems; `load-system` for ASDF-registered only | | Telos tools on unloaded system | Empty results | Load the system first; telos returns empty when not available | | Macro redefinition | Callers use old expansion | After macro change, reload dependent files | ## Detailed Reference - **All 36 tools with full schemas**: `.claude/skills/integration/references/tools-reference.md` - **Architecture**: `docs/explanation/architecture.md` - **Canon specifications**: `canon/features/` --- > Source: [quasi/cl-mcp-server](https://github.com/quasi/cl-mcp-server) — distributed by [TomeVault](https://tomevault.io).