Skip to content

sysdiglabs/sysdig-mcp-server

BranchesTags
 
 

Repository files navigation

MCP Server

Image Build Image Scanning Image Test
Image Build Image Scanning Image Test

Table of contents

Description

This is an implementation of an MCP (Model Context Protocol) Server to allow different LLMs to query information from Sysdig Secure platform. It is still in early development and not yet ready for production use. New endpoints and functionalities will be added over time. The goal is to provide a simple and easy-to-use interface for querying information from Sysdig Secure platform using LLMs.

Quickstart Guide

Get up and running with the Sysdig MCP Server quickly using our pre-built Docker image.

  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 Secure platform (See the Configuration section for more details).

  2. Pull the image:

    Pull the latest Sysdig MCP Server image from the GitHub Container Registry:

    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 section).

    Substitute the following placeholders with your actual values:

    • <your_sysdig_host>: 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>: Your Sysdig Secure API token
      {
    "mcpServers": {
      "sysdig-mcp-server": {
        "command": "docker",
        "args": [
          "run",
            "-i",
            "--rm",
            "-e",
            "SYSDIG_MCP_API_HOST",
            "-e",
            "SYSDIG_MCP_TRANSPORT",
            "-e",
            "SYSDIG_MCP_API_SECURE_TOKEN",
            "ghcr.io/sysdiglabs/sysdig-mcp-server:latest"
        ],
        "env": {
          "SYSDIG_MCP_API_HOST": "<your_sysdig_host>",
          "SYSDIG_MCP_API_SECURE_TOKEN": "<your_sysdig_secure_api_token>",
          "SYSDIG_MCP_TRANSPORT": "stdio"
        }
      }
    }
  }

You can find a mcp.json file in the root of the project that you can tweak and add to your client.

Available Tools

GA Tools

Events Feed
Tool Name Description Sample Prompt
get_event_info Retrieve detailed information for a specific security event by its ID "Get full details for event ID 123abc"
list_runtime_events List runtime security events with optional filters "Show me high severity events from the last 2 hours in cluster1"
get_event_process_tree Retrieve the process tree for a specific event (if available) "Get the process tree for event ID abc123"
Inventory
Tool Name Description Sample Prompt
list_resources List inventory resources using filters (e.g., platform or category) "List all exposed IAM resources in AWS"
Sysdig Sysql
Tool Name Description Sample Prompt
sysdig_sysql_execute_query Execute a Sysdig Sysql query against the Sysdig API and return the results "MATCH CloudResource AFFECTED_BY Vulnerability WHERE Vulnerability.severity = 'Critical' RETURN DISTINCT CloudResource, Vulnerability LIMIT 50;"
Sysdig CLI scanner
Tool Name Description Sample Prompt
run_sysdig_cli_scanner Run the Sysdig CLI Scanner to analyze a container image or IaC files for vulnerabilities and posture and misconfigurations. "Scan this image ubuntu:latest for vulnerabilities"

Only in stdio transport mode. Make sure to have in your local $PATH the sysdig-cli-scanner binary; more info in the docs

Beta Tools

Inventory
Tool Name Description Sample Prompt
get_resource Get detailed information about an inventory resource by its hash "Get inventory details for hash abc123"
Vulnerability Management
Tool Name Description Sample Prompt
list_runtime_vulnerabilities List runtime vulnerability scan results with filtering "List running vulnerabilities in cluster1 sorted by severity"
list_accepted_risks List all accepted vulnerability risks "Show me all accepted risks related to nginx containers"
get_accepted_risk Retrieve a specific accepted risk by ID "Get details for accepted risk id abc123"
list_registry_scan_results List scan results for container registries "List failed scans from harbor registry"
get_vulnerability_policy_by_id Get a specific vulnerability policy by ID "Show policy ID 42"
list_vulnerability_policies List all vulnerability policies "List all vulnerability policies for pipeline stage"
list_pipeline_scan_results List CI pipeline scan results "Show me pipeline scans that failed for ubuntu images"
get_scan_result Retrieve detailed scan results by scan ID "Get results for scan ID 456def"
Sysdig Sysql
Tool Name Description Sample Prompt
sysdig_sysql_sage_query Get a Sysdig Sysql query through the help of Sysdig Sage based on a natural language question. "List top 10 pods by memory usage in the last hour"

Important

In order to enable the Beta tools, set the SYSDIG_MCP_ENABLE_BETA_TOOLS to true. Use the beta tools under your own responability since some Sysdig APIs are still on beta.

