stackql · jeffreyaven · Jun 12, 2026 · Jun 12, 2026 · Jun 12, 2026
diff --git a/.gitignore b/.gitignore
@@ -4,6 +4,9 @@ ref/antlr/.antlr/
 # Dependencies
 /node_modules
 
+# yarn is the package manager for this repo - keep npm's lockfile out
+package-lock.json
+
 # Production
 /build
 

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -17,7 +17,7 @@ The two surfaces serve the same URLs to all visitors (no UA-based cloaking). The
 - Docusaurus 3.10.1, classic preset
 - React 18 (pinned - several deps require it)
 - MUI 5/6 (already in deps - Material UI and emotion)
-- Node 22 toolchain
+- Node 22 toolchain, yarn is the package manager (yarn.lock is the only lockfile - package-lock.json is gitignored)
 - Deployed via Netlify, build = `npm run build`, publish = `build/`
 - Search via Algolia DocSearch (`ALGOLIA_APP_ID`, `ALGOLIA_API_KEY`, `ALGOLIA_INDEX_NAME` env vars required for prod builds)
 
@@ -157,8 +157,8 @@ When `faq:` is present, the plugin emits a `FAQPage` JSON-LD node and links it t
 The two AEO plugins are developed in sibling repos. To bump:
 
 ```
-npm install @stackql/docusaurus-plugin-structured-data@<version> --save
-npm install @stackql/docusaurus-plugin-aeo@<version> --save
+yarn add @stackql/docusaurus-plugin-structured-data@<version>
+yarn add @stackql/docusaurus-plugin-aeo@<version>
 ```
 
 If the build breaks after a bump, the plugin's CHANGELOG.md is the first place to look. Both plugins maintain detailed changelogs noting breaking changes and config migrations.

diff --git a/README.md b/README.md
@@ -39,6 +39,7 @@ or PowerShell:
 $env:ALGOLIA_API_KEY="<your algolia api key>"
 $env:ALGOLIA_APP_ID="<your algolia app id>"
 $env:ALGOLIA_INDEX_NAME="<your algolia index name>"
+$env:ALGOLIA_AGENTID="<your algolia agent id>"
 $env:HUBSPOT_ACCT_ID="<your hubspot account id>"
 $env:HUBSPOT_FORM_ID="<your hubspot form id>"
 $env:HUBSPOT_REGION="<your hubspot region>"

diff --git a/docs/command-line-usage/mcp.md b/docs/command-line-usage/mcp.md
@@ -116,6 +116,8 @@ The `--mcp.config` flag accepts a JSON object with the following structure.
 |--|--|--|
 |`backend.dsn`|PostgreSQL connection string for the backend StackQL server.|Yes (for `reverse_proxy`)|
 
+<br />
+
 :::info
 
 The backend DSN should include the `default_query_exec_mode=simple_protocol` parameter for optimal compatibility.
@@ -129,6 +131,8 @@ The backend DSN should include the `default_query_exec_mode=simple_protocol` par
 |`enabled_tools`|Array of tool names that the server is permitted to publish.  When omitted or empty, every built-in tool is registered.  Used to expose a narrow subset (e.g., a read-only inventory server).|
 |`enabled_prompts`|Array of prompt names.  Same semantics as `enabled_tools` but for the prompt surface.|
 
+<br/>
+
 Example -- a server that publishes only `server_info` and `list_providers`:
 
 ```json
@@ -151,6 +155,8 @@ Example -- a server that publishes only `server_info` and `list_providers`:
 |`delete_safe`|allow|allow|needs approval|needs approval|
 |`full_access`|allow|allow|allow|allow|
 
+<br />
+
 **Refuse** returns an error immediately to the client.
 
 **Needs approval** uses the MCP elicitation flow:
@@ -206,6 +212,8 @@ Every tool call writes one JSONL record to the configured audit sink.  Audit is
 |`duration_ms`|Wall-clock duration of the gate + handler.|
 |`error`|Error message if the tool errored or was refused.|
 
+<br />
+
 Result rows from `SELECT` statements are deliberately excluded -- they can be very large and may carry sensitive data.
 
 #### File sink
@@ -553,25 +561,7 @@ Sample audit log line for the same mutation:
 
 To integrate StackQL's MCP server with an AI assistant, register `stackql` as an MCP server in the assistant's configuration.  Most editor-embedded MCP clients run the server over `stdio`; for those, use `--mcp.server.type=stdio` and the assistant launches the process directly.  Standalone agents that speak HTTP can connect to a long-running `stackql mcp --mcp.server.type=http` process.
 
-**For Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
-
-```json
-{
-  "mcpServers": {
-    "stackql": {
-      "command": "stackql",
-      "args": [
-        "mcp",
-        "--mcp.server.type=stdio",
-        "--mcp.config",
-        "{\"server\": {\"transport\": \"stdio\", \"mode\": \"safe\"}}"
-      ]
-    }
-  }
-}
-```
-
-Claude Desktop advertises the elicitation capability, so `mode: safe` (the default) will prompt the user for approval on each mutation.  Switch to `mode: read_only` for inventory-only access or `mode: full_access` to skip prompts.
+For Claude Desktop - including the prebuilt one-click MCP Bundle (`.mcpb`) and manual configuration - see [Using StackQL with Claude Desktop](/docs/getting-started/claude-desktop).
 
 :::note
 

diff --git a/docs/getting-started/claude-desktop.md b/docs/getting-started/claude-desktop.md
@@ -16,7 +16,35 @@ image: "/img/stackql-featured-image.png"
 
 StackQL integrates with Claude Desktop via the Model Context Protocol (MCP), enabling you to query and provision cloud resources across multiple cloud providers using natural language. This powerful combination allows you to interact with your cloud infrastructure conversationally while leveraging StackQL's SQL-based interface under the hood.
 
-## Prerequisites
+## One-Click Install (MCP Bundle)
+
+The easiest way to use the StackQL MCP server with Claude Desktop is the prebuilt MCP Bundle (`.mcpb`) - a one-click installable package containing the signed `stackql` binary and the server configuration. No separate StackQL installation is required.
+
+Download the bundle for your platform from the latest release:
+
+| Platform | Bundle |
+|---|---|
+| macOS (universal) | [stackql-mcp-darwin-universal.mcpb](https://github.com/stackql/stackql/releases/latest/download/stackql-mcp-darwin-universal.mcpb) |
+| Windows x64 | [stackql-mcp-windows-x64.mcpb](https://github.com/stackql/stackql/releases/latest/download/stackql-mcp-windows-x64.mcpb) |
+| Linux x64 | [stackql-mcp-linux-x64.mcpb](https://github.com/stackql/stackql/releases/latest/download/stackql-mcp-linux-x64.mcpb) |
+| Linux arm64 | [stackql-mcp-linux-arm64.mcpb](https://github.com/stackql/stackql/releases/latest/download/stackql-mcp-linux-arm64.mcpb) |
+
+<br/>
+
+Then in Claude Desktop: **Settings -> Extensions -> Install Extension** and select the downloaded file. The embedded binary is Authenticode-signed (Windows) and Apple-notarised (macOS); each bundle has a `.sha256` checksum alongside it on the [release page](https://github.com/stackql/stackql/releases/latest). To verify before installing:
+
+```bash
+# macOS / Linux
+shasum -a 256 -c stackql-mcp-darwin-universal.mcpb.sha256
+```
+
+The server is also listed on the [Official MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=stackql) as `io.github.stackql/stackql-mcp`, which pins these checksums.
+
+## Manual Configuration
+
+If you already have StackQL installed, you can register the StackQL MCP server in Claude Desktop's configuration file directly.
+
+### Prerequisites
 
 Before setting up StackQL with Claude Desktop, ensure you have:
 
@@ -30,8 +58,6 @@ Verify StackQL is in your system PATH by running:
 stackql --version
 ```
 
-## Configuration
-
 ### Setting Up the MCP Server
 
 To enable Claude Desktop to communicate with StackQL, you need to configure the MCP server in your Claude Desktop configuration file.
@@ -95,12 +121,14 @@ You only need to include environment variables for the cloud providers you plan
 Never commit your `claude_desktop_config.json` file with actual credentials to version control. Use secure credential management practices.
 :::
 
+Claude Desktop advertises the MCP elicitation capability, so the default server mode (`safe`) will prompt you for approval on each mutation. Switch to `mode: read_only` for inventory-only access or `mode: full_access` to skip prompts - see [Server modes](/docs/command-line-usage/mcp#server-modes).
+
 ### Provider-Specific Credentials
 
 Different cloud providers require different authentication methods, see the provider docs ([https://stackql.io/docs/providers](https://stackql.io/docs/providers))for the environment variables required for your desired provider(s).
 
 
-## Restarting Claude Desktop
+### Restarting Claude Desktop
 
 After updating the configuration file, restart Claude Desktop to load the new MCP server configuration. The StackQL MCP server will be automatically started when you begin a new conversation.
 

diff --git a/docs/installing-stackql.md b/docs/installing-stackql.md
@@ -19,6 +19,7 @@ import DownloadIcon from '@mui/icons-material/Download';
 import ArticleIcon from '@mui/icons-material/Article';
 import {
   BinaryDownloadLink,
+  DropDownBinaryDownloadLink,
 } from '../src/components';
 import buttonStyles from '../src/components/BinaryDownloadLink/binarydownloadlink.module.css';
 import clsx from 'clsx';
@@ -32,6 +33,7 @@ Instructions for installing StackQL on various different platforms are provided
     { label: 'Linux', value: 'linux', },
     { label: 'Windows', value: 'windows', },
     { label: 'Docker', value: 'docker', },
+    { label: 'Claude Desktop / MCP', value: 'mcp', },
     { label: 'stackql-deploy', value: 'deploy', },
     { label: 'Cloud Shells', value: 'shells', },
   ]}
@@ -201,6 +203,58 @@ Instructions for installing StackQL on various different platforms are provided
   ```
 </Box>
 
+</TabItem>
+<TabItem value="mcp">
+
+<Box sx={{ 
+  border: '1px solid #e0e0e0', 
+  borderRadius: '4px', 
+  p: 3, 
+  mb: 2
+}}>
+
+  ## Claude Desktop / MCP clients
+
+  Prebuilt MCP Bundles (`.mcpb`) are attached to every StackQL release for one-click installation of the StackQL MCP server into Claude Desktop - no separate StackQL installation is required.  Bundles are available for macOS, Windows and Linux.
+
+  <Box sx={{ mt: 2, mb: 1, display: 'flex', gap: 2 }}>
+    <div className={clsx(buttonStyles.buttons)} style={{ display: 'flex', gap: '12px' }}>
+      <BinaryDownloadLink 
+        iconSize={20} 
+        text="Download macOS MCPB"
+        to="https://github.com/stackql/stackql/releases/latest/download/stackql-mcp-darwin-universal.mcpb"
+      />
+      <DropDownBinaryDownloadLink 
+        iconSize={20} 
+        text="Download Linux MCPB (x64)"
+        to="https://github.com/stackql/stackql/releases/latest/download/stackql-mcp-linux-x64.mcpb"
+        options={[
+          { text: 'Download Linux MCPB (arm64)', to: 'https://github.com/stackql/stackql/releases/latest/download/stackql-mcp-linux-arm64.mcpb' },
+        ]}
+      />
+      <BinaryDownloadLink 
+        iconSize={20} 
+        text="Download Windows MCPB"
+        to="https://github.com/stackql/stackql/releases/latest/download/stackql-mcp-windows-x64.mcpb"
+      />      
+    </div>
+  </Box>
+
+<br />
+:::info
+
+The StackQL MCP server is also listed on the Official MCP Registry as `io.github.stackql/stackql-mcp`, see [__MCP Registry__](https://github.com/mcp).  
+
+:::
+
+:::tip
+
+See [Using StackQL with Claude Desktop](/docs/getting-started/claude-desktop#one-click-install-mcp-bundle) for download links and installation instructions.
+
+:::
+
+</Box>
+
 </TabItem>
 <TabItem value="deploy">
 

diff --git a/docusaurus.config.js b/docusaurus.config.js
@@ -204,10 +204,15 @@ const config = {
       '@docusaurus/preset-classic',
       /** @type {import('@docusaurus/preset-classic').Options} */
       ({
-        gtag: {
-          trackingID: 'G-M7GH68KJ3F',
-          anonymizeIP: true,
-        },        
+        // gtag only on Netlify builds - local production builds write gtag codegen
+        // into .docusaurus, which a concurrently running dev server hot-reloads,
+        // breaking window.gtag on every route change
+        ...(process.env.NETLIFY === 'true' ? {
+          gtag: {
+            trackingID: 'G-M7GH68KJ3F',
+            anonymizeIP: true,
+          },
+        } : {}),
         sitemap: {
           changefreq: 'weekly',
           priority: 0.5,

diff --git a/netlify.toml b/netlify.toml
@@ -1,5 +1,5 @@
 [build]
-  command = "npm run build"
+  command = "yarn build"
   publish = "build"
 
 # Serve raw markdown companion files with the correct MIME type so AI