MCP server for WithSecure Elements

An MCP (Model Context Protocol) server to connect AI agents to WithSecure Elements for automated security analysis and threat hunting.

Features

• Incidents (BCDs) : Access and manage Broad Context Detections (BCDs)
• Security Events : Retrieve and analyze security events
• Organizations : Manage organization information
• Devices : Monitor and perform actions on devices
• Response Actions : Execute security response actions on devices
• Software Updates : Install software updates and manage missing updates on devices
• OAuth2 Authentication : Secure integration with WithSecure Elements API

Prerequisites

• Python 3.10 or higher
• WithSecure Elements API credentials (Client ID, Client Secret)
• Organization ID (optional, can be retrieved via API)
• Docker (for containerized deployment)

Installation

Using Docker (Recommended)

The easiest way to run the WithSecure Elements MCP Server is using Docker:

# Pull the latest image
docker pull ghcr.io/fspms/wselements-mcp:latest

# Run with environment variables
docker run --rm \
  -e WITHSECURE_CLIENT_ID=your_client_id \
  -e WITHSECURE_CLIENT_SECRET=your_client_secret \
  -e WITHSECURE_BASE_URL=https://api.connect.withsecure.com \
  -e WITHSECURE_ORGANIZATION_ID=your_organization_id \
  -p 8000:8000 \
  ghcr.io/fspms/wselements-mcp:latest \
  --transport streamable-http --host 0.0.0.0 --port 8000

Using Docker Compose

Create a docker-compose.yml file:

version: '3.8'

services:
  withsecure-elements-mcp:
    image: ghcr.io/fspms/wselements-mcp:latest
    container_name: withsecure-elements-mcp
    ports:
      - "8000:8000"
    environment:
      - WITHSECURE_CLIENT_ID=your_client_id
      - WITHSECURE_CLIENT_SECRET=your_client_secret
      - WITHSECURE_BASE_URL=https://api.connect.withsecure.com
      - WITHSECURE_ORGANIZATION_ID=your_organization_id
      - MCP_DEBUG=false
      - MCP_LOG_LEVEL=INFO
      - WITHSECURE_MCP_MODULES=incidents,events,organizations,devices,response_actions,software_updates
    command: ["--transport", "streamable-http", "--host", "0.0.0.0", "--port", "8000"]
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

Then run:

docker-compose up -d

Install using uv

uv tool install withsecure-elements-mcp

Install using pip

pip install withsecure-elements-mcp

Configuration

Environment Variables

Create a .env file with the following information:

# WithSecure Elements API Configuration
WITHSECURE_CLIENT_ID=your_client_id
WITHSECURE_CLIENT_SECRET=your_client_secret
WITHSECURE_BASE_URL=https://api.connect.withsecure.com
WITHSECURE_ORGANIZATION_ID=your_organization_id
WITHSECURE_API_SCOPE=read_only

# MCP Server Configuration
MCP_DEBUG=false
MCP_LOG_LEVEL=INFO
WITHSECURE_MCP_MODULES=incidents,events,organizations,devices,response_actions,software_updates

Available Environments

• Production : https://api.connect.withsecure.com
• Staging : https://api.connect-stg.fsapi.com
• CI : https://api.connect-ci.fsapi.com

API Scope Configuration

The WITHSECURE_API_SCOPE environment variable controls the level of access to the WithSecure Elements API:

• read_only : Read-only access only (scope: connect.api.read) — default

  • Allows data retrieval but not modification (least privilege)
  • Resolves the "Scope not allowed for the client" error for read-only clients

• read_write : Full read and write access (scopes: connect.api.read connect.api.write)

  • Required for write/response actions (isolate, scan, restart, install updates, response actions)
  • Use only if your WithSecure client has full access

Example configuration for a read-only client:

WITHSECURE_API_SCOPE=read_only

Module Configuration

The server supports 6 main modules that can be enabled/disabled:

• incidents : Broad Context Detections (BCDs) management
• events : Security events analysis and monitoring
• organizations : Organization information and settings
• devices : Device monitoring and management
• response_actions : Security response actions execution
• software_updates : Software updates installation, management, and scanning

Usage

Command Line

Run the server with default settings (stdio transport):

withsecure-elements-mcp

Run with SSE transport:

withsecure-elements-mcp --transport sse

Run with streamable-http transport:

withsecure-elements-mcp --transport streamable-http

Run with streamable-http transport on custom port:

withsecure-elements-mcp --transport streamable-http --host 0.0.0.0 --port 8080

Module Configuration

The WithSecure Elements MCP Server supports multiple ways to specify which modules to enable:

1. Command Line Arguments (highest priority)

# Enable specific modules
withsecure-elements-mcp --modules incidents,events,organizations,devices,response_actions

# Enable only one module
withsecure-elements-mcp --modules incidents

2. Environment Variable (fallback)

# Export environment variable
export WITHSECURE_MCP_MODULES=incidents,events,organizations,devices,response_actions,software_updates
withsecure-elements-mcp

3. Default Behavior (all modules)

If no modules are specified, all available modules are enabled by default.

As a Library

from withsecure_elements_mcp.server import WithSecureElementsMCPServer

# Create and run the server
server = WithSecureElementsMCPServer(
    base_url="https://api.connect.withsecure.com",
    debug=True,
    enabled_modules=["incidents", "events", "organizations", "devices", "response_actions", "software_updates"]
)

# Run with stdio transport (default)
server.run()

