Skip to content
lambda-symbolicsPublic

About

MCP client library for Common Lisp

Resources

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

 

History

57 Commits

Folders and files

Repository files navigation

Mcparen

Mcparen is a small Common Lisp client for the Model Context Protocol over standard I/O and Streamable HTTP. It defaults to the MCP 2025-11-25 and 2025-06-18 lifecycle. Use :protocol-mode :auto to probe for the MCP 2026-07-28 stateless lifecycle and subscriptions before falling back.

The library handles:

  • JSON-RPC lifecycle
  • concurrent requests
  • typed errors
  • timeouts and cancellation
  • cursor pagination
  • tool calls, resources, and prompts
  • HTTP sessions
  • bounded process cleanup

List pagination is bounded before pages are accumulated. One list operation may read at most 1,000 pages and retain at most 10,000 items, 16 MiB of conservative encoded item and cursor data, and 100,000 item and cursor tree nodes. Session restarts begin a fresh accumulation and are limited to eight attempts. These reloadable bounds are exported with the *mcp-pagination- prefix.

Use

(ql:quickload :mcparen)

Create a lazy Streamable HTTP client:

(defparameter *client*
  (mcparen:make-mcp-client
   (mcparen:make-mcp-streamable-http-transport
    "https://example.test/mcp"
    :headers-function
    (lambda ()
      (let ((token (uiop:getenv "EXAMPLE_MCP_TOKEN")))
        (and token
             (list (cons "Authorization"
                         (format nil "Bearer ~A" token)))))))
   :name "example-client"
   :version "1.0.0"))

(unwind-protect
     (progn
       (mcparen:mcp-client-connect *client*)
       (dolist (tool (mcparen:mcp-client-list-tools *client*))
         (format t "~A: ~A~%"
                 (mcparen:mcp-tool-name tool)
                 (mcparen:mcp-tool-description tool))))
  (mcparen:mcp-client-close *client*))

Create a standard I/O client:

(mcparen:make-mcp-client
 (mcparen:make-mcp-stdio-transport
  "/absolute/path/to/server"
  :arguments '("--stdio")
  :directory #P"/workspace/"))

Credential providers run at request or process-launch time. Callers can retain environment-variable names instead of secret values in long-lived objects.

Streamable HTTP transports also accept :exchange-scope-function. This function receives and synchronously invokes a zero-argument thunk around each complete HTTP exchange, from late header resolution through response parsing and dispatch. It can establish application-owned dynamic state for normal requests, SSE resumptions, idle listener cycles, and session deletion.

Both transport constructors accept :maximum-message-characters. The default is 16 MiB. Mcparen rejects larger standard I/O messages, HTTP JSON bodies, SSE lines, and aggregate SSE event data before retaining an unbounded document. Outbound documents are checked against the same transport-specific limit before encoding. Every document is also held to the structural bounds in *mcp-json-limits*, an argo json-limits value that defaults to argo:*json-strict-limits* (nesting depth, nodes, string and key lengths, members, elements, and number lengths). Exceeding the character limit signals mcp-message-too-large; malformed JSON, an exceeded structural bound, or an outbound value with no JSON form signals mcp-protocol-error.

JSON values

Mcparen decodes and encodes with argo and uses its value model for every public raw MCP value:

  • JSON objects are hash tables with equal string keys
  • JSON arrays are vectors
  • JSON strings and numbers are Common Lisp strings and numbers
  • JSON true is T
  • JSON false is the marker returned by argo:json-false, which argo:json-get reads as NIL
  • JSON null is NIL; use gethash or argo:json-get-present where a present null must differ from an absent member

Decoding is strict RFC 8259. json-object is argo’s constructor of an object from alternating string keys and values. When building values, yason’s boolean symbols and :null are also accepted. These representations are also used by tool schemas, raw tool metadata, tool arguments, structured results, resources, and prompts.

Lifecycle

By default, mcp-client-connect negotiates MCP 2025-11-25 or 2025-06-18 with initialize followed by notifications/initialized. Pass :protocol-mode :auto to make-mcp-client to probe for 2026-07-28 with server/discover. Modern requests carry client metadata on each request. Modern HTTP uses POST without session IDs or a standalone GET listener. On a legacy probe response, the client uses the 2025 handshake. A recognized modern error is reported instead of trying initialize; 2026-07-28 is the only modern revision supported. This mode covers the stateless lifecycle, ordinary complete results and subscriptions. It does not implement MRTR (input-required continuations) or modern extensions.

Public operations reconnect a deliberately closed client when it is used again. mcp-client-close terminates owned resources. mcp-client-detach closes inherited descriptors without signaling a parent-owned server.

On supported POSIX systems, a standard I/O server must enter a process group led by its direct child process. Shutdown closes stdin, then uses bounded TERM and KILL phases.

Notifications and subscriptions

For MCP 2025-11-25 and 2025-06-18, pass :notification-handler to either transport constructor. The function receives the server notification method and JSON params. Stdio delivers notifications from server stdout; Streamable HTTP receives them on SSE response streams and on a standalone GET stream when the server supports it. Call mcp-client-subscribe-resource or mcp-client-unsubscribe-resource with a URI when the server advertises resources.subscribe. The subscription belongs to the current session; subscribe again after a reconnect if you still want updates. Receiving server notifications does not require advertising a client capability.

For MCP 2026-07-28, call mcp-client-listen with a JSON object containing toolsListChanged, promptsListChanged, resourcesListChanged and/or a vector of URI strings at resourceSubscriptions. The call returns when the server acknowledges the request. Check mcp-subscription-acknowledged-filter for the accepted subset.

(let ((subscription
        (mcparen:mcp-client-listen
         client
         (mcparen:json-object "resourceSubscriptions" #("file:///project/config")))))
  (unwind-protect
       (multiple-value-bind (event status failure)
           (mcparen:mcp-subscription-next subscription :timeout 10)
         (list status event failure))
    (mcparen:mcp-subscription-cancel subscription)))

Use one consumer per subscription. mcp-subscription-next returns the full JSON-RPC notification with :notification, or an outcome: :timeout, :complete, :dropped, :cancelled, :server-cancelled or :failed. The third value contains a condition when available. A read timeout leaves the subscription open. Each handle buffers up to 128 notifications in arrival order. On overflow, the handle terminates; drain the queued events, then read :failed and its condition. A stalled consumer does not block unrelated stdio replies. Cancel to close only the HTTP response stream or send a stdio cancellation notification. On unexpected stdio process loss, Mcparen attempts one restart and re-sends active, acknowledged subscriptions on the same handles. Each restored exchange has a fresh mcp-subscription-id and must receive its own acknowledgment. Queued events keep their original IDs. Ordinary requests are not retried. An HTTP disconnect ends the subscription; call mcp-client-listen again after reconnecting.

Managed connections

Load mcparen/managed for shared restartable connections and discovery snapshots. Construct mcp-managed-server instances with :name, :required-p and either :client or :client-factory. A factory receives the server and a notification callback; pass that callback to the transport constructor.

(asdf:load-system :mcparen/managed)
(defparameter *servers*
  (make-instance 'mcparen:mcp-connection-manager
                 :maximum-schema-bytes (* 1024 1024)
                 :runtimes
                 (list (make-instance
                        'mcparen:mcp-managed-server :name "example"
                        :client-factory
                        (lambda (server notification-handler)
                          (declare (ignore server))
                          (mcparen:make-mcp-client
                           (mcparen:make-mcp-streamable-http-transport
                            "https://example.test/mcp"
                            :notification-handler notification-handler)))))))
(unwind-protect
     (progn
       (mcparen:mcp-manager-start *servers*)
       (mcparen:mcp-manager-snapshot *servers*))
  (mcparen:mcp-manager-close *servers*))

Use mcp-manager-build with zero-argument server factories for cleanup across factory and partial-startup failures. A server has one lifecycle owner; share that manager among application consumers. Required servers receive aggregate schema budget first, preserving presentation order. Optional failures are isolated, and failed discovery is cached until a refresh is requested.

Use mcp-manager-refresh for explicit rediscovery, or mcp-server-runtime-connect at use boundaries. Notifications and transparent reconnections invalidate discovery. Read detached mcp-discovery-snapshot values through mcp-server-runtime-snapshot or mcp-manager-snapshot; each contains state, capabilities, generation, revision, tools and a diagnostic. Use mcp-manager-collect to aggregate resources or prompts, supplying a client list function and optionally an item identity function. Results and failures are separate, server-qualified lists; duplicate identities within a server are rejected when an identity function is supplied. Use mcp-server-runtime-call for scoped client operations. Consume or project secret-bearing results inside its callback before returning to the caller.

Specialize the mcp-managed- protocol for credential scopes, diagnostic redaction, metadata projection and provider-specific schema validation. mcp-managed-credential-key returns a non-secret identity of the exact active credential snapshot and an optional resolution condition; enable persistent identity checks with mcp-managed-credential-check-p. Specialize mcp-managed-call-with-local-cleanup when local fallback needs application bindings without fresh credential resolution. Before callback entry, errors and nonlocal scope exits still trigger exactly one local teardown attempt. Use mcp-server-runtime-cancel to interrupt in-flight requests before closing. Close and detach leave connections restartable. Manager teardown is serialized against discovery.

The lock order is manager, server, then notification revision. Scope and projection methods run synchronously. Within those methods, inspect the given server rather than reentering manager operations.

Development

./script/bootstrap
./script/check
./script/check --fix

./script/check runs the tests, then checks the source with cheque as cheque.sexp configures it. --fix skips the tests and repairs what cheque can repair. cheque and its tools are development dependencies: checks/qlfile lists them, and the check installs them on first use into ~/.cache/cheque/tools/.

Part of the Lambda Symbolics library shelf.

Declarative transport configuration

Applications that store MCP server definitions can validate and detach a configuration without starting a process or reading the environment. Use mcp-read-transport-configuration with a plist whose :type is :stdio or :http.

(mcp-read-transport-configuration
 '(:type :stdio
   :command "/usr/local/bin/example-mcp"
   :arguments ("--stdio")
   :directory :workspace
   :environment (("API_TOKEN" :environment "EXAMPLE_API_TOKEN")))
 :default-directory "/srv/example")

(mcp-read-transport-configuration
 '(:type :http
   :url "https://example.test/mcp"
   :headers (("Authorization" :environment "EXAMPLE_TOKEN"))
   :connect-timeout-seconds 15))

The reader returns an mcp-stdio-transport-configuration or mcp-http-transport-configuration. Stdio values are available through mcp-stdio-configuration-command, mcp-stdio-configuration-arguments, mcp-stdio-configuration-directory, and mcp-stdio-configuration-environment-bindings. HTTP values are available through mcp-http-configuration-url, mcp-http-configuration-header-bindings, and mcp-http-configuration-connect-timeout-seconds. Bindings use mcp-environment-binding-target and mcp-environment-binding-source.

The reader accepts only bounded ASCII environment names and validates the URL scheme and authority. HTTPS accepts valid DNS and IP authorities. HTTP is limited to localhost and loopback IP authorities. Password-bearing authorities, reserved MCP headers, duplicate names, unknown plist keys, malformed lists, and values outside the transport bounds signal mcp-configuration-error.

When :directory is omitted, :default-directory defaults to :workspace. An explicit :workspace value is retained for the caller to resolve. Transport limits are exported reloadable parameters. The reader accepts a default HTTP connection timeout and a maximum timeout through keyword arguments.

Input schema normalization

mcp-validate-input-schema validates and detaches a JSON-compatible MCP input schema. It returns two values: the normalized hash table and its compact UTF-8 byte count. Missing type defaults to "object" and missing properties defaults to an empty object. An object-containing type union is accepted. Present properties and required values are checked for their required JSON shapes. JSON false, null, and annotation members are preserved.

(multiple-value-bind (schema bytes)
    (mcp-validate-input-schema
     (json-object "type" "object"
                  "properties"
                  (json-object "name" (json-object "type" "string"))))
  (format t "~D bytes~%" bytes)
  schema)

The original value and normalized value are checked against the supplied byte, depth, node, string, and key limits. Cycles, unrepresentable Lisp values, and limit violations signal mcp-input-schema-error, whose reason and value readers identify the failure.

About

MCP client library for Common Lisp

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages