mcp.org

Autolith MCP

MCP

Autolith is an MCP client. It supports MCP 2025-11-25 and 2025-06-18 through stdio and Streamable HTTP, using mcparen. It requests the newer revision and accepts either one the server selects.

As with other agents servers can offer tools, resources, resource templates, prompts, and server instructions.

Autolit’s MCP configuration is an S-expression, see below.

Start with one server

Create ${XDG_CONFIG_HOME:-~/.config}/autolith/mcp.sexp:

(:version 1
 :servers
 ((:name "local-tools"
   :transport
   (:type        :stdio
    :command     "/absolute/path/to/server"
    :arguments   ("--stdio")
    :directory   :workspace
    :environment
    (("SERVICE_TOKEN" :environment "AUTOLITH_SERVICE_TOKEN")))
   :required-p              nil
   :startup-timeout-seconds 15
   :tool-timeout-seconds    60
   :approval                :prompt
   :child-tools             ("lookup"))))

There is a couple important notes:

• Server names are case-sensitive
• A stdio :directory is :workspace or an existing pathname
• :workspace is resolved when the process starts, so a reconnect follows the current working directory

Here is how a remote server with read-only approval would look:

(:name      "remote-tools"
 :transport
 (:type                    :http
  :url                     "https://mcp.example.net/"
  :headers
  (("Authorization" :environment "AUTOLITH_MCP_AUTHORIZATION"))
  :connect-timeout-seconds 10)
 :approval                 :read-only
 :trusted-read-only-tools  ("lookup"))

Streamable HTTP requires HTTPS, except plain HTTP to a loopback host.

Security practices

Map an environment variable into a server environment or HTTP header:

("TARGET-NAME" :environment "SOURCE_VARIABLE")

For an Authorization header, the source value is the full value the server expects, such as Bearer ....

Do not put secrets into files you may share with others and/or the CCP.

• Autolith reads every referenced source variable once at the start of each credential-bearing MCP operation
• A changed credential closes the old process before reconnecting
• Stdio servers get a small baseline environment plus AUTOLITH_MCP=1. They do not inherit Autolith’s full environment. Add every other value with :environment

Trust project configuration

By default, a repository cannot turn on its own MCP server. To opt in, create ${XDG_CONFIG_HOME:-~/.config}/autolith/directory-scopes.sexp:

(:version     1
 :directories ("~/project/"))

When the workspace is that directory or a descendant, Autolith reads <trusted-directory>/.autolith/mcp.sexp.

• Only exact manifest anchors count
• A nested repository needs its own exact manifest entry
• Matching anchors apply from outermost to nearest
• A nearer file replaces an outer file’s same-name server
• Directory files override the global mcp.sexp
• Trusted-directory and user init.lisp registrations, plus live registrations, have higher precedence

A trusted anchor may also supply .autolith/init.lisp. When a site configuration root is set, Autolith first loads its init.lisp. It then loads trusted directory files from outermost to nearest and finally ${XDG_CONFIG_HOME:-~/.config}/autolith/init.lisp.

They are full-power Common Lisp in the AUTOLITH package. They can register servers. Arbitrary side effects remain until you reverse them or restart. Workspace changes replace extension registrations, not arbitrary Lisp effects.

Approval

:prompt is the default. Choose one policy per server:

• :prompt applies the session’s normal permission mode to each call
• :read-only permits an exact :trusted-read-only-tools name whose MCP annotations say read-only and non-destructive; other calls use normal permissions
• :allow permits every server tool without a prompt
• :deny denies every server tool, including in full-access sessions

For calls requiring authorization, full grants session access and auto classifies the external operation against the user’s request. In ask mode, choose once, always, auto, full, or deny. The picker shows the configured server, raw tool name, and complete arguments as aligned fields.

always records the exact server, raw tool, arguments, and workspace in the standard permission store. The argument payload is hashed rather than saved. (permissions :clear) removes these grants along with shell-command grants.

Local command sandboxing cannot confine an external server. In sandbox mode, a server call needs an exact remembered grant or separate approval. Automatic classification cannot grant sandboxed execution to an external call.

A child agent gets a server tool only when both the server’s :child-tools list names its exact raw name and the selected child role permits that resulting tool.

Connect, inspect, and refresh

Autolith connects effective servers and discovers tools while building its tool registry.

• A :required-p t server makes startup or reload fail when initialization or discovery fails
• An optional server stays visible as failed, so unrelated work can continue
• Retry it with mcp.refresh or (mcp :refresh)

Servers without tools may still provide resources or prompts. Autolith validates advertised tool names and schemas before showing them to the model. Provider calls use deterministic mcp__* namespaces and encoded operation names. In the terminal, calls and results use configured-server.raw-tool labels; schema discovery shows the server name.

Use (compact-tool nil) to expand successful MCP answers into styled fields. With compact tools enabled, successful answers collapse regardless of server annotations. Failures are visible in either mode. Text and structured content sections share one bounded preview.

(mcp.status)
(mcp.refresh)
(mcp.resources          :server "configured-server-name")
(mcp.resource-templates :server "configured-server-name")
(mcp.read-resource      :server "configured-server-name"
                        :uri    "resource-uri")
(mcp.prompts            :server "configured-server-name")
(mcp.get-prompt         :server "configured-server-name"
                        :name   "prompt-name")

• mcp.status reports source, transport, state, requirement, failure, and tool count, without credentials
• mcp.refresh reconnects where needed and refreshes advertised tools
• Resource and prompt helpers use the exact configured server name
• mcp.get-prompt accepts an optional object of string arguments

As for commands:

• (mcp) shows connection state.
• (mcp refresh refreshes connections and tool discovery (does not reread config).
• (mcp reload) rereads the site, global, and active directory files plus init.lisp, closes old runtimes, and

installs a fresh registry. (cwd) does the equivalent replacement before changing directory.

A notifications/tools/list_changed notification marks one server stale. Autolith refreshes it before the next provider request.

Text, structured content, embedded resources, and supported images in MCP results become ordinary Autolith tool results, and will be recorded.

Register from Lisp

Your global init.lisp, or whatever other file you load, can register the same property list used by mcp.sexp:

(register-mcp-server
 '(:name      "project-service"
   :transport
   (:type      :stdio
    :command   "/absolute/path/to/server"
    :directory :workspace)
   :approval  :prompt))

Precedence, low to high:

• site mcp.sexp
• site init.lisp
• global mcp.sexp
• active directory-scoped mcp.sexp files
• trusted-directory init.lisp files, outermost to nearest
• global user init.lisp
• live runtime registrations

A higher layer shadows the same case-sensitive name. Reloading init.lisp atomically replaces its prior registrations. A load failure restores the previous registry.

Limits and shutdown

• One MCP manager retains at most 8 MiB of encoded input schemas
• Required servers receive capacity first, then optional servers
• A required overflow fails startup or refresh
• An optional overflow marks that server failed and clears its tools

Shutdown, MCP reload, conversation replacement, and checkpoint preparation close live clients.