Steadybit MCP Server Interaction Guide

Overview

The Steadybit MCP (Model Context Protocol) server is a lightweight HTTP service that acts as a bridge between your tooling and the Steadybit chaos engineering platform. It provides a consistent interface for creating, running, and monitoring experiments programmatically, enabling automation in CI/CD pipelines, monitoring integrations, and scripted test scenarios. Running an MCP server locally or alongside your infrastructure makes it easier to orchestrate experiments and collect results in a repeatable way.

This server is useful when you want to automate chaos experiments (for example, in a nightly pipeline), integrate Steadybit actions into monitoring alerts, or build custom tooling around experiment lifecycle management. It exposes a simple API and supports common operational features such as authentication, configuration via environment variables, and containerized deployment for easy integration into existing workflows.

Features

• HTTP API for controlling experiments and fetching results
• Simple configuration via environment variables or files
• Container-ready: runs as a standalone Docker image
• Lightweight, suitable for embedding in CI/CD jobs or local development
• Hooks for registering external tools or agents used in experiments
• Built-in logging and status endpoints for health checks
• Example client requests for common automation tasks

Installation / Configuration

Quick start with Docker (example):

# Run the MCP server on port 8080
docker run --rm -p 8080:8080 ghcr.io/steadybit/mcp:latest

From source (example using Maven):

git clone https://github.com/steadybit/mcp.git
cd mcp
./mvnw package
java -jar target/mcp-server.jar

Environment variables

Example setting environment variables and running:

export MCP_PORT=8080
export MCP_API_KEY="s3cr3t"
docker run --rm -p ${MCP_PORT}:${MCP_PORT} \
  -e MCP_PORT=${MCP_PORT} \
  -e MCP_API_KEY=${MCP_API_KEY} \
  ghcr.io/steadybit/mcp:latest

Configuration file (optional)

• The server can be configured through a YAML or JSON config file if supported in your build. Place the config at /etc/mcp/config.yaml or mount it into the container with -v.

Available Resources

• Repository: https://github.com/steadybit/mcp
• Example Docker image: ghcr.io/steadybit/mcp (check the repository for exact tags)
• Health and status endpoints: /health, /metrics (for orchestration tools)
• API documentation: Look for an OpenAPI/Swagger file in the repo for full request/response schemas
• Example clients: sample curl commands and CI snippets are included below and in the repo examples folder

Use Cases

1. Automate regression experiments in CI

   • Trigger an experiment as part of a pull request check to ensure resilience changes do not break system behavior.

   Example GitHub Actions step:

   - name: Trigger Steadybit experiment
     env:
       MCP_URL: http://mcp:8080
       MCP_API_KEY: ${{ secrets.MCP_API_KEY }}
     run: |
       curl -X POST "${MCP_URL}/v1/experiments" \
         -H "Authorization: Bearer ${MCP_API_KEY}" \
         -H "Content-Type: application/json" \
         -d '{"target":"my-service","action":"latency-injection","duration":60}'
   

2. Integrate experiments with alerting systems

   • Automatically run an investigation experiment when an alert fires to validate fallback paths.

   Example alert-to-experiment flow:

   • Alerting system calls MCP /v1/experiments with alert context
   • MCP triggers experiment and returns an experiment id
   • Monitoring system polls /v1/experiments/{id}/results

3. Continuous resilience testing

   • Schedule regular chaos tests against staging to detect regressions early and collect trend data.

4. Local development and validation

   • Developers run a local MCP server to iterate on experiment definitions and validate behavior before committing changes.

Example API interactions

Register a tool/agent (example):

curl -X POST "http://localhost:8080/v1/tools" \
  -H "Authorization: Bearer s3cr3t" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"k8s-agent",
    "type":"kubernetes",
    "metadata":{"namespace":"staging"}
  }'

Start an experiment (example):

curl -X POST "http://localhost:8080/v1/experiments" \
  -H "Authorization: Bearer s3cr3t" \
  -H "Content-Type: application/json" \
  -d '{
    "target":"service-a",
    "scenario":"network-latency",
    "parameters":{"latency_ms":200,"duration_s":120}
  }'

Fetch experiment results:

curl -X GET "http://localhost:8080/v1/experiments/{experimentId}/results" \
  -H "Authorization: Bearer s3cr3t"

Health check

curl http://localhost:8080/health
# expected: 200 OK with JSON status

For full API schemas, advanced configuration options, and example integrations, consult the repository README and the OpenAPI/Swagger spec included in the project. The MCP server is designed to be a practical integration point enabling automated, repeatable chaos experiments in development and production workflows.