Skip to main content

How to embed the StackQL MCP server in a Go application

StackQL's MCP server can run inside a compiled Go program with no npx, no separate install, and no runtime dependency. The stackql-mcp-go library spawns the signed StackQL binary over stdio behind the official Go MCP SDK client, so your Go app gets a governed, self-describing SQL interface to every cloud and SaaS provider in the StackQL registry. This is the pattern behind sandboxctl, an on-demand infrastructure concierge shipped as one binary.

Steps​

  1. Add the library:
go get github.com/stackql/stackql-mcp-go
  1. Start the embedded server and call a tool. The server starts in read_only mode by default:
import (
    "context"
    "github.com/modelcontextprotocol/go-sdk/mcp"
    stackqlmcp "github.com/stackql/stackql-mcp-go/embed"
)

func main() {
    ctx := context.Background()
    client, err := stackqlmcp.StartServer(ctx, stackqlmcp.Options{
        Binary: StackqlMCPBinary(),
    })
    if err != nil {
        // handle error
    }
    defer client.Close()

    res, err := client.Session.CallTool(ctx, &mcp.CallToolParams{
        Name: "run_select_query",
        Arguments: map[string]any{"sql": "SELECT name FROM google.compute.regions WHERE project = 'my-project'"},
    })
    _ = res
}
  1. Choose a mode. Options.Mode defaults to read_only. Set it to safe, delete_safe, or full_access only when the app needs to provision. Escalation is explicit.

Ship a single binary with go:embed​

For a self-contained executable, add a go:generate fetch step that downloads and sha256-verifies the platform binary, then go:embed it into the build:

//go:generate go run github.com/stackql/stackql-mcp-go/cmd/stackql-mcp-fetch -platform auto -package main

At runtime StackqlMCPBinary() returns the embedded binary, so there is no first-run download. Without vendoring, the binary is downloaded and verified into the shared cache at ~/.stackql/mcp-server-bin/ on first run.

Demo app​

sandboxctl is an infrastructure concierge: an embedded StackQL MCP server plus a Claude agent loop in one Go binary that plans, cost-checks, and provisions ephemeral cloud sandboxes behind an approval gate.