Skip to main content

Gleam

Embed the StackQL MCP server in a Gleam application on the Erlang/BEAM target. The library integrates with OTP supervision, downloads and verifies the signed binary, and spawns it over stdio.

info

The embedded binary is downloaded and sha256-verified on first run, or vendored into your app. See the common contract.

Install​

gleam add stackql_mcp

Targets Erlang/BEAM only (not the JavaScript target). The server is exposed as an OTP child via child_spec() so it can sit inside your own supervision tree.

Quick start​

import gleam/io
import gleam/int
import gleam/list
import envoy
import stackql_mcp

pub fn main() {
  let config =
    stackql_mcp.Config(
      ..stackql_mcp.default_config(),
      auth: [stackql_mcp.auth_for("github", "null_auth")],
    )

  let assert Ok(server) =
    stackql_mcp.start(
      config: config,
      home: "/home/u",
      os: "linux",
      arch: "x86_64",
      getenv: envoy.get,
    )

  let assert Ok(tools) = stackql_mcp.list_tools(server)
  io.println(int.to_string(list.length(tools)) <> " tools available")

  stackql_mcp.stop(server)
}

The API is stackql_mcp.start(), stop(), and child_spec() for lifecycle; list_tools() and call_tool() for operations (with supervised_list_tools() and supervised_call_tool() variants for use under a supervisor); and Config, default_config(), and auth_for() for configuration.

Modes​

The mode is set on Config.mode and defaults to read_only. Set it to safe, delete_safe, or full_access to escalate:

stackql_mcp.Config(..stackql_mcp.default_config(), mode: stackql_mcp.safe)

Escalation is explicit - the server will not enable mutation or lifecycle tools unless you opt in.

Vendoring / embedding​

On start the library downloads the platform's StackQL bundle, verifies it against baked-in sha256 pins, and caches it in the shared family cache. Resolution precedence:

  1. Explicit Config.binary.
  2. STACKQL_MCP_BIN environment variable.
  3. Shared cache at ~/.stackql/mcp-server-bin/<version>/<platform-key>/.

For offline or air-gapped deployments, set STACKQL_MCP_BUNDLE to point at a local bundle.

Demo app​

pipewatch is the planned demo for this library. It is on the roadmap and not yet implemented.

github.com/stackql/stackql-mcp-gleam