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.(cancel-gateway-server-auth! flow-id)Forget an abandoned flow and release its listener.
Forget an abandoned flow and release its listener.
(canonical-name name)The one spelling of an MCP server name, or nil when nothing is left: lower case,
accents dropped, and each run of characters other than a-z and 0-9 (blanks,
newlines, _, .) as one -. Figma Dev is figma-dev. The name keys the
config, the token file and the host verb, so every reader and writer uses it.
The one spelling of an MCP server name, or nil when nothing is left: lower case, accents dropped, and each run of characters other than `a-z` and `0-9` (blanks, newlines, `_`, `.`) as one `-`. `Figma Dev` is `figma-dev`. The name keys the config, the token file and the host verb, so every reader and writer uses it.
(clear-session-servers! session-id)Drop and CLOSE every session-scoped server attached to session-id.
Drop and CLOSE every session-scoped server attached to `session-id`.
(complete-gateway-server-auth! flow-id input)Finish flow flow-id with the redirect URL the user pasted back (or a bare
authorization code) and reconnect the server.
Finish flow `flow-id` with the redirect URL the user pasted back (or a bare authorization code) and reconnect the server.
(definitions db target)The MCP server definitions that settings target resolves, under canonical names.
The MCP server definitions that settings `target` resolves, under canonical names.
(delete-gateway-server! name)Remove a server from this gateway's machine-owned state and stop it now.
Remove a server from this gateway's machine-owned state and stop it now.
(delete-scoped-server! db target name)Remove only the selected definition override, revealing an inherited server if present.
Remove only the selected definition override, revealing an inherited server if present.
(gateway-server-auth-status name)Non-secret OAuth state for name: whether tokens exist, whether they expired.
Non-secret OAuth state for `name`: whether tokens exist, whether they expired.
(gateway-servers)Sanitized MCP inventory for gateway management. Secrets (env and header values)
deliberately never cross this boundary. Every configured server is listed —
gateway-owned and hand-written alike — and is_managed says which of them
this API may write. Reading the inventory also nudges the pool toward config
and arms the health loop, so a client that has not run a turn yet still gets —
not merely sees — the connections the gateway owes it.
String-keyed throughout, like every MCP surface.
Sanitized MCP inventory for gateway management. Secrets (env and header values) deliberately never cross this boundary. Every configured server is listed — gateway-owned and hand-written alike — and `is_managed` says which of them this API may write. Reading the inventory also nudges the pool toward config and arms the health loop, so a client that has not run a turn yet still gets — not merely sees — the connections the gateway owes it. String-keyed throughout, like every MCP surface.
(kill-gateway-server! name)Stop name NOW and keep it stopped: close the connection (for stdio that
destroys the child process, forcibly if it will not go) and set the kill brake
so the per-turn reconcile does not respawn it. Nothing is persisted — use
set-gateway-server-enabled! for a durable off switch. Works for hand-written
servers too: killing a runaway process is not editing the user's file.
Stop `name` NOW and keep it stopped: close the connection (for stdio that destroys the child process, forcibly if it will not go) and set the kill brake so the per-turn reconcile does not respawn it. Nothing is persisted — use `set-gateway-server-enabled!` for a durable off switch. Works for hand-written servers too: killing a runaway process is not editing the user's file.
(logout-gateway-server-auth! name)Forget the persisted OAuth tokens for name and drop the connection that was
using them.
Forget the persisted OAuth tokens for `name` and drop the connection that was using them.
(mcp-call server)(mcp-call server tool)(mcp-call server tool args)Invoke tool on configured MCP server server with args matching its input schema (omit or {} for none): {"server": S, "tool": S, "content": [<MCP content blocks>], "is_error": bool}; text is at content[i]["text"], a tool with an output schema adds "structured_content", and a refused call carries "input_schema" back with it. Called with server alone it lists that server's catalog instead: {"server": S, "tools": [{"name": S, "description": S, "input_schema": <JSON schema dict>}], "methods": [S]}; "methods" is there only for a server with resources or prompts. A tool that names one of these MCP requests sends it: resources/list, resources/templates/list, resources/read with {"uri": S}, prompts/list, prompts/get with {"name": S, "arguments": {...}}. The answer is {"server": S, "method": S} plus the keys of the MCP result; a list gives one page, and its "nextCursor" goes back as {"cursor": S}. Server names and status ride in ctx under env.mcp; the gateway connects and heals every enabled server on its own clock, so there is no connect/disconnect verb. Config: ~/.vis/state.yml :mcp :servers.
Invoke `tool` on configured MCP server `server` with `args` matching its input schema (omit or {} for none): {"server": S, "tool": S, "content": [<MCP content blocks>], "is_error": bool}; text is at content[i]["text"], a tool with an output schema adds "structured_content", and a refused call carries "input_schema" back with it. Called with `server` alone it lists that server's catalog instead: {"server": S, "tools": [{"name": S, "description": S, "input_schema": <JSON schema dict>}], "methods": [S]}; "methods" is there only for a server with resources or prompts. A `tool` that names one of these MCP requests sends it: `resources/list`, `resources/templates/list`, `resources/read` with {"uri": S}, `prompts/list`, `prompts/get` with {"name": S, "arguments": {...}}. The answer is {"server": S, "method": S} plus the keys of the MCP result; a list gives one page, and its "nextCursor" goes back as {"cursor": S}. Server names and status ride in ctx under env.mcp; the gateway connects and heals every enabled server on its own clock, so there is no connect/disconnect verb. Config: ~/.vis/state.yml :mcp :servers.
(poll-gateway-server-auth! flow-id)Non-blocking verdict for flow-id: pending, ok, or error. This is how a
client learns the loopback listener already finished the flow for it.
Non-blocking verdict for `flow-id`: `pending`, `ok`, or `error`. This is how a client learns the loopback listener already finished the flow for it.
(save-gateway-server! name raw-spec)Validate and persist a complete string-keyed server spec in this gateway's machine state, then reconnect it in the background. Returns its sanitized row.
env and headers survive a save that omits them: see with-preserved-secrets.
Validate and persist a complete string-keyed server spec in this gateway's machine state, then reconnect it in the background. Returns its sanitized row. `env` and `headers` survive a save that omits them: see `with-preserved-secrets`.
(save-scoped-server! db target name raw-spec)Write a scoped definition. Credentials and OAuth administration stay global.
Write a scoped definition. Credentials and OAuth administration stay global.
(scoped-servers db target)Sanitized definitions and provenance for one settings target; does not change other pools.
Sanitized definitions and provenance for one settings target; does not change other pools.
(session-servers session-id)The session-scoped servers attached to session-id as string-keyed rows
[{name, transport, is_connected}], in name order — like every MCP surface.
The session-scoped servers attached to `session-id` as string-keyed rows
`[{name, transport, is_connected}]`, in name order — like every MCP surface.(set-gateway-server-enabled! name enabled)Persist an enabled/disabled override without exposing or accepting secrets.
Persist an enabled/disabled override without exposing or accepting secrets.
(set-scoped-server-enabled! db target name enabled)Change availability without mutating an ancestor definition or stopping another session.
Change availability without mutating an ancestor definition or stopping another session.
(set-session-servers! session-id servers)Attach servers — {name raw-spec}, each raw spec shaped exactly like a
:mcp :servers config entry — to session-id, REPLACING whatever that
session had, and connect each one EAGERLY so the caller learns now whether the
client's servers actually work. Nothing is persisted. Returns
{connected [name…], failed [{server …, error …}…]} — STRING-keyed, like every
MCP surface. A detach/replacement
racing a handshake wins: the just-opened transport is closed, never leaked.
Attach `servers` — `{name raw-spec}`, each raw spec shaped exactly like a
`:mcp :servers` config entry — to `session-id`, REPLACING whatever that
session had, and connect each one EAGERLY so the caller learns now whether the
client's servers actually work. Nothing is persisted. Returns
`{connected [name…], failed [{server …, error …}…]}` — STRING-keyed, like every
MCP surface. A detach/replacement
racing a handshake wins: the just-opened transport is closed, never leaked.(start-gateway-server! name)Undo a kill: release the brake and connect name right now. A disabled server
stays down — enabled false is the user's decision, not a stale brake.
Undo a kill: release the brake and connect `name` right now. A disabled server stays down — `enabled false` is the user's decision, not a stale brake.
(start-gateway-server-auth! name)(start-gateway-server-auth! name {:keys [callback-mode]})Begin a headless OAuth 2.1 flow for HTTP server name. Returns
{flow_id, server, kind, url, redirect_uri, callback_mode, expires_at_ms, status}.
callback-mode is loopback (default) or app (direct native return); never a relay.
Begin a headless OAuth 2.1 flow for HTTP server `name`. Returns
`{flow_id, server, kind, url, redirect_uri, callback_mode, expires_at_ms, status}`.
`callback-mode` is loopback (default) or app (direct native return); never a relay.(test-gateway-server! name raw-spec)Probe a candidate without saving it; return only non-secret tool metadata. An HTTP 401 Bearer challenge without static credentials returns disconnected with no tools, allowing save followed by OAuth sign-in. Other failures throw. Any opened connection is always closed.
Probe a candidate without saving it; return only non-secret tool metadata. An HTTP 401 Bearer challenge without static credentials returns disconnected with no tools, allowing save followed by OAuth sign-in. Other failures throw. Any opened connection is always closed.
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 |