Thanks to the creators of 40ants-mcp, the library provides a nice pattern and code structure that I really like. However, I struggled significantly with installation and getting started. What should have taken minutes ended up taking days.

I'm sharing my experience here so that others who want to build MCP servers in Common Lisp can get started in minutes, not days like I did.

Prerequisites

Before you begin, make sure you have the following installed:

• SBCL – A high-performance Common Lisp compiler
• Roswell – A Common Lisp implementation manager and script runner
• Quicklisp – The de facto package manager for Common Lisp
• Ultralisp – A community-driven distribution of Common Lisp libraries

Installing Ultralisp

In SBCL with Quicklisp, you can enable Ultralisp by:

(ql-dist:install-dist "http://dist.ultralisp.org/" :prompt nil)

(How to install SBCL and Quicklisp is in the appendix.)

The Gotcha: Loading 40ants-mcp

Here's the issue that cost me days: when you try to load 40ants-mcp with:

(ql:quickload :40ants-mcp)

You might encounter errors. The solution is simple but not obvious—load jsonrpc first:

(ql:quickload :jsonrpc)
(ql:quickload :40ants-mcp)

This dependency isn't automatically resolved, which was the source of my frustration.

Creating Your MCP Server

Here's a minimal example from my mcp-exper package:

(in-package :mcp-exper)

(openrpc-server:define-api (mi-tools :title "mi-tools"))

(40ants-mcp/tools:define-tool (mi-tools add) (a b)
  (:summary "just add")
  (:param a integer "a")
  (:param b integer "b")
  (:result text-content)
  (make-instance 'text-content :text (format nil "~a" (+ a b))))

(defun start-server ()
  (40ants-mcp/server/definition:start-server mi-tools))

Key points:

1. Use openrpc-server:define-api to define your API
2. Use 40ants-mcp/tools:define-tool to define tools
3. Return text-content instances for text results (MCP requires specific content types)

Running the Server

Create a Roswell script (mi-mcp-server.ros):

#!/bin/sh
#|-*- mode:lisp -*-|#
exec ros -Q -- $0 "$@"
|#
(progn
  (ros:ensure-asdf)
  #+quicklisp(ql:quickload '(:mcp-exper) :silent t))

(defun main (&rest argv)
  (declare (ignorable argv))
  (mcp-exper:start-server))

Quick Test

Run directly with Roswell:

ros mi-mcp-server.ros

Production Installation

Build and install as an executable:

ros build mi-mcp-server.ros
install -m 0755 mi-mcp-server $HOME/.local/bin/

Make sure $HOME/.local/bin is in your PATH.

Integrating with Opencode

To enable your MCP server in opencode, add this to ~/.config/opencode/opencode.json:

{
    "mcp": {
        "mi-tools": {
            "type": "local",
            "command": ["mi-mcp-server"],
            "enabled": true
        }
    }
}

Conclusion

Building MCP servers with Common Lisp is straightforward once you know the tricks. The 40ants-mcp library is well-designed, and the OpenRPC integration works smoothly.

I hope this guide saves you the days of frustration I experienced. Happy hacking!

The full source code for this example is available at mcp-exper.

Appendix: Installing SBCL

macOS

brew install sbcl

Debian/Ubuntu

apt install sbcl

Arch Linux

pacman -S sbcl

Appendix: Installing Quicklisp

Download and install Quicklisp:

wget https://beta.quicklisp.org/quicklisp.lisp
sbcl --load quicklisp.lisp \
        --eval '(quicklisp-quickstart:install)' \
        --eval '(ql-util:without-prompting (ql:add-to-init-file))' \
        --quit

Thanks to the creators of 40ants-mcp, the library provides a nice pattern and code structure that I really like. However, I struggled significantly with installation and getting started. What should have taken minutes ended up taking days.

I'm sharing my experience here so that others who want to build MCP servers in Common Lisp can get started in minutes, not days like I did.

Prerequisites

Before you begin, make sure you have the following installed:

• SBCL – A high-performance Common Lisp compiler
• Roswell – A Common Lisp implementation manager and script runner
• Quicklisp – The de facto package manager for Common Lisp
• Ultralisp – A community-driven distribution of Common Lisp libraries

Installing Ultralisp

In SBCL with Quicklisp, you can enable Ultralisp by:

(ql-dist:install-dist "http://dist.ultralisp.org/" :prompt nil)

(How to install SBCL and Quicklisp is in the appendix.)

The Gotcha: Loading 40ants-mcp

Here's the issue that cost me days: when you try to load 40ants-mcp with:

(ql:quickload :40ants-mcp)

You might encounter errors. The solution is simple but not obvious—load jsonrpc first:

(ql:quickload :jsonrpc)
(ql:quickload :40ants-mcp)

This dependency isn't automatically resolved, which was the source of my frustration.

Creating Your MCP Server

Here's a minimal example from my mcp-exper package:

(in-package :mcp-exper)

(openrpc-server:define-api (mi-tools :title "mi-tools"))

(40ants-mcp/tools:define-tool (mi-tools add) (a b)
  (:summary "just add")
  (:param a integer "a")
  (:param b integer "b")
  (:result text-content)
  (make-instance 'text-content :text (format nil "~a" (+ a b))))

(defun start-server ()
  (40ants-mcp/server/definition:start-server mi-tools))

Key points:

1. Use openrpc-server:define-api to define your API
2. Use 40ants-mcp/tools:define-tool to define tools
3. Return text-content instances for text results (MCP requires specific content types)

Running the Server

Create a Roswell script (mi-mcp-server.ros):

#!/bin/sh
#|-*- mode:lisp -*-|#
exec ros -Q -- $0 "$@"
|#
(progn
  (ros:ensure-asdf)
  #+quicklisp(ql:quickload '(:mcp-exper) :silent t))

(defun main (&rest argv)
  (declare (ignorable argv))
  (mcp-exper:start-server))

Quick Test

Run directly with Roswell:

ros mi-mcp-server.ros

Production Installation

Build and install as an executable:

ros build mi-mcp-server.ros
install -m 0755 mi-mcp-server $HOME/.local/bin/

Make sure $HOME/.local/bin is in your PATH.

Integrating with Opencode

To enable your MCP server in opencode, add this to ~/.config/opencode/opencode.json:

{
    "mcp": {
        "mi-tools": {
            "type": "local",
            "command": ["mi-mcp-server"],
            "enabled": true
        }
    }
}

Conclusion

Building MCP servers with Common Lisp is straightforward once you know the tricks. The 40ants-mcp library is well-designed, and the OpenRPC integration works smoothly.

I hope this guide saves you the days of frustration I experienced. Happy hacking!

The full source code for this example is available at mcp-exper.

Appendix: Installing SBCL

macOS

brew install sbcl

Debian/Ubuntu

apt install sbcl

Arch Linux

pacman -S sbcl

Appendix: Installing Quicklisp

Download and install Quicklisp:

wget https://beta.quicklisp.org/quicklisp.lisp
sbcl --load quicklisp.lisp \
        --eval '(quicklisp-quickstart:install)' \
        --eval '(ql-util:without-prompting (ql:add-to-init-file))' \
        --quit

Bash Example

I wrote a Bash script consisting of four files:

a.bash

a.bash orchestrates everything. “Orchestration” might be too grand a word for these toy scripts, but I want to convey that it performs a role similar to Apache Airflow.

#!/bin/bash

. ./b.bash
. ./c.bash
. ./d.bash

init
print_count
inc
print_count

b.bash

b.bash contains only one function, inc, which increments the counter, which is the global variable in this example.

inc() {
    counter=$((counter + 1))
}

c.bash

c.bash contains print_count, which simply displays the value of the global variable counter.

print_count() {
    echo $counter
}

d.bash

In Bash, counter can be initialized globally from within a function by default.

init() {
    counter=1
}

Python Example

The following section shows the result of porting the Bash script above to Python, highlighting the key differences.

a.py

This is the orchestration part. Note the use of namespaces or module names.

import c, b, d

d.init()
c.print_count()
b.inc()
c.print_count()

b.py

In the Python version, inc must refer to the module d to access the variable. Alternatively, counter could be explicitly imported.

import d

def inc():
    d.counter += 1

c.py

Similarly, print_count in Python must also refer to module d.

import d

def print_count():
    print(d.counter)

d.py

Unlike in Bash, initializing a global variable from within a function—even in the same module—requires an explicit global declaration.

def init():
    global counter
    counter = 1

Key Differences

As you can see, a global variable in Bash is truly global across files. In Python, however, a global variable is only global within its module, i.e., file. Furthermore, mutating a global variable in Bash requires no special syntax, whereas in Python a function must explicitly declare global to modify a module-level variable.

Consequently, although both are called “global variables,” Python's are scoped to the module. This means they won’t interfere with variables in other modules unless we deliberately make them do so. For developers who use one class per module, a Python global variable behaves much like a class variable. Additionally, variable assignment inside a Python function is local by default, preventing accidental modification of global state unless explicitly intended.

In short, many traditional precautions about global variables in languages like Bash or MBASIC no longer apply in Python. Therefore, we might reconsider automatically rejecting global variables based on past advice and instead evaluate their use case thoughtfully.

It retains explicit calls to configure and make, preserving the transparency of a manual installation. This demonstrates that while increased abstraction can make code shorter, it can also hinder understanding.

Another potential advantage of greater abstraction is the ability to change the configure command for every package by modifying just one location. However, since GNU Autotools has continued to use the configure command for decades, it may not be worth sacrificing clarity for this particular benefit.

Expanding Emacs functionality is as simple as defining a new function instead of creating an entire extension package, as is often done in many other extensible editors. This function can then be re-evaluated, tested, and modified entirely within Emacs using just a few clicks or keyboard shortcuts, with no need to restart or reload Emacs.

An actively-maintained-implementation, long-term-stable-specification programming language

There are many programming languages that don't change much, including Common Lisp, but Common Lisp implementations continue to be developed. For example, SBCL (Steel Bank Common Lisp) released its latest version just last month.

Common Lisp can be extended through libraries. For example, cl-interpol enables Perl-style strings to Common Lisp without requiring a new version of Common Lisp. cl-arrows allows Common Lisp to create pipelines using Clojure-style syntax without needing to update the Common Lisp specification. This exceptional extensibility stems from macro and particularly reader macro support in Common Lisp.

Feature-packed

Common Lisp includes many features found in modern programming languages, such as:

• Garbage collection
• Built-in data structures (e.g., vectors, hash tables)
• Type hints
• Class definitions
• A syntactic structure similar to list comprehensions

Multi-paradigm

While Lisp is commonly associated with functional programming, Common Lisp doesn't enforce this paradigm. It fully supports imperative programming (like Pascal), and its object-oriented programming system even includes advanced features. Best of all, you can freely mix all these styles. Common Lisp even embraces goto-like code via TAGBODY-GO.

Performance

Common Lisp has many implementations, and some of them, such as SBCL, are compilers that can generate efficient code.

With some (of course, not all) implementations, many programs written in dynamic programming languages run slower than those in static ones, such as C and Modula-2.

First, an example of the generated assembly will be shown, along with more explanation about why it might be slowed down by some dynamic implementations

The code listing below is a part of a program written in Modula-2, which must be easy to read by programmers of languages in the extended ALGOL family.

    TYPE
      Book = RECORD
        title: ARRAY[1..64] OF CHAR;
        price: REAL;
      END;

    PROCEDURE SumPrice(a, b: Book): REAL;
    BEGIN
      RETURN a.price + b.price;
    END SumPrice;

The code is mainly for summing the price of books, and only the part 'a.price + b.price' will be focused on.

'a.price + b.price' is translated into X86-64 assembly code list below using the GNU Modula-2 compiler.

    movsd   80(%rbp), %xmm1
    movsd   152(%rbp), %xmm0
    addsd   %xmm1, %xmm0

“movsd 80(%rbp), %xmm1' and 'movsd 152(%rbp), %xmm0' are for loading 'prices' to registers '%xmm1' and '%xmm0', respectively. Finally, 'addsd %xmm1, %xmm0' is for adding prices together. As can be seen, the prices are loaded from exact locations relative to the value of the '%rbp' register, which is one of the most efficient ways to load data from memory. The instruction 'addsd' is used because prices in this program are REAL (floating point numbers), and '%xmm0', '%xmm1', and 'movsd' are used for the same reason. This generated code should be reasonably efficient. However, the compiler needs to know the type and location of the prices beforehand to choose the proper instructions and registers to use.

In dynamic languages, 'SumPrice' can be applied to a price whose type is an INTEGER instead of a REAL, or it can even be a string/text. A straightforward implementation would check the type of 'a' and 'b' at runtime, which makes the program much less efficient. The checking and especially branching can cost more time than adding the numbers themselves. Moreover, obtaining the value of the price attribute from 'a' and 'b' might be done by accessing a hash table instead of directly loading the value from memory. Of course, while a hash-table has many advantages, it's less efficient because it requires many steps, including comparing the attribute name and generating a hash value.

However, compilers for dynamic languages can be much more advanced than what's mentioned above, and SBCL is one such advanced compiler. SBCL can infer types from the code, especially from literals. Moreover, with information from type hints and 'struct' usage, SBCL can generate code that's comparably as efficient as static language compilers.

Given, the Common Lisp code listing below:

    (defstruct book
      title
      (price 0 :type double-float))

    (declaim (ftype (function (book book) double-float) add-price)
         (optimize (speed 3) (debug 0) (safety 0)))
    (defun add-price (a b)
      (+ (book-price a)
         (book-price b)))

SBCL can generate assembly code for '(+ (book-price a) (book-price b))' as shown below:

    ; 86:       F20F104A0D       MOVSD XMM1, [RDX+13]
    ; 8B:       F20F10570D       MOVSD XMM2, [RDI+13]
    ; 90:       F20F58D1         ADDSD XMM2, XMM1

The assembly code format is slightly different from the one generated by the GNU Modula-2 compiler, but the main parts, the 'MOVSD' and 'ADDSD' instructions and the use of XMM registers—are exactly the same. This shows that we can write efficient code in Common Lisp at least for this case. This shows that we can write efficient code in Common Lisp, at least in this case, that is as efficient as, or nearly as efficient as, a static language.

This implies that Common Lisp is good both for high-level rapid development and optimized code, which has two advantages: (1) in many cases, there is no need to switch between two languages, i.e., a high-level one and a fast one; (2) the code can be started from high-level and optimized in the same code after a profiler finds critical parts. This paradigm can prevent premature optimization.

Interactive programming

Interactive programming may not sound familiar. However, it is a common technique that has been used for decades. For example, a database engine such as PostgreSQL doesn't need to be stopped and restarted just to run a new SQL statement. Similarly, it is akin to a spreadsheet like Lotus 1-2-3 or Microsoft Excel, which can run a new formula without needing to reload existing sheets or restart the program.

Common Lisp is exceptionally well-suited for interactive programming because of (1) integrated editors with a REPL (Read Eval Print Loop), (2) the language's syntax, and (3) the active community that has developed libraries specifically designed to support interactive programming.

Integrated editors with a REPL

With an integrated with a REPL, any part of the code can be evaluated immediately without copying and pasting from an editor into a REPL. This workflow provides feedback even faster than hot reloading because the code can be evaluated and its results seen instantaneously, even before it is saved. There are many supported editors, such as Visual Studio Code, Emacs, Neovim, and others.

the language's syntax

Instead of marking region arbitrarily for evaluating, which is not very convenient when it is done every few seconds, in Common Lisp, we can mark a form (which is similar to a block in ALGOL) by moving a cursor to one of the parentheses in the code, which is very easy with structural editing, which will be discussed in the next section.

Moreover, even a method definition can be evaluated immediately without resetting the state of the object in Common Lisp. Since method definitions are not nested in defclass, this allows mixing interactive programming and object-oriented programming (OOP) smoothly.

Here's the corrected code listing:

    (defclass toto ()
      ((i :initarg :i :accesor i)))

    (defmethod update-i ((obj toto))
      (setf (i obj) (+ i obj) 1))

According to the code listing above, the method 'update-i' can be redefined without interfering with the pre-existing value of 'i'.

Structural editing

Instead of editing Lisp code like normal text, tree-based operations can be used instead, such as paredit-join-sexps and paredit-forward-slurp-sexp. Moving cursor operations, such as paredit-forward, which moves the cursor to the end of the form (a block). These structural moving operations are also useful for selecting regions to be evaluated in a REPL.

Conclusion

In brief, Common Lisp has unparalleled combined advantages, which are relevant to software development especially now, not just an archaic technology that just came earlier. For example, Forth has a long-term-stable specification, and works well with interactive programming, but it is not designed for defining classes and adding type hints. Julia has similar performance optimization and OOP is even richer, but it doesn't have a long-term-stable specification. Moreover, Common Lisp's community is still active, as libraries, apps, and even implementations continue to receive updates.

No one actually cares about my programming environment journey, but I’ve often been asked to share it, perhaps for the sake of social media algorithms. I post it here, so later, I can copy and paste this conveniently.

My first computer, in the sense that I, not someone else, made the decision to buy it, ran Debian in 2002. It was a used Compaq desktop with a Pentium II processor, which I bought from Zeer Rangsit, a used computer market that may be the most famous in Thailand these days. When I got it home, I installed Debian right away. Before I bought my computer, I had used MBasic, mainly MS-DOS, Windows 3.1 (though rarely), and Solaris (remotely). For experimentation, I used Xenix, AIX, and one on DEC PDP-11 that I forgot.

Since I started with MBasic, that was my first programming environment. I learned Logo at a summer camp, so that became my second. Later, my father bought me a copy of Turbo Basic, and at school, I switched to Turbo Pascal.

After moving to GNU/Linux, I used more editors instead IDEs. From 1995 to 2010, my editors were pico, nvi, vim, TextMate, and Emacs paired with GCC (mostly C, not C++), PHP, Perl, Ruby, Python, JavaScript, and SQL. I also used VisualAge to learn Java in the 90s. I tried Haskell, OCaml, Objective C, Lua, Julia, and Scala too, but it was strictly for learning only.

After 2010, I used IntelliJ IDEA and Eclipse for Java and Kotlin. For Rust (instead of C), I used Emacs and Visual Studio Code. I explored Racket for learning purposes, then later started coding seriously in Clojure and Common Lisp. I tried using Vim 9.x and Neovim too, they were great, but not quite my cup of tea.

In 2025, a few days ago, I learned Smalltalk with Pharo to deepen my understanding of OOP and exploratory programming.

Update 2025/07/20: I forgot to mention xBase. In the '90s, I used it in a programming competition, but none of my programs in xBase reach production.

I've been told to avoid linked lists because their elements are scattered everywhere, which can be true in some cases. However, I wonder what happens in loops, which I use frequently. I tried to inspect memory addresses of list elements of these two programs run on SBCL.

CL-USER> (setq *a-list* (let ((a nil)) (push 10 a) (push 20 a) (push 30 a) a))
(30 20 10)
CL-USER> (sb-kernel:get-lisp-obj-address *a-list*)
69517814583 (37 bits, #x102F95AB37)
CL-USER> (sb-kernel:get-lisp-obj-address (cdr *a-list*))
69517814567 (37 bits, #x102F95AB27)
CL-USER> (sb-kernel:get-lisp-obj-address (cddr *a-list*))
69517814551 (37 bits, #x102F95AB17)
CL-USER> (sb-kernel:get-lisp-obj-address (cddr *a-list*))
69517814551 (37 bits, #x102F95AB17)

CL-USER> (setq *a-list* (let ((a nil))
			  (push 10 a)
			  (push 20 a)
			  (push 30 a) 
			  a))
(30 20 10)
CL-USER> (sb-kernel:get-lisp-obj-address *a-list*)
69518319943 (37 bits, #x102F9D6147)
CL-USER> (sb-kernel:get-lisp-obj-address (cdr *a-list*))
69518319927 (37 bits, #x102F9D6137)
CL-USER> (sb-kernel:get-lisp-obj-address (cddr *a-list*))
69518319911 (37 bits, #x102F9D6127)

In both programs, the list elements are not scattered. So, if scattered list elements were an issue for these simple cases, you probably used the wrong compiler or memory allocator.

There are many ways to manipulate JSON. I reviewed a few rapid ways today, which are using a command line tool called jq and libraries that support JSONPath query language.

jq

Awk is a powerful domain-specific language for text processing, but it lacks built-in support for manipulating hierarchical data structures like trees. jq fills this gap by providing a tool for transforming JSON data. However, one potential drawback is that jq requires a separate installation, which may add complexity to my workflow.

So I write a shell script using jq to extract user's names and user's urls from a cURL response, and then output it in TSV format.

curl -s 'https://mstdn.in.th/api/v1/timelines/public?limit=10' | jq '.[].account | [.username, .url] | @tsv' -r

The result looks like this:

kuketzblog      https://social.tchncs.de/@kuketzblog
cats    https://social.goose.rodeo/@cats
AlJazeera       https://flipboard.com/@AlJazeera
TheHindu        https://flipboard.com/@TheHindu
GossiTheDog     https://cyberplace.social/@GossiTheDog
kuketzblog      https://social.tchncs.de/@kuketzblog
weeklyOSM       https://en.osm.town/@weeklyOSM
juanbellas      https://masto.es/@juanbellas
noborusudou     https://misskey.io/@noborusudou
jerryd  https://mastodon.social/@jerryd

With a TSV file, we can use Awk, sed, etc. to manipulate them as usual.

JSONPath

JSONPath, which was explained in RFC 9535, is supported by many libraries and applications, e.g. PostgreSQL. Still, I try to it in Python by the jsonpath_nq library.

from jsonpath_ng import parse
import requests


res = requests.get("https://mstdn.in.th/api/v1/timelines/public?limit=10")

compiled_path = parse("$[*].account")


for matched_node in compiled_path.find(res.json()):
    print(matched_node.value["username"] + "\t" + matched_node.value["url"])

It gave the same result to the shell script above. The code is a bit longer than the shell script. However, it can be integrated with many Python libraries.

While Python scripts are generally portable, they may not always run seamlessly on popular Docker base images like Debian and Alpine. In contrast, Awk scripts are often readily available and executable within these environments.

Although Python syntax is relatively stable, its lifespan is shorter compared to Awk. For example, the print 10 syntax from the early 2000s is no longer valid in modern Python. However, Awk scripts from the 1980s can still be executed in current environments.

Python is known for its conciseness, especially when compared to languages like Java. However, when it comes to text processing and working within shell pipelines, Awk often provides more concise solutions. For instance, extracting text blocks between “REPORT” and “END” can be achieved with a single line in Awk: /REPORT/,/END/ { print }. Achieving the same result in Python typically involves more lines of code, including handling file input and pattern matching.

While Python can be embedded within shell scripts like Bash, aligning the indentation of multiline Python code with the surrounding shell script can often break the Python syntax. Awk, on the other hand, is less sensitive to indentation, making it easier to integrate into shell scripts.

Although different Awk implementations (such as Busybox Awk and GNU Awk) may have minor variations, Awk generally offers advantages over Python in the situations mentioned above.