Lisply

Lisply-MCP is a middleware bridge that lets an MCP-enabled AI agent talk to Lisp-based backends. It translates evaluation requests, HTTP calls, and file operations between the agent and your Lisp environment, enabling neuro-symbolic programming workflows and automated Lisp-driven tasks.

How to use

You use Lisply-MCP by configuring your MCP client to connect through the wrapper and then starting one or more Lisply backends. Each connected server exposes a set of tools that let your AI agent evaluate Lisp, query HTTP endpoints exposed by the backend, or ping the service to verify availability. Tools are automatically prefixed with the server name to avoid conflicts when running multiple backends.

How to install

Prerequisites you need before starting:

• Node.js (18+ recommended)
• Docker (20+ recommended)
• A Lisp backend image or source you want to connect to via Lisply-MCP

Complete steps to get up and running from a fresh setup:

1. Install Node.js and Docker on your host.

2. Clone the Lisply-MCP source to a location accessible by your MCP-capable AI agent.

3. Prepare a client configuration that points to the Lisply-MCP wrapper and its backend(s). You will define mcpServers in your agent’s configuration to start MCP connections.

Additional configuration and notes

Environment and runtime options let you customize how Lisply-MCP starts and talks to backends. The wrapper can auto-pull and run a Lisply backend container, or you can point it at existing services. Key options include ports for HTTP, HTTPS, and internal Lisp evaluation, as well as the Lisp implementation and mount points for sharing files.

Security best practices emphasize isolating backends in containers, avoiding host-wide mounts to sensitive directories, and limiting container RAM/CPU to reduce risk from untrusted Lisp code.

If you plan to run multiple Lisply servers, each server’s tools will be scoped to its own namespace to prevent conflicts.

Troubleshooting and tips

If the MCP client cannot connect to the Lisply backend, verify that the Lisply service is running and that network ports are accessible. Check the wrapper log file for errors, and try a direct ping to the Lisply HTTP server to confirm responsiveness.

Common issues include Docker not running, port conflicts, or permission problems with Docker socket. Resolve these by ensuring Docker is up, freeing the needed ports, and granting your user permission to access Docker.

If you are running in a container, make sure the Docker socket is mounted correctly so the wrapper can manage the backend container.

Notes on backends and endpoints

Lisply-MCP supports HTTP mode for structured responses and stdio mode for raw REPL-like interactions. HTTP mode is suitable for most use cases, while stdio mode is geared toward development and debugging for local containers.

Tools exposed include Lisp evaluation, HTTP requests to backend endpoints, and a ping utility to verify service availability. The available tools are automatically named by server to avoid conflicts when running multiple Lisply servers.

Examples of typical workflows

{
  "mcpServers": {
    "lisply-gendl": {
      "type": "stdio",
      "command": "node",
      "args": [
        "/path/to/cloned/lisply-mcp/scripts/mcp-wrapper.js",
        "--server-name", "gendl",
        "--http-port", "9080"
      ]
    }
  },
  "globalShortcut": ""
}

MCP server registrations

The following inline examples show stdio-style MCP server entries you can adapt for your setup. Each entry runs the MCP wrapper with a distinct server name and HTTP port.

Available tools

lisp_eval

Evaluates Lisp code in the Lisply backend and returns the result, enabling AI agents to run symbolic computations and tests.

http_request

Sends HTTP requests to endpoints exposed by the Lisply backend and returns the response, enabling data retrieval and integration.

ping_lisp

Pings the Lisply server to verify it is running and reachable.