Skip to main content

How to embed the StackQL MCP server in a Gleam application

StackQL's MCP server can run inside a Gleam application on the Erlang/BEAM target with no separate install and no runtime dependency. The stackql_mcp library spawns the signed StackQL binary over stdio and integrates with OTP supervision, so a BEAM service gets a governed, self-describing SQL interface to every cloud and SaaS provider in the StackQL registry. The server is exposed as an OTP child via child_spec() so it can sit inside your own supervision tree.

Steps​

  1. Add the library:
gleam add stackql_mcp

Targets Erlang/BEAM only (not the JavaScript target).

  1. Start the server and list tools. Config.mode defaults to read_only:
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)
}

Use child_spec() to place the server under a supervisor, with supervised_list_tools() and supervised_call_tool() for supervised calls.

  1. Choose a mode. Config.mode defaults to read_only. Build stackql_mcp.Config(..stackql_mcp.default_config(), mode: stackql_mcp.safe) to escalate to safe, delete_safe, or full_access. Escalation is explicit.

Binary sourcing​

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: explicit Config.binary, then STACKQL_MCP_BIN, then the shared cache at ~/.stackql/mcp-server-bin/. 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.