Liking cljdoc? Tell your friends :D

com.blockether.vis.internal.foundation.mcp.core

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.
raw docstring

cancel-gateway-server-auth!clj

(cancel-gateway-server-auth! flow-id)

Forget an abandoned flow and release its listener.

Forget an abandoned flow and release its listener.
sourceraw docstring

canonical-nameclj

(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.
sourceraw docstring

clear-session-servers!clj

(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`.
sourceraw docstring

complete-gateway-server-auth!clj

(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.
sourceraw docstring

definitionsclj

(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.
sourceraw docstring

delete-gateway-server!clj

(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.
sourceraw docstring

delete-scoped-server!clj

(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.
sourceraw docstring

gateway-server-auth-statusclj

(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.
sourceraw docstring

gateway-serversclj

(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.
sourceraw docstring

kill-gateway-server!clj

(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.
sourceraw docstring

logout-gateway-server-auth!clj

(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.
sourceraw docstring

mcp-callclj

(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.
sourceraw docstring

poll-gateway-server-auth!clj

(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.
sourceraw docstring

register!clj

(register!)
source

save-gateway-server!clj

(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`.
sourceraw docstring

save-scoped-server!clj

(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.
sourceraw docstring

scoped-serversclj

(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.
sourceraw docstring

session-serversclj

(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.
sourceraw docstring

set-gateway-server-enabled!clj

(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.
sourceraw docstring

set-scoped-server-enabled!clj

(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.
sourceraw docstring

set-session-servers!clj

(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.
sourceraw docstring

start-gateway-server!clj

(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.
sourceraw docstring

start-gateway-server-auth!clj

(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.
sourceraw docstring

test-gateway-server!clj

(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.
sourceraw docstring

vis-extensionclj

source

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