Steadybit MCP Server

What is Steadybit MCP Server about?

Enables LLM agents to query and manipulate Steadybit experiment data. It exposes a collection of tools—such as listing experiment designs, fetching executions, creating experiments from templates, and enumerating actions, environments, teams, and schedules—through the Model Context Protocol (MCP). This makes it possible for AI assistants to drive chaos engineering workflows without manual API calls.

How to use Steadybit MCP Server?

Installation

• Docker: docker build -t steadybit/mcp -f Dockerfile . then run with docker run -i --rm -e API_TOKEN -e API_URL steadybit/mcp.
• Java jar: Build with Maven (mvn clean install) and execute the generated JAR (java -jar target/mcp-*.jar).
• Native image: Install GraalVM 24.0.1, then run mvn -Pnative native:compile and execute the produced binary.

Configuration

• Set API_TOKEN (required) and optionally API_URL (default https://platform.steadybit.com/api).
• Enable optional capabilities via CAPABILITIES_ENABLED_0, e.g. CREATE_EXPERIMENT_FROM_TEMPLATE.

Running with Claude Desktop Add a server entry in Claude’s developer settings, for example:

{
  "mcpServers": {
    "steadybit": {
      "command": "docker",
      "args": ["run","-i","--rm","-e","API_TOKEN","-e","API_URL","steadybit/mcp"],
      "env": {"API_TOKEN": "<your-token>", "API_URL": "https://platform.steadybit.com/api"}
    }
  }
}

The MCP client will then communicate via STDIO with the server.

Key Features

• list-experiment-designs – retrieve designs for a specific team.
• get_experiment_design – fetch a single design by key.
• list_experiment_executions – filter executions by experiment, environment, team, state, date range, pagination.
• get_experiment_execution – obtain details of a particular execution.
• list_actions – enumerate registered actions with pagination.
• list_environments – obtain all environments.
• list_teams – retrieve all teams.
• list_experiment_schedules – view schedules, filterable by experiment or team.
• list_experiment_templates / get_experiment_template – browse and fetch template data.
• create_experiment_from_template – (optional capability) create a new experiment from a template, supporting placeholders and external IDs.

Use Cases

• AI‑driven chaos engineering: A conversational assistant can ask for the latest experiment designs, start a new experiment from a template, and monitor its progress.
• Dashboard automation: Scripts retrieve execution status across environments to feed custom monitoring dashboards.
• Team self‑service: Teams query their own designs and schedules without needing direct API access.
• Compliance reporting: Generate lists of completed experiments, filters by date or state, for audit purposes.
• Integration testing: Developers can programmatically create and tear down experiments to validate platform behavior.

FAQ

• Do I need a Steadybit account? Yes, an account and an API token (admin or team token) are required.
• Can I run the server locally? Absolutely – use the Maven build or the native binary; logs are written to steadybit-mcp.log.
• How do I enable experiment creation from templates? Set an environment variable like CAPABILITIES_ENABLED_0=CREATE_EXPERIMENT_FROM_TEMPLATE before starting the server.
• What limits pagination? pageSize defaults to 50 and caps at 100.
• Is there any console output? The server communicates via STDIO; detailed logs are stored in the log file, not printed to the console.

Steadybit MCP Server

MCP Server for Steadybit, enabling LLM tools like Claude to interact with the Steadybit platform.

Tools

1. list-experiment-designs
   • List experiment designs
   • Required inputs:
     • team (string): The team key to list experiment designs for
   • Returns: List of experiment designs with their key and name
2. get_experiment_design
   • Get an experiment design
   • Required inputs:
     • experimentKey (string): The experiment key to get
   • Returns: The experiment design
3. list_experiment_executions
   • List experiment executions
   • Optional inputs:
     • experiment (list of string): Filter by one or more experiment keys
     • environment (list of string): Filter by one or more environment names
     • team (list of string): Filter by one or more team keys
     • state (list of string): Filter by one or more result states, possible values are [CREATED, PREPARED, RUNNING, FAILED, CANCELED, COMPLETED, ERRORED]
     • from (string, ISO8601 date): Filter by creation date from
     • to (string, ISO8601 date): Filter by creation date to
     • page (number): Number of the requested page, default is 0
     • pageSize (number): Results per page, defaults to 50, maximum 100 is allowed
   • Returns: The experiment design
4. get_experiment_execution
   • Get an experiment execution
   • Required inputs:
     • executionId (number): The execution id to get
   • Returns: The experiment execution
5. list_actions
   • List of currently registered actions
   • Optional inputs:
     • page (number): Number of the requested page, default is 0
     • pageSize (number): Results per page, defaults to 50, maximum 100 is allowed
   • Returns: List of actions
6. list_environments
   • Get a list of environments
   • Returns: List of environments
7. list_teams
   • Get a list of teams
   • Returns: List of teams
8. list_experiment_schedules
   • Get a list of experiment schedules
   • Optional inputs:
     • experiment (list of string): Filter by one or more experiment keys
     • team (list of string): Filter by one or more team keys
   • Returns: List of experiment schedules
9. list_experiment_templates
   • Get a list of experiment templates (name and ids)
10. get_experiment_template
    • Get an experiment template including its design
    • Required inputs:
      • templateId (string): The id of the template to create an experiment from
11. create_experiment_from_template
    • Create an experiment from a template
    • Needs to be enabled via environment variable, for example CAPABILITIES_ENABLED_0=CREATE_EXPERIMENT_FROM_TEMPLATE
    • Required inputs:
      • templateId (string): The id of the template to create an experiment from
      • environment (string): The environment to use for the experiment
      • team (string): The team to use for the experiment
    • Optional inputs:
      • placeholders (object): A map of placeholder keys and their values.
      • externalId (string): An optional external id that can be used to update existing experiment designs.
    • Returns: The key of the created experiment or an error message if the experiment could not be created

Setup

You need to have a Steadybit account and an API token. You can create an API token in the Steadybit platform under "Settings" → "API Access Tokens". Both token types, Admin or Team are supported.

If you want to create experiments, you need a team token for the team you want to create experiments in.

Supported ENV-Variables

• API_TOKEN: The API token to use for authentication. This is required.
• API_URL: The URL of the Steadybit API. Default is https://platform.steadybit.com/api.
• CAPABILITIES_ENABLED_0,CAPABILITIES_ENABLED_1,...: A comma-separated list of additional capabilities to enable. The capabilities are:
  • CREATE_EXPERIMENT_FROM_TEMPLATE: Enables the create_experiment_from_template tool.

Usage with Claude Desktop

• Settings -> Developer -> Edit
• Add the following JSON to the file, make sure to replace <your-api-token> with your actual API token.:

  {
    "mcpServers": {
      "steadybit": {
        "command": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "-e",
          "API_TOKEN",
          "ghcr.io/steadybit/mcp:latest"
        ],
        "env": {
          "API_TOKEN": "<your-api-token>"
        }
      }
    }
  }
  

