Skip to main content

How to embed the StackQL MCP server in a macOS Swift application

StackQL's MCP server can run inside a native macOS app with no separate install and no runtime dependency. The stackql-mcp-swift package spawns the signed StackQL binary over stdio behind the official Swift MCP SDK client. Because the darwin-universal binary is Developer ID signed and Apple-notarised, you can bundle it inside a signed .app and keep the app's notarisation valid - the pattern behind CloudLens, a menu-bar cloud sentinel.

Steps​

  1. Add the package to Package.swift:
.package(url: "https://github.com/stackql/stackql-mcp-swift.git", from: "0.1.0")

Requires macOS 13+ and Swift 6.1 (Xcode 16.3+). The single dependency is the official Swift MCP SDK.

  1. Start the server and call a tool. Options.mode defaults to .readOnly:
import StackQLMCP

var options = Options()
options.mode = .readOnly
options.auth = ["github": ["type": "null_auth"]]

let server = try await StackQLServer.start(options)
let tools = try await server.listToolNames()
print("\(tools.count) tools available")

let services = try await server.call(
    "list_services", ["provider": "github", "row_limit": 5])
print(services.text)

await server.stop()

For external harnesses, StackQLServer.resolveCommand(_:) returns the resolved launch command.

  1. Choose a mode. Options.mode defaults to .readOnly. Set .safe, .deleteSafe, or .fullAccess only when the app needs to provision. Escalation is explicit.

Bundle the notarised binary in a signed app​

The darwin-universal binary is Developer ID signed and Apple-notarised, so it can be bundled inside a signed macOS .app while keeping the app's own notarisation valid. Binary resolution order:

  1. Explicit binaryOverride.
  2. Bundled .app resources.
  3. Shared cache at ~/.stackql/mcp-server-bin/.
  4. Download with sha256 verification (when allowDownload is set).

Put the notarised binary in app resources and the bundled path wins - the app is fully self-contained with no first-run download.

Demo app​

CloudLens is a menu-bar cloud sentinel that embeds the notarised binary and runs a read_only check suite.