# Or run with SSE transport
server.run("sse")

# Or run with streamable-http transport
server.run("streamable-http", host="0.0.0.0", port=8080)

Editor/Assistant Integration

MCP Configuration

Using Docker

{
  "mcpServers": {
    "withsecure-elements-mcp": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-p",
        "8000:8000",
        "-e",
        "WITHSECURE_CLIENT_ID=your_client_id",
        "-e",
        "WITHSECURE_CLIENT_SECRET=your_client_secret",
        "-e",
        "WITHSECURE_BASE_URL=https://api.connect.withsecure.com",
        "-e",
        "WITHSECURE_ORGANIZATION_ID=your_organization_id",
        "-e",
        "MCP_DEBUG=false",
        "-e",
        "MCP_LOG_LEVEL=INFO",
        "-e",
        "WITHSECURE_MCP_MODULES=incidents,events,organizations,devices,response_actions,software_updates",
        "ghcr.io/fspms/wselements-mcp:latest",
        "--transport",
        "streamable-http",
        "--host",
        "0.0.0.0",
        "--port",
        "8000"
      ]
    }
  }
}

Using HTTP Transport (when server is already running)

{
  "mcpServers": {
    "withsecure-elements-mcp": {
      "url": "http://localhost:8000",
      "transport": "http"
    }
  }
}

Using uvx (for local development)

{
  "mcpServers": {
    "withsecure-elements-mcp": {
      "command": "uvx",
      "args": [
        "--env-file",
        "/path/to/.env",
        "withsecure-elements-mcp"
      ]
    }
  }
}

With Module Selection

{
  "mcpServers": {
    "withsecure-elements-mcp": {
      "command": "uvx",
      "args": [
        "--env-file",
        "/path/to/.env",
        "withsecure-elements-mcp",
        "--modules",
        "incidents,events,response_actions"
      ]
    }
  }
}

Available Modules

Incidents (BCDs)

• List incidents
• Retrieve incident details
• Archive/unarchive incidents
• Update incident status

Security Events

• List security events
• Retrieve event details
• Filter events by criteria

Organizations

• Retrieve organization information
• List accessible organizations

Devices

• List devices
• Retrieve device details
• Perform actions on devices
• Send full status: Request complete status information from devices
  • Force devices to send their complete status to the server
  • Supports 1-5 devices per operation
• Restart system: Restart devices (Windows computers only)
  • Optional message to display before restart
  • Supports 1-5 devices per operation

Response Actions

• List response actions responses
• Create response actions on devices
• Execute security actions including:
  • Process Management: Kill threads, kill processes, collect process memory
  • Memory Analysis: Full memory dumps, process memory collection
  • File Operations: Collect files, delete files, quarantine/unquarantine files
  • System Control: Run commands, restart/shutdown devices
  • Network Isolation: Isolate devices from network, release from isolation
  • Agent Management: Restart security agents

Software Updates

• Install software updates: Install specific updates or updates by severity on devices
  • Install specific bulletin IDs
  • Install updates by severity (critical, important, everything)
  • Force close applications during upgrade
• Get missing updates: Retrieve list of missing software updates for a device
  • Filter by severity (critical, important, moderate, low, unclassified)
  • Filter by category (security, nonSecurity, servicePack, securityTool, none)
  • Limit results (1-200)
• Scan for updates: Trigger manual scan for software updates on devices
  • Force devices to check for available updates
  • Supports 1-5 devices per operation

Examples

The project includes several usage examples in the examples/ directory:

• basic_usage.py : Basic server setup and configuration
• sse_usage.py : Server-Sent Events transport example
• streamable_http_usage.py : HTTP transport example

Quick Start Example

import asyncio
from withsecure_elements_mcp.server import WithSecureElementsMCPServer

async def main():
    # Create server with all modules enabled
    server = WithSecureElementsMCPServer(
        debug=True,
        enabled_modules=["incidents", "events", "organizations", "devices", "response_actions", "software_updates"]
    )
    
    # Run with stdio transport
    await server.run("stdio")

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

Development

Development Environment Setup

# Clone the repository
git clone https://github.com/withsecure/elements-mcp.git
cd elements-mcp

# Create virtual environment and install dependencies
uv sync --all-extras

# Activate virtual environment
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Or use the provided startup scripts
# On Windows:
.\scripts\start.ps1

# On Linux/macOS:
./scripts/start.sh

Running Tests

# Run all tests
pytest

# Run tests with detailed output
pytest -v -s

License

This project is licensed under the MIT License - see the LICENSE file for details.

Security Considerations

• API Credentials : Store your WithSecure API credentials securely using environment variables or secret management systems
• Network Security : Use HTTPS in production environments
• Access Control : Limit access to the MCP server to authorized users only
• Logging : Monitor and audit all API calls and response actions
• Response Actions : Use response actions carefully as they can affect system operations

Troubleshooting

Common Issues

1. Authentication Errors : Verify your API credentials and organization ID
2. Module Not Found : Ensure the module is included in WITHSECURE_MCP_MODULES
3. Connection Issues : Check network connectivity and API endpoint URLs
4. Permission Errors : Verify your API credentials have the necessary permissions

Debug Mode

Enable debug mode for detailed logging:

# Environment variable
export MCP_DEBUG=true

# Command line
withsecure-elements-mcp --debug

Support

This is a community-driven open source project. For more information, see our SUPPORT file.

About

Connect AI agents to WithSecure Elements for automated security analysis and threat hunting.