cl-mcp-integration

name	cl-mcp-integration
description	Integration guide for using cl-mcp (server + client) in a project
version	0.2.0
author	quasi
type	integration

cl-mcp — Integration Skill

What Is cl-mcp

MCP server and client framework for Common Lisp.

• cl-mcp (server): Expose CL functions as MCP tools over stdio. Framework handles JSON-RPC framing, protocol negotiation, tool validation, error recovery.
• cl-mcp/client (client): Connect to any MCP server subprocess, list its tools, call them. Threading, request correlation, and error signaling handled by the framework.

Protocol: MCP 2025-06-18 (server) / 2025-11-25 (client).

---

SERVER

Quick Start

(ql:quickload :cl-mcp)

(defvar *server* (cl-mcp:make-server :name "my-server" :version "1.0.0"))

(cl-mcp:register-tool *server* "greet"
  :description "Returns a greeting"
  :schema '(("type" . "object")
            ("required" . ("name"))
            ("properties" . (("name" . (("type" . "string"))))))
  :handler (lambda (args)
             (format nil "Hello, ~a!"
                     (cdr (assoc "name" args :test #'string=)))))

(cl-mcp:run-server *server*)  ; blocks until EOF on stdin

Core Concepts (Server)

Server: mcp-server struct with an isolated tool registry. Multiple servers can run independently in the same image.

Tool registry: Per-server hash-table. register-tool mutates it. No global state.

Handler: (lambda (args) ...). args is an alist — string keys mapped to decoded JSON values (strings, numbers, lists, nested alists).

Result normalization: Return a string → auto-wrapped to (("type" . "text") ("text" . ...)). Return a list of content blocks → used as-is.

Error recovery: Server catches all handler errors and returns JSON-RPC internal-error (-32603). Server never terminates on error.

Server API

All symbols in package cl-mcp.

Function	Signature	Returns	Notes
make-server	(&key name version)	mcp-server	Defaults: "mcp-server", "0.1.0"
register-tool	(server name &key description schema handler)	tool-definition	handler required; call before run-server
run-server	(server &key input output)	—	Blocks until EOF. Defaults: *standard-input*, *standard-output*
mcp-server-name	(server)	string	Accessor
mcp-server-version	(server)	string	Accessor
mcp-server-tools	(server)	hash-table	Registry; use for testing

Schema Format

'(("type" . "object")
  ("required" . ("arg1" "arg2"))
  ("properties" . (("arg1" . (("type" . "string")))
                   ("arg2" . (("type" . "number"))))))

Omitting schema defaults to (("type" . "object")) — accepts anything, validates nothing.

Server Patterns

PATTERN-001: Minimal Server

(let ((server (cl-mcp:make-server :name "ping-server" :version "1.0.0")))
  (cl-mcp:register-tool server "ping"
    :description "Returns pong"
    :schema '(("type" . "object"))
    :handler (lambda (args) (declare (ignore args)) "pong"))
  (cl-mcp:run-server server))

PATTERN-002: Tool With Required Arguments

(cl-mcp:register-tool server "add"
  :description "Adds two numbers"
  :schema '(("type" . "object")
            ("required" . ("a" "b"))
            ("properties" . (("a" . (("type" . "number")))
                             ("b" . (("type" . "number"))))))
  :handler (lambda (args)
             (let ((a (cdr (assoc "a" args :test #'string=)))
                   (b (cdr (assoc "b" args :test #'string=))))
               (format nil "~a" (+ a b)))))

Missing "a" or "b" signals invalid-params (-32602) automatically.

PATTERN-003: Stateful Tool Via Closure

;; State lives in closure, not global variable
(let ((counter 0))
  (cl-mcp:register-tool server "count"
    :description "Increments and returns counter"
    :schema '(("type" . "object"))
    :handler (lambda (args)
               (declare (ignore args))
               (format nil "~a" (incf counter)))))

PATTERN-004: Multiple Content Blocks

(cl-mcp:register-tool server "report"
  :description "Returns structured report"
  :schema '(("type" . "object"))
  :handler (lambda (args)
             (declare (ignore args))
             '((("type" . "text") ("text" . "Summary: OK"))
               (("type" . "text") ("text" . "Details: none")))))

PATTERN-005: Custom I/O (Testing / Piped Transport)

(with-open-file (in "/tmp/input.ndjson" :direction :input)
  (with-open-file (out "/tmp/output.ndjson"
                       :direction :output
                       :if-exists :supersede)
    (cl-mcp:run-server server :input in :output out)))

Server Pitfalls

Pitfall	Cause	Fix
invalid-params on valid call	Schema "required" has the arg name	Check alist key spelling (case-sensitive)
method-not-found on known tool	register-tool called after run-server	Register all tools before starting loop
Handler error → client gets -32603	Server catches all errors silently	Return error info as string; inspect opsis events
run-server never returns	Blocks until EOF on input	Call from dedicated thread or at top level
State shared across clients	Global variable instead of closure	Move state into let wrapping register-tool
Wrong arg type from JSON	Numbers as CL numbers, strings as CL strings	Use numberp/stringp before coercing

---

CLIENT

Quick Start

(ql:quickload :cl-mcp/client)

(cl-mcp.client:with-mcp-client (client
    :name "my-agent"
    :command '("npx" "@modelcontextprotocol/server-filesystem" "/tmp"))
  ;; List available tools
  (let ((tools (cl-mcp.client:list-tools client)))
    (dolist (tool tools)
      (format t "~a: ~a~%" (getf tool :name) (getf tool :description))))
  ;; Call a tool
  (let ((result (cl-mcp.client:call-tool
                 client "read_file" '(("path" . "/tmp/hello.txt")))))
    (print (getf result :content))))

Core Concepts (Client)

mcp-client: struct holding process handle, I/O streams, reader thread, pending-request table, and session state.

connect: Spawns the server subprocess, starts the reader thread, performs the MCP initialization handshake. Mutates the client struct.

Reader thread: Reads server stdout in a loop. Parses each line as JSON-RPC. Fulfills the matching pending-request promise. Exits cleanly on EOF.

Pending-request promise: One-shot synchronization object. %send-request registers it before writing to stdin, then blocks. Reader thread fulfills it; caller unblocks and returns the response.

Pagination: list-tools handles nextCursor pagination automatically — returns all tools across pages.

Error taxonomy:

Condition	When signaled
mcp-connect-error	Subprocess fails to start or handshake fails
mcp-session-closed	EOF or timeout waiting for response
mcp-protocol-error	Server returns JSON-RPC error for a valid session op (session still alive)
mcp-tool-error	Tool call returns isError: true

mcp-tool-error establishes two restarts: use-value (return a specific value) and skip-tool (return nil content). use-value shadows the CL standard restart of the same name within the dynamic extent of call-tool — do not rely on the standard use-value restart inside call-tool call stacks.

Client API

All symbols in package cl-mcp.client.

Function / Macro	Signature	Returns	Notes
make-client	(&key name version command)	mcp-client	command is a list of strings
connect	(client)	client	Spawns subprocess + handshake. Signals mcp-connect-error on failure
disconnect	(client &key timeout)	t	Closes stdin, joins reader thread (kills if timeout), terminates process
list-tools	(client)	list of plists	Each plist: (:name NAME :description DESC :input-schema SCHEMA)
call-tool	(client name arguments)	plist	arguments is alist or hash-table. Returns (:content CONTENT :is-error BOOL)
with-mcp-client	((var &rest make-args) &body body)	—	Connects on entry, disconnects on exit (unwind-protect)

Client struct accessors (read-only after connect):

• client-name, client-version, client-command
• client-connected-p — boolean
• client-server-info — alist: server name and version from handshake
• client-server-capabilities — alist from initialize response

Client Patterns

PATTERN-006: Safe Session With with-mcp-client

;; Preferred — disconnect guaranteed even on error
(cl-mcp.client:with-mcp-client (client
    :name "orchestrator"
    :command '("python" "-m" "my_mcp_server"))
  (let ((tools (cl-mcp.client:list-tools client)))
    (format t "~a tools available~%" (length tools))))

PATTERN-007: Manual Connect/Disconnect

(let ((client (cl-mcp.client:make-client
               :name "orchestrator"
               :command '("node" "server.js"))))
  (handler-case
      (progn
        (cl-mcp.client:connect client)
        (cl-mcp.client:call-tool client "ping" nil))
    (cl-mcp.client.conditions:mcp-connect-error (c)
      (format t "Could not connect: ~a~%" c)))
  (cl-mcp.client:disconnect client))

PATTERN-008: Handling Tool Errors With Restarts

(handler-bind
    ((cl-mcp.client.conditions:mcp-tool-error
      (lambda (c)
        ;; Log and continue with nil
        (format t "Tool ~a failed: ~a~%"
                (cl-mcp.client.conditions:tool-error-name c)
                (cl-mcp.client.conditions:tool-error-content c))
        (invoke-restart 'skip-tool))))
  (cl-mcp.client:call-tool client "risky-tool" '(("x" . 1))))

PATTERN-009: Inspecting Server Capabilities

(cl-mcp.client:with-mcp-client (client :command '("my-server"))
  ;; Inspect handshake results
  (let ((info (cl-mcp.client:client-server-info client)))
    (format t "Connected to: ~a ~a~%"
            (cdr (assoc "name"    info :test #'string=))
            (cdr (assoc "version" info :test #'string=)))))

Client Pitfalls

Pitfall	Cause	Fix
mcp-connect-error on known-good server	Server not on PATH	Use absolute path in command
mcp-session-closed (timeout)	Server slow to start	Increase %send-request :timeout (default 30s)
mcp-tool-error not handled → unwind	Tool returns isError: true	Use handler-bind with skip-tool or use-value restart
disconnect hangs	Reader thread stuck	Pass :timeout to disconnect (default 5s); thread is force-killed after
call-tool with nil arguments	Empty hash-table sent	Pass nil — framework converts to empty object
list-tools returns partial list	Assumed single page	list-tools paginates automatically; always correct

---

MCP Methods Supported

Server

Method	Response
initialize	protocolVersion, serverInfo, capabilities
tools/list	All registered tool definitions
tools/call	Validates args, calls handler, returns content blocks
Notifications	Silently ignored (no response sent)
Any other method	method-not-found (-32601)

Client

Method sent	Purpose
initialize	Handshake — establishes session
notifications/initialized	Handshake completion notification
tools/list	Discover available tools (with pagination)
tools/call	Execute a tool

Error Conditions

Server Conditions (package cl-mcp)

Condition	Code	Trigger
parse-error	-32700	Malformed JSON
invalid-request	-32600	Missing jsonrpc/method field
method-not-found	-32601	Unknown method or tool name
invalid-params	-32602	Missing required tool argument
internal-error	-32603	Handler signaled a condition

Accessors: error-code, error-message, error-data.

Client Conditions (package cl-mcp.client.conditions)

Condition	Accessor(s)	When
mcp-connect-error	connect-error-command	Subprocess launch or handshake failure
mcp-session-closed	—	EOF, timeout, or reader thread crash
mcp-protocol-error	—	JSON-RPC error on valid session op
mcp-tool-error	tool-error-name, tool-error-content	isError: true in tool result

All inherit from mcp-error (from cl-mcp.conditions). Accessor error-message available on all.

---

GHOST.MCP — Higher-Level Bridge

If you are using cl-mcp inside a Ghost agent, prefer the ghost/mcp bridge over calling cl-mcp.client directly. It converts MCP tools into native Ghost tool-definition objects automatically.

(ql:quickload :ghost/mcp)

;; Convenience macro — wraps session, builds environment, disconnects on exit
(ghost.mcp:with-mcp-environment (env
    :command '("npx" "@modelcontextprotocol/server-filesystem" "/tmp"))
  (ghost:make-agent :provider provider :model model :environment env))

Lower-level: if you already hold a connected client, call mcp-tools-from directly:

(cl-mcp.client:with-mcp-client (client :command '("my-server"))
  (let ((tools (ghost.mcp:mcp-tools-from client :safety-level :safe)))
    ;; tools is a list of cl-llm-provider:tool-definition
    (ghost.environment:make-environment :tools tools)))

Error mapping:

cl-mcp condition	ghost.mcp behavior
mcp-tool-error (isError: true)	Handler returns LLM-visible string; session stays alive
mcp-session-closed	Propagated — Ghost agent loop signals agent-tool-error
mcp-protocol-error	Propagated — Ghost agent loop signals agent-tool-error

Package: ghost.mcp. ASDF system: ghost/mcp (separate from :ghost).

---

References

• Dev Skill — for contributors working on cl-mcp
• README.md — project navigation