Skip to main content

How to embed the StackQL MCP server in a Kotlin or JVM application

StackQL's MCP server can run inside a Kotlin or JVM application with no npx, no separate install, and no runtime dependency. The io.stackql:stackql-mcp library spawns the signed StackQL binary over stdio behind the official Kotlin MCP SDK client, and a companion Gradle plugin wires the same launch into a build. This is the pattern behind costgate, a cost gate for CI/CD shipped as a CLI and a Gradle plugin.

Steps​

  1. Add the library to your Gradle dependencies:
dependencies {
    implementation("io.stackql:stackql-mcp:0.1.0")
}

Requires JDK 17 and Kotlin 2.x. The client comes from the official Kotlin MCP SDK.

  1. Start the server and list tools. The builder defaults to Mode.ReadOnly:
import io.stackql.mcp.LaunchArgs
import io.stackql.mcp.Mode
import io.stackql.mcp.StackqlMcp

suspend fun main() {
    val server = StackqlMcp.builder()
        .mode(Mode.ReadOnly)
        .auth(LaunchArgs.authFor("github", "null_auth"))
        .start()

    server.use {
        val tools = server.client.listTools().tools
        println("${tools.size} tools available")
    }
}
  1. Choose a mode. .mode() defaults to Mode.ReadOnly. Set Mode.Safe, Mode.DeleteSafe, or Mode.FullAccess only when the app needs to provision. Escalation is explicit.

Run StackQL queries from a Gradle build​

The Gradle plugin wires the embedded server into your build so CI tasks run StackQL queries without a separate install step. The costgate demo gates infrastructure deploys on cost budgets, as a CLI:

costgate check --intent examples/costgate.yaml --explain

and as a Gradle plugin:

plugins {
    id("io.stackql.costgate") version "0.1.0"
}

costgate {
    intent.set(layout.projectDirectory.file("costgate.yaml"))
    explain.set(true)
}