From 3afc0fae395c247081ebecb53af1b5f188e0d791 Mon Sep 17 00:00:00 2001 From: Fede Barcelona Date: Thu, 26 Mar 2026 11:58:39 +0100 Subject: [PATCH 1/2] feat: add cross-platform binary releases and restructure setup docs Build standalone binaries for darwin/linux/windows (amd64/arm64/386) in the publish workflow, attach them with checksums to GitHub Releases, and reorganize the README around Go/Docker/Binary installation methods with CLI examples for Claude Code, Gemini CLI, and Codex CLI. --- .github/workflows/publish.yaml | 77 +++++++- README.md | 334 +++++++++++++++++++-------------- 2 files changed, 271 insertions(+), 140 deletions(-) diff --git a/.github/workflows/publish.yaml b/.github/workflows/publish.yaml index 6684632..c15ebb4 100644 --- a/.github/workflows/publish.yaml +++ b/.github/workflows/publish.yaml @@ -1,5 +1,5 @@ --- -name: Publish Docker image +name: Publish on: push: @@ -174,15 +174,74 @@ jobs: VERSION: ${{ needs.get-newer-version.outputs.new-version }} run: docker buildx imagetools inspect $REGISTRY:${VERSION} + build-binaries: + name: Build ${{ matrix.goos }}-${{ matrix.goarch }} binary + runs-on: ubuntu-latest + needs: [ get-newer-version ] + if: needs.get-newer-version.outputs.new-version != '' + defaults: + run: + shell: nix develop --command bash {0} + permissions: + contents: read + strategy: + matrix: + include: + - { goos: darwin, goarch: arm64, ext: tar.gz } + - { goos: darwin, goarch: amd64, ext: tar.gz } + - { goos: linux, goarch: arm64, ext: tar.gz } + - { goos: linux, goarch: amd64, ext: tar.gz } + - { goos: linux, goarch: "386", ext: tar.gz } + - { goos: windows, goarch: arm64, ext: zip } + - { goos: windows, goarch: amd64, ext: zip } + - { goos: windows, goarch: "386", ext: zip } + steps: + - name: Check out the repo + uses: actions/checkout@v5 + + - name: Install Nix + # Pinned to v21 commit SHA for supply-chain safety. + # To update: git ls-remote https://github.com/DeterminateSystems/nix-installer-action.git + uses: DeterminateSystems/nix-installer-action@c5a866b6ab867e88becbed4467b93592bce69f8a # v21 + + - name: Enable Nix cache + # Pinned to v13 commit SHA for supply-chain safety. + # To update: git ls-remote https://github.com/DeterminateSystems/magic-nix-cache-action.git + uses: DeterminateSystems/magic-nix-cache-action@565684385bcd71bad329742eefe8d12f2e765b39 # v13 + with: + use-flakehub: false + + - name: Build and package binary + env: + VERSION: ${{ needs.get-newer-version.outputs.new-version }} + ARCHIVE: sysdig-mcp-server_${{ matrix.goos }}-${{ matrix.goarch }} + BINARY: sysdig-mcp-server${{ matrix.goos == 'windows' && '.exe' || '' }} + run: | + CGO_ENABLED=0 GOOS=${{ matrix.goos }} GOARCH=${{ matrix.goarch }} \ + go build -ldflags "-w -s -X main.Version=${VERSION}" -o "${BINARY}" ./cmd/server + if [ "${{ matrix.ext }}" = "tar.gz" ]; then + tar -czf "${ARCHIVE}.tar.gz" "${BINARY}" + else + zip "${ARCHIVE}.zip" "${BINARY}" + fi + + - name: Upload artifact + uses: actions/upload-artifact@v5 + with: + name: binary-${{ matrix.goos }}-${{ matrix.goarch }} + path: sysdig-mcp-server_${{ matrix.goos }}-${{ matrix.goarch }}.${{ matrix.ext }} + if-no-files-found: error + retention-days: 1 + release: name: Create release at Github - needs: [ get-newer-version ] + needs: [ get-newer-version, push_to_registry, build-binaries ] if: needs.get-newer-version.outputs.new-version != '' runs-on: ubuntu-latest permissions: contents: write # Required for release creation steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@v5 with: fetch-depth: 0 fetch-tags: true @@ -208,6 +267,17 @@ jobs: - name: Generate changelog run: git-chglog -c .github/git-chglog/config.yml -o RELEASE_CHANGELOG.md $(git describe --tags $(git rev-list --tags --max-count=1)) + - name: Download binary artifacts + uses: actions/download-artifact@v6 + with: + path: /tmp/binaries + pattern: binary-* + merge-multiple: true + + - name: Generate checksums + working-directory: /tmp/binaries + run: sha256sum * > checksums.txt + - name: Create release uses: softprops/action-gh-release@v2 with: @@ -215,3 +285,4 @@ jobs: tag_name: ${{ needs.get-newer-version.outputs.new-version }} prerelease: false body_path: RELEASE_CHANGELOG.md + files: /tmp/binaries/* diff --git a/README.md b/README.md index 3f6c11b..e1ba208 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ ## Table of contents -- [MCP Server](#mcp-server) +- [Sysdig MCP Server](#sysdig-mcp-server) - [Table of contents](#table-of-contents) - [Description](#description) - [Quickstart Guide](#quickstart-guide) @@ -14,9 +14,10 @@ - [Requirements](#requirements) - [Configuration](#configuration) - [API Permissions](#api-permissions) - - [Running the Server](#running-the-server) - - [Docker (Recommended)](#docker-recommended) + - [Server Setup](#server-setup) - [Go](#go) + - [Docker](#docker) + - [Binary](#binary) - [Kubernetes](#kubernetes) - [Client Configuration](#client-configuration) - [Authentication](#authentication) @@ -36,48 +37,40 @@ Get up and running with the Sysdig MCP Server quickly using our pre-built Docker 1. **Get your API Token**: Go to your Sysdig Secure instance and navigate to **Settings > Sysdig Secure API**. Here, you can generate or copy your API token. This token is required to authenticate requests to the Sysdig Platform (See the [Configuration](#configuration) section for more details). -2. **Pull the image**: +2. **Configure your MCP client**: - Pull the latest Sysdig MCP Server image from the GitHub Container Registry: - - ```bash - docker pull ghcr.io/sysdiglabs/sysdig-mcp-server:latest - ``` - -3. **Configure your client**: - - For example, you can configure Claude Desktop app to use the Sysdig MCP Server by editing the `claude_desktop_config.json` file. This is useful for running the server locally with the `stdio` transport. You can apply this configuration to any other client that supports MCP (For more details, see the [Client Configuration](#client-configuration) section). + Add the following configuration to your MCP client (e.g., Claude Desktop's `claude_desktop_config.json`). The client will automatically pull the Docker image and start the server. You can apply this configuration to any other client that supports MCP (For more details, see the [Client Configuration](#client-configuration) section). Substitute the following placeholders with your actual values: - ``: The hostname of your Sysdig Secure instance (e.g., `https://us2.app.sysdig.com` or `https://eu1.app.sysdig.com`) - ``: Your Sysdig Secure API token ```json - { - "mcpServers": { - "sysdig-mcp-server": { - "command": "docker", - "args": [ - "run", - "-i", - "--rm", - "-e", - "SYSDIG_MCP_API_HOST", - "-e", - "SYSDIG_MCP_TRANSPORT", - "-e", - "SYSDIG_MCP_API_TOKEN", - "ghcr.io/sysdiglabs/sysdig-mcp-server:latest" - ], - "env": { - "SYSDIG_MCP_API_HOST": "", - "SYSDIG_MCP_API_TOKEN": "", - "SYSDIG_MCP_TRANSPORT": "stdio" - } + { + "mcpServers": { + "sysdig-mcp-server": { + "command": "docker", + "args": [ + "run", + "-i", + "--rm", + "-e", + "SYSDIG_MCP_API_HOST", + "-e", + "SYSDIG_MCP_TRANSPORT", + "-e", + "SYSDIG_MCP_API_TOKEN", + "ghcr.io/sysdiglabs/sysdig-mcp-server:latest" + ], + "env": { + "SYSDIG_MCP_API_HOST": "", + "SYSDIG_MCP_API_TOKEN": "", + "SYSDIG_MCP_TRANSPORT": "stdio" } } } - ``` + } + ``` ## Available Tools @@ -225,7 +218,7 @@ You can find your API token in the Sysdig Secure UI under **Settings > Sysdig Se ```bash # Required -SYSDIG_MCP_API_HOST=https://us2.app.sysdig.com +SYSDIG_MCP_API_HOST= SYSDIG_MCP_API_TOKEN=your-api-token-here # Optional @@ -240,7 +233,7 @@ SYSDIG_MCP_LOGLEVEL=INFO SYSDIG_MCP_TRANSPORT=streamable-http # Optional (Host and Token can be provided via HTTP headers) -# SYSDIG_MCP_API_HOST=https://us2.app.sysdig.com +# SYSDIG_MCP_API_HOST= # SYSDIG_MCP_API_TOKEN=your-api-token-here SYSDIG_MCP_LISTENING_PORT=8080 SYSDIG_MCP_LISTENING_HOST= @@ -279,41 +272,165 @@ For detailed instructions, see the official [Sysdig Roles Administration documen > **Service Account Limitation:** The `generate_sysql` tool currently does not work with Service Account tokens and will return a 500 error. For this tool, use an API token assigned to a regular user account. -## Running the Server +## Server Setup + +The MCP server is never invoked manually. Depending on the transport protocol, the MCP client either starts the server process automatically or connects to a running service: -You can run the MCP server using Docker (recommended for production) or directly with Go. +- **Local (`stdio`)**: The MCP client (e.g., Claude Desktop, Cursor) spawns the server process based on your [client configuration](#client-configuration). You only need the server available on your system via Go, Docker, or a pre-built binary. +- **Remote (`streamable-http`, `sse`)**: The server is deployed as a service (e.g., Docker Compose, Kubernetes) and the MCP client connects to it via URL. -### Docker (Recommended) +### Go + +If you have Go installed, the MCP client can run the server directly without cloning the repository. Configure your client with: + +```json +{ + "mcpServers": { + "sysdig-mcp-server": { + "command": "go", + "args": [ + "run", + "github.com/sysdiglabs/sysdig-mcp-server/cmd/server@latest" + ], + "env": { + "SYSDIG_MCP_API_HOST": "", + "SYSDIG_MCP_API_TOKEN": "", + "SYSDIG_MCP_TRANSPORT": "stdio" + } + } + } +} +``` -The easiest way to run the server is using the pre-built Docker image from GitHub Container Registry (as shown in the [Quickstart Guide](#quickstart-guide)). +Or using the CLI: ```bash -docker run -e SYSDIG_MCP_API_HOST= -e SYSDIG_MCP_API_TOKEN= -e SYSDIG_MCP_TRANSPORT=stdio -p 8080:8080 ghcr.io/sysdiglabs/sysdig-mcp-server:latest +# Claude Code +claude mcp add --transport stdio \ + -e SYSDIG_MCP_API_HOST= \ + -e SYSDIG_MCP_API_TOKEN= \ + -e SYSDIG_MCP_TRANSPORT=stdio \ + -- sysdig-mcp-server go run github.com/sysdiglabs/sysdig-mcp-server/cmd/server@latest + +# Gemini CLI +gemini mcp add -t stdio \ + -e SYSDIG_MCP_API_HOST= \ + -e SYSDIG_MCP_API_TOKEN= \ + -e SYSDIG_MCP_TRANSPORT=stdio \ + sysdig-mcp-server go run github.com/sysdiglabs/sysdig-mcp-server/cmd/server@latest + +# Codex CLI +codex mcp add \ + --env SYSDIG_MCP_API_HOST= \ + --env SYSDIG_MCP_API_TOKEN= \ + --env SYSDIG_MCP_TRANSPORT=stdio \ + -- sysdig-mcp-server go run github.com/sysdiglabs/sysdig-mcp-server/cmd/server@latest ``` -To use the `streamable-http` or `sse` transports (for remote MCP clients), set the `SYSDIG_MCP_TRANSPORT` environment variable accordingly: +### Docker + +The pre-built Docker image is available from the GitHub Container Registry: ```bash -docker run -e SYSDIG_MCP_TRANSPORT=streamable-http -e SYSDIG_MCP_API_HOST= -e SYSDIG_MCP_API_TOKEN= -p 8080:8080 ghcr.io/sysdiglabs/sysdig-mcp-server:latest +docker pull ghcr.io/sysdiglabs/sysdig-mcp-server:latest ``` -### Go +Configure your client with: + +```json +{ + "mcpServers": { + "sysdig-mcp-server": { + "command": "docker", + "args": [ + "run", + "-i", + "--rm", + "-e", + "SYSDIG_MCP_API_HOST", + "-e", + "SYSDIG_MCP_TRANSPORT", + "-e", + "SYSDIG_MCP_API_TOKEN", + "ghcr.io/sysdiglabs/sysdig-mcp-server:latest" + ], + "env": { + "SYSDIG_MCP_API_HOST": "", + "SYSDIG_MCP_API_TOKEN": "", + "SYSDIG_MCP_TRANSPORT": "stdio" + } + } + } +} +``` + +For remote transports, deploy the container as a service with the appropriate environment variables (see [Configuration](#configuration)). -You can run the server directly using Go without cloning the repository: +### Binary + +Download the latest pre-built binary for your platform from [GitHub Releases](https://github.com/sysdiglabs/sysdig-mcp-server/releases/latest), extract it, and place it somewhere in your `PATH` (e.g., `/usr/local/bin`): ```bash -go run github.com/sysdiglabs/sysdig-mcp-server/cmd/server@latest +# macOS (Apple Silicon) +curl -L https://github.com/sysdiglabs/sysdig-mcp-server/releases/latest/download/sysdig-mcp-server_darwin-arm64.tar.gz | tar xz + +# macOS (Intel) +curl -L https://github.com/sysdiglabs/sysdig-mcp-server/releases/latest/download/sysdig-mcp-server_darwin-amd64.tar.gz | tar xz + +# Linux (x86_64) +curl -L https://github.com/sysdiglabs/sysdig-mcp-server/releases/latest/download/sysdig-mcp-server_linux-amd64.tar.gz | tar xz + +# Linux (arm64) +curl -L https://github.com/sysdiglabs/sysdig-mcp-server/releases/latest/download/sysdig-mcp-server_linux-arm64.tar.gz | tar xz +``` + +Windows `.zip` archives are also available on the [releases page](https://github.com/sysdiglabs/sysdig-mcp-server/releases/latest). + +Configure your client with: + +```json +{ + "mcpServers": { + "sysdig-mcp-server": { + "command": "sysdig-mcp-server", + "env": { + "SYSDIG_MCP_API_HOST": "", + "SYSDIG_MCP_API_TOKEN": "", + "SYSDIG_MCP_TRANSPORT": "stdio" + } + } + } +} ``` -By default, the server will run using the `stdio` transport. To use the `streamable-http` or `sse` transports, set the `SYSDIG_MCP_TRANSPORT` environment variable: +Or using the CLI: ```bash -SYSDIG_MCP_TRANSPORT=streamable-http go run github.com/sysdiglabs/sysdig-mcp-server/cmd/server@latest +# Claude Code +claude mcp add --transport stdio \ + -e SYSDIG_MCP_API_HOST= \ + -e SYSDIG_MCP_API_TOKEN= \ + -e SYSDIG_MCP_TRANSPORT=stdio \ + -- sysdig-mcp-server sysdig-mcp-server + +# Gemini CLI +gemini mcp add -t stdio \ + -e SYSDIG_MCP_API_HOST= \ + -e SYSDIG_MCP_API_TOKEN= \ + -e SYSDIG_MCP_TRANSPORT=stdio \ + sysdig-mcp-server sysdig-mcp-server + +# Codex CLI +codex mcp add \ + --env SYSDIG_MCP_API_HOST= \ + --env SYSDIG_MCP_API_TOKEN= \ + --env SYSDIG_MCP_TRANSPORT=stdio \ + -- sysdig-mcp-server sysdig-mcp-server ``` ### Kubernetes -You can deploy the MCP server to a Kubernetes cluster and connect to it remotely from clients like Claude Desktop. +Deploy the MCP server to a Kubernetes cluster as a remote service. MCP clients like Claude Desktop will connect to it via URL. **1. Create a Secret with your Sysdig credentials:** @@ -418,98 +535,41 @@ For example, if you are running the server locally on port 8080 with the default ### Claude Desktop App -For the Claude Desktop app, you can manually configure the MCP server by editing the `claude_desktop_config.json` file. - -1. **Open the configuration file**: - - Go to **Settings > Developer** in the Claude Desktop app. - - Click on **Edit Config** to open the `claude_desktop_config.json` file. - -2. **Add the MCP server configuration**: - - **Option A: Using Docker (Recommended)** - - ```json - { - "mcpServers": { - "sysdig-mcp-server": { - "command": "docker", - "args": [ - "run", - "-i", - "--rm", - "-e", - "SYSDIG_MCP_API_HOST", - "-e", - "SYSDIG_MCP_TRANSPORT", - "-e", - "SYSDIG_MCP_API_TOKEN", - "ghcr.io/sysdiglabs/sysdig-mcp-server:latest" - ], - "env": { - "SYSDIG_MCP_API_HOST": "", - "SYSDIG_MCP_API_TOKEN": "", - "SYSDIG_MCP_TRANSPORT": "stdio" - } - } - } - } - ``` - - **Option B: Using Go** - - ```json - { - "mcpServers": { - "sysdig-mcp-server": { - "command": "go", - "args": [ - "run", - "github.com/sysdiglabs/sysdig-mcp-server/cmd/server@latest" - ], - "env": { - "SYSDIG_MCP_API_HOST": "", - "SYSDIG_MCP_API_TOKEN": "", - "SYSDIG_MCP_TRANSPORT": "stdio" - } - } - } - } - ``` - - **Option C: Connecting to a Remote Server** - - If the MCP server is deployed remotely (e.g., in a [Kubernetes cluster](#kubernetes)), you can connect to it using [`mcp-remote`](https://www.npmjs.com/package/mcp-remote). This requires [Node.js](https://nodejs.org/) (v18+) installed on your machine. - - ```json - { - "mcpServers": { - "sysdig-mcp-server": { - "command": "npx", - "args": [ - "-y", - "mcp-remote", - "http://:/sysdig-mcp-server", - "--allow-http" - ] - } - } +For the Claude Desktop app, configure the MCP server by editing the `claude_desktop_config.json` file: + +1. Go to **Settings > Developer** in the Claude Desktop app. +2. Click on **Edit Config** to open the `claude_desktop_config.json` file. +3. Add the JSON configuration from the [Server Setup](#server-setup) section that matches your installation method (Go, Docker, or Binary). +4. Replace `` with your Sysdig Secure host URL and `` with your API token. +5. Save the file and restart the Claude Desktop app. + +**Connecting to a Remote Server:** + +If the MCP server is deployed remotely (e.g., in a [Kubernetes cluster](#kubernetes)), you can connect to it using [`mcp-remote`](https://www.npmjs.com/package/mcp-remote). This requires [Node.js](https://nodejs.org/) (v18+) installed on your machine. + +```json +{ + "mcpServers": { + "sysdig-mcp-server": { + "command": "npx", + "args": [ + "-y", + "mcp-remote", + "http://:/sysdig-mcp-server", + "--allow-http" + ] } - ``` - - > **Note:** The `--allow-http` flag is required when connecting over plain HTTP. If your server is behind HTTPS (e.g., via an Ingress with TLS), you can omit it. No authentication headers or tokens are needed in the client configuration when the server has `SYSDIG_MCP_API_HOST` and `SYSDIG_MCP_API_TOKEN` set as environment variables. - -3. **Replace the placeholders**: - - Replace `` with your Sysdig Secure host URL. - - Replace `` with your Sysdig Secure API token. - - Replace `:` with the address of your remote MCP server (Option C only). + } +} +``` -4. **Save the file** and restart the Claude Desktop app for the changes to take effect. +> **Note:** The `--allow-http` flag is required when connecting over plain HTTP. If your server is behind HTTPS (e.g., via an Ingress with TLS), you can omit it. No authentication headers or tokens are needed in the client configuration when the server has `SYSDIG_MCP_API_HOST` and `SYSDIG_MCP_API_TOKEN` set as environment variables. ### MCP Inspector -1. Run the [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) locally -2. Select the transport type and have the Sysdig MCP server running accordingly. -3. Pass the Authorization header if using "streamable-http" or the SYSDIG_SECURE_API_TOKEN env var if using "stdio" +1. Run the [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) locally. +2. Select the transport type and configure the connection to the Sysdig MCP server. +3. Pass the Authorization header if using `streamable-http` or the `SYSDIG_SECURE_API_TOKEN` env var if using `stdio`. ![mcp-inspector](./docs/assets/mcp-inspector.png) From 52daedeced0b5ed3a73710a0adf782638e018df0 Mon Sep 17 00:00:00 2001 From: Fede Barcelona Date: Thu, 26 Mar 2026 12:49:06 +0100 Subject: [PATCH 2/2] docs: deduplicate Docker config snippet and fix env var name in README --- README.md | 31 ++----------------------------- 1 file changed, 2 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index e1ba208..fc667ed 100644 --- a/README.md +++ b/README.md @@ -39,39 +39,12 @@ Get up and running with the Sysdig MCP Server quickly using our pre-built Docker 2. **Configure your MCP client**: - Add the following configuration to your MCP client (e.g., Claude Desktop's `claude_desktop_config.json`). The client will automatically pull the Docker image and start the server. You can apply this configuration to any other client that supports MCP (For more details, see the [Client Configuration](#client-configuration) section). + Add the server configuration to your MCP client (e.g., Claude Desktop's `claude_desktop_config.json`). Choose your preferred installation method from the [Server Setup](#server-setup) section. The [Docker](#docker) method is the easiest to get started with since it requires no local toolchain. Substitute the following placeholders with your actual values: - ``: The hostname of your Sysdig Secure instance (e.g., `https://us2.app.sysdig.com` or `https://eu1.app.sysdig.com`) - ``: Your Sysdig Secure API token - ```json - { - "mcpServers": { - "sysdig-mcp-server": { - "command": "docker", - "args": [ - "run", - "-i", - "--rm", - "-e", - "SYSDIG_MCP_API_HOST", - "-e", - "SYSDIG_MCP_TRANSPORT", - "-e", - "SYSDIG_MCP_API_TOKEN", - "ghcr.io/sysdiglabs/sysdig-mcp-server:latest" - ], - "env": { - "SYSDIG_MCP_API_HOST": "", - "SYSDIG_MCP_API_TOKEN": "", - "SYSDIG_MCP_TRANSPORT": "stdio" - } - } - } - } - ``` - ## Available Tools The server dynamically filters the available tools based on the permissions associated with the API token used for the request. If the token lacks the required permissions for a tool, that tool will not be listed. @@ -569,7 +542,7 @@ If the MCP server is deployed remotely (e.g., in a [Kubernetes cluster](#kuberne 1. Run the [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) locally. 2. Select the transport type and configure the connection to the Sysdig MCP server. -3. Pass the Authorization header if using `streamable-http` or the `SYSDIG_SECURE_API_TOKEN` env var if using `stdio`. +3. Pass the Authorization header if using `streamable-http` or the `SYSDIG_MCP_API_TOKEN` env var if using `stdio`. ![mcp-inspector](./docs/assets/mcp-inspector.png)