Development

Please note that there will be no logging to the console when running the MCP Server. The server uses STDIO transport to communicate with the MCP Clients. Have a look at the steadybit-mcp.log file to see the output of the server.

Local Testing

• Build the project:

  mvn clean install
  

• Test with the MCP inspector:

  • Launch the inspector:

    npx @modelcontextprotocol/inspector java -jar target/mcp-1.0.0-SNAPSHOT.jara -e API_URL=https://platform.steadybit.com/api -e API_TOKEN=123456
    

  • Logs can be found in steadybit-mcp.log located in the folder where you started the inspector.

• Use in Claude Desktop

  • Settings -> Developer -> Edit
  • Add something like below.

  {
    "mcpServers": {
      "steadybit": {
        "command": "/Users/danielreuter/.sdkman/candidates/java/current/bin/java",
        "args": [
          "-jar",
          "/Users/danielreuter/.m2/repository/com/steadybit/mcp/1.0.0-SNAPSHOT/mcp-1.0.0-SNAPSHOT.jar"
        ],
        "env": {
          "API_URL": "https://platform.steadybit.com/api",
          "API_TOKEN": "123456",  
          "LOGGING_FILE_NAME": "/Users/danielreuter/Library/Logs/Claude/steadybit-mcp-server.log"
        }
      }
    }
  }
  

  • MCP-Client-Logs can be found in ~/Library/Logs/Claude/mcp-server-steadybit.log
  • MCP-Server-Logs can be found in ~/Library/Logs/Claude/steadybit-mcp.log, depending on the LOGGING_FILE_NAME you set in the env section.

Building and testing the Docker image

• Build the image:

  docker build -t steadybit/mcp -f Dockerfile . 
  

• Create a file config.json with the following content:

  {
    "mcpServers": {
      "steadybit": {
        "command": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "-e",
          "API_TOKEN",
          "-e",
          "API_URL",
          "steadybit/mcp"
        ],
        "env": {
          "API_TOKEN": "123456",
          "API_URL":"https://platform.steadybit.com/api"
        }
      }
    }
  }
  

• Run the inspector:

  npx @modelcontextprotocol/inspector --config config.json --server steadybit
  

Building a native image

• Install GraalVM 24.0.1 with the following command using sdkman:

  sdk install java 24.0.1-graalce
  

• Use the GraalVM version:

  sdk use java 24.0.1-graalce
  

• Build the native image:

  mvn -Pnative native:compile
  

Example Usage

You can find some example prompts here.

License

This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.