Liking cljdoc? Tell your friends :D

com.blockether.vis.internal.foundation.mcp.client

Minimal Model Context Protocol (MCP) client. Speaks JSON-RPC 2.0 over two transports:

:stdio — spawn the server process and frame newline-delimited JSON-RPC on its stdin/stdout (the dominant local-server pattern). A daemon thread drains stderr into the vis log so a chatty server never deadlocks on a full pipe.

:http — Streamable HTTP: POST each JSON-RPC message to one endpoint; the reply is either application/json (one response) or text/event-stream (SSE), read as a stream. A stream that ends before its reply continues on a GET with Last-Event-ID. The Mcp-Session-Id handed back by initialize rides on every later request, a DELETE frees it on shutdown, and an optional GET listen loop hears server-pushed notifications.

:sse — the HTTP+SSE transport of protocol 2024-11-05, for a server that has no Streamable HTTP: one GET stream carries every message of the server, and its first event names the endpoint for the POST of each client message.

On every transport a ping of the server gets its answer, any other server request gets Method not found, and notifications/tools/list_changed invalidates the tools cache. With :elicitation? the client declares form elicitation: an elicitation/create of the server goes to the call that waits, and the :on-elicitation fn of that call answers it. With :sampling? the same holds for sampling/createMessage and :on-sampling. With :roots? the client declares roots and answers roots/list with the :roots of the newest request.

OAuth 2.1 (spec 2025-06-18) is supported for HTTP transports via oauth.clj: pass :bearer-fn (a 0/1-arg fn yielding the current Bearer token, called with the just-rejected token on 401). A 401 triggers a single-flight refresh and one automatic retry.

The client speaks two eras of the protocol. A server of a stateless revision (2026-07-28) answers server/discover: it gets no handshake and no session, every request carries the protocol version, the client capabilities and the client info in _meta, and a result of the type input_required gets its input and a new request. Over HTTP, the headers Mcp-Method, Mcp-Name and Mcp-Param-* name the request. Any other server gets the initialize handshake of the older revisions.

A conn is a plain map of closures + state; the extension treats it opaquely. Lifecycle: connect (which finds the era of the server) → list-tools / call-tool / request → close.

Minimal Model Context Protocol (MCP) client. Speaks JSON-RPC 2.0 over two
transports:

  :stdio  — spawn the server process and frame newline-delimited JSON-RPC on
            its stdin/stdout (the dominant local-server pattern). A daemon
            thread drains stderr into the vis log so a chatty server never
            deadlocks on a full pipe.

  :http   — Streamable HTTP: POST each JSON-RPC message to one endpoint; the
            reply is either `application/json` (one response) or
            `text/event-stream` (SSE), read as a stream. A stream that ends
            before its reply continues on a GET with `Last-Event-ID`. The
            `Mcp-Session-Id` handed back by `initialize` rides on every later
            request, a `DELETE` frees it on shutdown, and an optional GET
            listen loop hears server-pushed notifications.

  :sse    — the HTTP+SSE transport of protocol 2024-11-05, for a server that
            has no Streamable HTTP: one GET stream carries every message of
            the server, and its first event names the endpoint for the POST
            of each client message.

On every transport a `ping` of the server gets its answer, any other server
request gets `Method not found`, and `notifications/tools/list_changed`
invalidates the tools cache. With `:elicitation?` the client declares form
elicitation: an `elicitation/create` of the server goes to the call that
waits, and the `:on-elicitation` fn of that call answers it. With `:sampling?`
the same holds for `sampling/createMessage` and `:on-sampling`. With `:roots?`
the client declares roots and answers `roots/list` with the `:roots` of the
newest request.

OAuth 2.1 (spec `2025-06-18`) is supported for HTTP transports via
`oauth.clj`: pass `:bearer-fn` (a 0/1-arg fn yielding the current Bearer
token, called with the just-rejected token on 401). A 401 triggers a
single-flight refresh and one automatic retry.

The client speaks two eras of the protocol. A server of a stateless revision
(`2026-07-28`) answers `server/discover`: it gets no handshake and no session,
every request carries the protocol version, the client capabilities and the
client info in `_meta`, and a result of the type `input_required` gets its
input and a new request. Over HTTP, the headers `Mcp-Method`, `Mcp-Name` and
`Mcp-Param-*` name the request. Any other server gets the `initialize`
handshake of the older revisions.

A `conn` is a plain map of closures + state; the extension treats it
opaquely. Lifecycle: `connect` (which finds the era of the server) →
`list-tools` / `call-tool` / `request` → `close`.
raw docstring

alive?clj

(alive? conn)
source

call-toolclj

(call-tool conn tool-name arguments)
(call-tool conn tool-name arguments timeout-ms)
(call-tool conn tool-name arguments timeout-ms opts)

tools/call tool-name with arguments (a map). Returns the result map ({"content" [...] "isError" bool}). opts are those of request.

`tools/call` `tool-name` with `arguments` (a map). Returns the result map
(`{"content" [...] "isError" bool}`). `opts` are those of `request`.
sourceraw docstring

closeclj

(close conn)
source

connectclj

(connect name spec)

Connect to MCP server name per its spec and find its era. spec supports: stdio → {:transport :stdio :command :args :env :cwd :timeout-ms} streamable-http → {:transport :streamable-http :url :headers :bearer-fn :timeout-ms :listen? :on-notification} sse → {:transport :sse :url :headers :bearer-fn :timeout-ms} With :elicitation? true the client declares form elicitation, with :sampling? true sampling and with :roots? true roots; see request. On stdio and Streamable HTTP the first request is server/discover. A server of a stateless revision answers it, and the conn has :modern? true. Any other server gets the initialize handshake. When a Streamable HTTP server refuses the POST of initialize, the client tries the HTTP+SSE transport on the same URL, as the specification asks. When that fails too, the first failure is the one that it reports. Returns an opaque conn map (or throws).

Connect to MCP server `name` per its `spec` and find its era. `spec` supports:
  stdio           → `{:transport :stdio :command :args :env :cwd :timeout-ms}`
  streamable-http → `{:transport :streamable-http :url :headers :bearer-fn
                      :timeout-ms :listen? :on-notification}`
  sse             → `{:transport :sse :url :headers :bearer-fn :timeout-ms}`
With `:elicitation? true` the client declares form elicitation, with
`:sampling? true` sampling and with `:roots? true` roots; see `request`.
On stdio and Streamable HTTP the first request is `server/discover`. A server
of a stateless revision answers it, and the conn has `:modern? true`. Any other
server gets the `initialize` handshake.
When a Streamable HTTP server refuses the POST of `initialize`, the client tries
the HTTP+SSE transport on the same URL, as the specification asks. When that
fails too, the first failure is the one that it reports.
Returns an opaque `conn` map (or throws).
sourceraw docstring

default-timeout-msclj

source

list-allclj

(list-all conn method)
(list-all conn method opts)

Every row of the list request method, prompts/list or resources/list, from the pages of the server: at most list-row-limit rows. Cached on the conn after the first call; the list_changed notification of that list drops it. opts are those of request.

Every row of the list request `method`, `prompts/list` or `resources/list`,
from the pages of the server: at most `list-row-limit` rows. Cached on the conn
after the first call; the `list_changed` notification of that list drops it.
`opts` are those of `request`.
sourceraw docstring

list-row-limitclj

The most rows that list-all reads from one server. A server can list thousands of resources.

The most rows that `list-all` reads from one server. A server can list
thousands of resources.
sourceraw docstring

list-toolsclj

(list-tools conn)

tools/list → vector of tool maps {"name" "description" "inputSchema"}, from every page of the server. Cached on the conn after the first call; invalidated by notifications/tools/list_changed. A tool of a stateless HTTP server with an x-mcp-header that breaks the rules is left out.

`tools/list` → vector of tool maps `{"name" "description" "inputSchema"}`,
from every page of the server. Cached on the conn after the first call;
invalidated by `notifications/tools/list_changed`. A tool of a stateless HTTP
server with an `x-mcp-header` that breaks the rules is left out.
sourceraw docstring

requestclj

(request conn method params)
(request conn
         method
         params
         timeout-ms
         {:keys [on-elicitation on-sampling roots headers asker]})

Send the MCP request method with params on conn, and return its result map. opts has the answers of this request to the inputs that the client declared and that the server asks for, while the request waits or in an input_required result of a stateless server:

:on-elicitation answers a form elicitation. It gets the params of elicitation/create, runs on the calling thread, and returns {"action" "accept" "content" {...}} or the action decline; anything else is a cancel. The defaults of the schema fill the fields that an accepted content leaves out.

:on-sampling answers sampling/createMessage. It gets the params, runs on the calling thread, and returns the result map, or nil to refuse the request.

:roots is the vector of roots ({"uri" "name"}) for roots/list.

:asker names who gives those answers, such as a session id. A server that names no call sends its request to the newest call that waits on the connection. When the calls that wait have more than one asker, nobody is asked: the request gets no answer.

Send the MCP request `method` with `params` on `conn`, and return its result
map. `opts` has the answers of this request to the inputs that the client
declared and that the server asks for, while the request waits or in an
`input_required` result of a stateless server:

`:on-elicitation` answers a form elicitation. It gets the params of
`elicitation/create`, runs on the calling thread, and returns
`{"action" "accept" "content" {...}}` or the action `decline`;
anything else is a cancel. The defaults of the schema fill the fields that an
accepted content leaves out.

`:on-sampling` answers `sampling/createMessage`. It gets the params, runs on
the calling thread, and returns the result map, or nil to refuse the request.

`:roots` is the vector of roots (`{"uri" "name"}`) for `roots/list`.

`:asker` names who gives those answers, such as a session id. A server that
names no call sends its request to the newest call that waits on the
connection. When the calls that wait have more than one asker, nobody is
asked: the request gets no answer.
sourceraw docstring

stale-era?clj

(stale-era? conn failure)

Whether failure of a request on conn can mean that the server changed its era after the connect, or lost its session: a Streamable HTTP server refused the request itself, as a server of the other era does. Such a request did not run. The caller connects again, which finds the era again.

Whether `failure` of a request on `conn` can mean that the server changed its
era after the connect, or lost its session: a Streamable HTTP server refused
the request itself, as a server of the other era does. Such a request did not
run. The caller connects again, which finds the era again.
sourceraw docstring

cljdoc builds & hosts documentation for Clojure/Script libraries

Keyboard shortcuts
Ctrl+kJump to recent docs
←Move to previous article
→Move to next article
Ctrl+/Jump to the search field
× close