Available Resources

  • Sysdig Secure Vulnerability Management Overview:
    • VM documentation based on the following url
  • Sysdig Filter Query Language Instructions:
    • Sysdig Filter Query Language for different API endpoint filters

Requirements

UV Setup

You can use uv as a drop-in replacement for pip to create the virtual environment and install dependencies.

If you don't have uv installed, you can install it following the instructions that you can find on the README of the project.

If you want to develop, set up the environment using:

uv venv
source .venv/bin/activate

This will create a virtual environment using uv and install the required dependencies.

Configuration

The following environment variables are required for configuring the Sysdig SDK:

  • SYSDIG_MCP_API_HOST: The URL of your Sysdig Secure instance (e.g., https://us2.app.sysdig.com).
  • SYSDIG_MCP_API_SECURE_TOKEN: Your Sysdig Secure API token.

You can also set the following variables to override the default configuration:

  • SYSDIG_MCP_TRANSPORT: The transport protocol for the MCP Server (stdio, streamable-http, sse). Defaults to: stdio.
  • SYSDIG_MCP_MOUNT_PATH: The URL prefix for the Streamable-http/sse deployment. Defaults to: /sysdig-mcp-server
  • SYSDIG_MCP_LOGLEVEL: Log Level of the application (DEBUG, INFO, WARNING, ERROR). Defaults to: ERROR
  • SYSDIG_MCP_LISTENING_PORT: The port for the server when it is deployed using remote protocols (steamable-http, sse). Defaults to: 8080
  • SYSDIG_MCP_LISTENING_HOST: The host for the server when it is deployed using remote protocols (steamable-http, sse). Defaults to: localhost

You can find your API token in the Sysdig Secure UI under Settings > Sysdig Secure API. Make sure to copy the token as it will not be shown again.

API_TOKEN_CONFIG API_TOKEN_SETTINGS

You can set these variables in your shell or in a .env file.

Running the Server

You can run the MCP server using either Docker, uv or install it in your K8s cluster with helm.

Docker

To run the server using Docker, you first need to build the image:

docker build -t sysdig-mcp-server .

Then, you can run the container, making sure to pass the required environment variables:

docker run -e SYSDIG_HOST=<your_sysdig_host> -e SYSDIG_SECURE_TOKEN=<your_sysdig_secure_api_token> -p 8080:8080 sysdig-mcp-server

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 to streamable-http or sse:

docker run -e MCP_TRANSPORT=streamable-http -e SYSDIG_HOST=<your_sysdig_host> -e SYSDIG_SECURE_TOKEN=<your_sysdig_secure_api_token> -p 8080:8080 sysdig-mcp-server

UV

To run the server using uv, first set up the environment as described in the UV Setup section. Then, run the main.py script:

uv run main.py

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 to streamable-http or sse:

MCP_TRANSPORT=streamable-http uv run main.py

Client Configuration

To use the MCP server with a client like Claude or Cursor, you need to provide the server's URL and authentication details.

Server Authentication

If you want to secure your MCP server with Oauth you can configure some environments variables to enable it. In this case we are going to use GitHub as the example provider but it also works for Google Oauth and the rest of the providers listed in the authentication integrations list.

In your .env file you will need to set the FASTMCP_SERVER_AUTH_... appropriate env vars depending on your Oauth provider.

export SYSDIG_MCP_...
# Oauth config vars
export FASTMCP_SERVER_AUTH="fastmcp.server.auth.providers.github.GitHubProvider"
export FASTMCP_SERVER_AUTH_GITHUB_CLIENT_ID="bv2..."
export FASTMCP_SERVER_AUTH_GITHUB_CLIENT_SECRET="ase2..."
export FASTMCP_SERVER_AUTH_GITHUB_BASE_URL="http://localhost:8080"
export FASTMCP_SERVER_AUTH_GITHUB_REDIRECT_PATH="/auth/callback"

Then if your MCP client supports the Oauth authentication method you will be able to connect to it. Here is an example client you can use to test it:

from fastmcp import Client
from fastmcp.client.transports import StreamableHttpTransport
import asyncio
import os

async def main():
    async with Client(
        transport=StreamableHttpTransport(
            url="http://localhost:8080/sysdig-mcp-server/mcp",
            headers={"X-Sysdig-Token": f"Bearer {os.getenv("SYSDIG_MCP_API_SECURE_TOKEN")}"}
            ),
            auth="oauth"
        ) as client:
        print("✓ Authenticated with Oauth!")
        tool_name = "list_runtime_events"
        result = await client.call_tool(tool_name)
        print(f"{tool_name} tool completed with status code: {result.structured_content.get('status_code')} with a total of: {result.data.get('results',{}).get('page', {}).get('total', 0)} runtime events.")

if __name__ == "__main__":
    asyncio.run(main())

You can find the above client code here tests/mcp_test_client.py

More information as an example of the Github Oauth config here

Sysdig API authentication

When using the sse or streamable-http transport, the server requires the X-Sysdig-Token header in the HTTP request (i.e SYSDIG_SECURE_API_TOKEN) to authenticate to the Sysdig API. This is different than the MCP server own authentication methods.

Additionally, you can specify the Sysdig Secure host by providing the X-Sysdig-Host header. If this header is not present, the server will use the value from the env variable SYSDIG_MCP_API_HOST.

Example headers:

X-Sysdig-Token: Bearer <your_sysdig_secure_api_token>
X-Sysdig-Host: <your_sysdig_host>

URL

If you are running the server with the sse or streamable-http transport, the URL will be http://<host>:<port>/sysdig-mcp-server/mcp. You can configure the SYSDIG_MCP_MOUNT_PATH env variable to configure the mountpoint path, default to /sysdig-mcp-server

For example, if you are running the server locally on port 8080, the URL will be http://localhost:8080/sysdig-mcp-server/mcp.

Claude Desktop App

For the Claude Desktop app, you can manually configure the MCP server by editing the claude_desktop_config.json file. This is useful for running the server locally with the stdio transport.

  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:

    • Add the following JSON object to the mcpServers section of the file.
    {
  "mcpServers": {
    "sysdig-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "<path_to_your_sysdig_mcp_server_directory>",
        "run",
        "main.py"
        ],
      "env": {
        "SYSDIG_MCP_API_HOST": "<your_sysdig_host>",
        "SYSDIG_MCP_API_SECURE_TOKEN": "<your_sysdig_secure_api_token>",
        "SYSDIG_MCP_TRANSPORT": "stdio"
      }
    }
  }
}

    Or, alternatively, if you want to use docker, you can add the following configuration:

    {
  "mcpServers": {
    "sysdig-mcp-server": {
      "command": "docker",
      "args": [
         "run",
          "-i",
          "--rm",
          "-e",
          "SYSDIG_MCP_API_HOST",
          "-e",
          "SYSDIG_MCP_TRANSPORT",
          "-e",
          "SYSDIG_MCP_API_SECURE_TOKEN",
          "ghcr.io/sysdiglabs/sysdig-mcp-server"
      ],
      "env": {
        "SYSDIG_MCP_API_HOST": "<your_sysdig_host>",
        "SYSDIG_MCP_API_SECURE_TOKEN": "<your_sysdig_secure_api_token>",
        "SYSDIG_MCP_TRANSPORT": "stdio"
      }
    }
  }
}

  3. Replace the placeholders:

    • Replace <your_sysdig_host> with your Sysdig Secure host URL.
    • Replace <your_sysdig_secure_api_token> with your Sysdig Secure API token.
    • Replace <path_to_your_sysdig_mcp_server_directory> with the absolute path to the sysdig-mcp-server directory.

  4. Save the file and restart the Claude Desktop app for the changes to take effect.

MCP Inspector

  1. Run the MCP Inspector locally
  2. Select the transport type and have the Sysdig MCP server running accordingly.
  3. Pass the X-Sysdig-Token authorization header if using "streamable-http" or the SYSDIG_MCP_API_SECURE_TOKEN env var if using "stdio"

mcp-inspector

Goose Agent

  1. In your terminal run goose configure and follow the steps to add the extension (more info on the goose docs), again could be using docker or uv as shown in the above examples.
  2. Your ~/.config/goose/config.yaml config file should have one config like this one, check out the env vars
extensions:
...
  sysdig-mcp-server:
    args: []
    bundled: null
    cmd: sysdig-mcp-server
    description: Sysdig MCP server
    enabled: true
    env_keys:
    - SYSDIG_MCP_TRANSPORT
    - SYSDIG_MCP_API_HOST
    - SYSDIG_MCP_API_SECURE_TOKEN
    envs:
      SYSDIG_MCP_TRANSPORT: stdio
    name: sysdig-mcp-server
    timeout: 300
    type: stdio
  1. Have fun

goose_results

About

Sysdig MCP Server

Topics

ai mcp

Resources

Readme

License

Apache-2.0 license
Activity
Custom properties

Stars

4 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 6

v0.3.1 Latest
Oct 3, 2025
+ 5 releases

Packages

 
 
 

Contributors 4

  •  
  •  
  •  
  •  

Languages