vis-agent gateway mcp commands for gateway-owned MCP servers: list, add,
test, remove, enable, disable, kill, start and OAuth sign-in.
`vis-agent gateway mcp` commands for gateway-owned MCP servers: list, add, test, remove, enable, disable, kill, start and OAuth sign-in.
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`.Built-in Model Context Protocol (MCP) surface. The gateway daemon owns ONE
shared pool of MCP connections ({server {:conn spec}}); every session sees
the same live tools. Always on: MCP is core infrastructure, not a droppable
plug-in and not gated by any toggle. The pool is empty (and costs nothing)
until at least one server is declared in config.
Servers are declared natively in ~/.vis/state.yml:
{:mcp {:servers {"filesystem" {:transport :stdio :command "npx" :args ["-y" "@modelcontextprotocol/server-filesystem" "/path"]} "remote" {:transport :streamable-http :url "https://.../mcp" :headers {"Authorization" "Bearer ${MY_TOKEN}"} :timeout_ms 60000} "stale" {:enabled false :url "https://.../mcp"}}}}
Every string in :headers / :env / :args / :url / :command / :cwd
supports ${ENV_VAR} interpolation from the host environment. :enabled false skips the server without deleting the entry. HTTP servers with no
static bearer transparently negotiate OAuth 2.1 on first 401 (RFC 9728
discovery + RFC 7591 dynamic client registration + PKCE loopback).
ONE host verb, with the wire name mcp__call:
mcp__call(server, tool, args) - call a tool
mcp__call(server) - that server's descriptions + input schemas
mcp__call(server, method, params) - an MCP request for resources or prompts,
such as resources/read
A block does not type that verb: the sandbox binds it under a private name, and
has no mcp name. The sandbox binds each server as a name
(resources/vis-host-python/mcp.py), the python-name of the server:
await linear.save_issue(title=...). inspect.signature gives the parameters
of a tool or a prompt. doc prints the page of a server, a tool
or a prompt, apropos finds them, and the resources of the servers are rows of
list_attachments().
There is deliberately NO connect/disconnect verb. The daemon connects every enabled server, health-checks the pool on its own clock, and reaps/respawns a dead one; a tool call self-heals its connection too. Starting or stopping a server is a human admin action on the gateway API (save/enable/kill/start), never something one session does to a resource every other session shares.
Every visible server rides in ctx under env.mcp with its sandbox name and its
status, keyed by server name so a change diffs per server. Its tools and its
prompts are not in ctx: apropos and doc give them.
Built-in Model Context Protocol (MCP) surface. The gateway daemon owns ONE
shared pool of MCP connections (`{server {:conn spec}}`); every session sees
the same live tools. Always on: MCP is core infrastructure, not a droppable
plug-in and not gated by any toggle. The pool is empty (and costs nothing)
until at least one server is declared in config.
Servers are declared natively in `~/.vis/state.yml`:
{:mcp {:servers {"filesystem" {:transport :stdio :command "npx"
:args ["-y" "@modelcontextprotocol/server-filesystem" "/path"]}
"remote" {:transport :streamable-http :url "https://.../mcp"
:headers {"Authorization" "Bearer ${MY_TOKEN}"}
:timeout_ms 60000}
"stale" {:enabled false :url "https://.../mcp"}}}}
Every string in `:headers` / `:env` / `:args` / `:url` / `:command` / `:cwd`
supports `${ENV_VAR}` interpolation from the host environment. `:enabled
false` skips the server without deleting the entry. HTTP servers with no
static bearer transparently negotiate OAuth 2.1 on first 401 (RFC 9728
discovery + RFC 7591 dynamic client registration + PKCE loopback).
ONE host verb, with the wire name `mcp__call`:
mcp__call(server, tool, args) - call a tool
mcp__call(server) - that server's descriptions + input schemas
mcp__call(server, method, params) - an MCP request for resources or prompts,
such as `resources/read`
A block does not type that verb: the sandbox binds it under a private name, and
has no `mcp` name. The sandbox binds each server as a name
(`resources/vis-host-python/mcp.py`), the `python-name` of the server:
`await linear.save_issue(title=...)`. `inspect.signature` gives the parameters
of a tool or a prompt. `doc` prints the page of a server, a tool
or a prompt, `apropos` finds them, and the resources of the servers are rows of
`list_attachments()`.
There is deliberately NO connect/disconnect verb. The daemon connects every
enabled server, health-checks the pool on its own clock, and reaps/respawns a
dead one; a tool call self-heals its connection too. Starting or stopping a
server is a human admin action on the gateway API (save/enable/kill/start),
never something one session does to a resource every other session shares.
Every visible server rides in ctx under `env.mcp` with its sandbox name and its
status, keyed by server name so a change diffs per server. Its tools and its
prompts are not in ctx: `apropos` and `doc` give them.Form elicitation of MCP: in the middle of a tool call, a server asks the person
of the calling session for values. The requested schema becomes one input View,
and the answer of the person becomes the content of the reply. The schema is
flat: text, number, boolean and choice properties.
Form elicitation of MCP: in the middle of a tool call, a server asks the person of the calling session for values. The requested schema becomes one input View, and the answer of the person becomes the `content` of the reply. The schema is flat: text, number, boolean and choice properties.
One lazy babashka.http-client instance shared by every MCP HTTP subsystem.
One lazy babashka.http-client instance shared by every MCP HTTP subsystem.
OAuth 2.1 client for Model Context Protocol servers (spec 2025-06-18).
Flow — on HTTP 401 from an MCP server, we:
WWW-Authenticate: Bearer resource_metadata="..." (RFC 9728),
fall back to ${origin}/.well-known/oauth-protected-resource;authorization_servers[0];.well-known/oauth-authorization-server (RFC 8414) or
.well-known/openid-configuration for endpoints + capabilities;client_id;provider.flow, the SAME lifecycle used by model-provider authentication.
The initiating client opens the browser and returns directly to its gateway;~/.vis/mcp-tokens/<server>.edn;com.blockether.vis.internal.provider.oauth/make-file-refresher.The returned bearer-fn is a 0/1-arg function: 0-arg yields the current
bearer token; 1-arg (with the token the server just rejected) forces a
refresh. It never opens a browser and never waits — with nothing to refresh
it throws :mcp/oauth-required, which callers turn into sign in.
OAuth 2.1 client for Model Context Protocol servers (spec `2025-06-18`).
Flow — on HTTP 401 from an MCP server, we:
1. read `WWW-Authenticate: Bearer resource_metadata="..."` (RFC 9728),
fall back to `${origin}/.well-known/oauth-protected-resource`;
2. GET the resource-metadata JSON → pick an `authorization_servers[0]`;
3. GET its `.well-known/oauth-authorization-server` (RFC 8414) or
`.well-known/openid-configuration` for endpoints + capabilities;
4. dynamic-client-register (RFC 7591) if the AS supports it, or use
the caller-supplied `client_id`;
5. prepare an allowed callback and register it, then hand the adapter to
`provider.flow`, the SAME lifecycle used by model-provider authentication.
The initiating client opens the browser and returns directly to its gateway;
6. exchange code → access + refresh tokens; persist to
`~/.vis/mcp-tokens/<server>.edn`;
7. on later expiry / 401, refresh the token single-flight through
`com.blockether.vis.internal.provider.oauth/make-file-refresher`.
The returned `bearer-fn` is a 0/1-arg function: 0-arg yields the current
bearer token; 1-arg (with the token the server just rejected) forces a
refresh. It never opens a browser and never waits — with nothing to refresh
it throws `:mcp/oauth-required`, which callers turn into `sign in`.The names that Python has before a session starts. An MCP server does not take
one as its sandbox name: a block that says import time must get the module.
The names that Python has before a session starts. An MCP server does not take one as its sandbox name: a block that says `import time` must get the module.
Sampling of MCP: in the middle of a request, a server asks the model of the client for one answer. The person of the calling session sees the request first and allows or refuses it; nothing goes to a model without that. Vis sends text only: it declares no tools and no context for sampling.
Sampling of MCP: in the middle of a request, a server asks the model of the client for one answer. The person of the calling session sees the request first and allows or refuses it; nothing goes to a model without that. Vis sends text only: it declares no tools and no context for sampling.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |