HAProxy

The HAProxy MCP Server provides a standardized way for LLMs to control and monitor HAProxy through the Model Context Protocol. It connects to HAProxy’s Runtime API and optional behavior like the Stats page, enabling you to perform administration, observe status, manage backend servers, and analyze traffic using natural language interfaces.

How to use

You operate the server through an MCP client that communicates with the MCP server via the Model Context Protocol. You can enable the Runtime API over TCP4 or Unix domain sockets, and you can optionally enable the HAProxy stats page for richer metrics. Start the MCP server with the appropriate environment variables, then issue MCP commands from your LLM-backed assistant to retrieve information, adjust backend pools, or query server states. You can mix Runtime API access with Stats Page capabilities for complementary functionality.

How to install

Prerequisites you need before installing are:

• Go (to build or run from source)
• Docker (optional, for containerized deployment)
• Optional: Homebrew (for macOS users) if you prefer a package-based install.

# Install via Go (builds the MCP server from source)
go install github.com/tuannvm/haproxy-mcp-server/cmd/server@latest

# Alternatively, run a prebuilt binary (example command shown; use the latest release in your environment)
# Download the latest binary and run it with your preferred settings

# Or run via Docker (example)
docker pull ghcr.io/tuannvm/haproxy-mcp-server:latest
docker run -it --rm \
  -e HAPROXY_HOST=your-haproxy-host \
  -e HAPROXY_PORT=9999 \
  ghcr.io/tuannvm/haproxy-mcp-server:latest

Configuration

Configure the MCP server to connect to HAProxy and optionally enable the Stats page. Use either the Runtime API over TCP4, Unix sockets, or both. You can enable the stats page with its URL and timeout. The following environment variables are used to configure the server:

{
  "mcpServers": {
    "haproxy_tcp": {
      "command": "haproxy-mcp-server",
      "env": {
        "HAPROXY_HOST": "localhost",
        "HAPROXY_PORT": "9999",
        "HAPROXY_RUNTIME_MODE": "tcp4",
        "HAPROXY_RUNTIME_TIMEOUT": "10",
        "MCP_TRANSPORT": "stdio"
      }
    },
    "haproxy_unix": {
      "command": "haproxy-mcp-server",
      "env": {
        "HAPROXY_RUNTIME_MODE": "unix",
        "HAPROXY_RUNTIME_SOCKET": "/var/run/haproxy/admin.sock",
        "HAPROXY_RUNTIME_TIMEOUT": "10",
        "MCP_TRANSPORT": "stdio"
      }
    },
    "haproxy_stats": {
      "command": "haproxy-mcp-server",
      "env": {
        "HAPROXY_STATS_ENABLED": "true",
        "HAPROXY_STATS_URL": "http://localhost:8404/stats",
        "HAPROXY_STATS_TIMEOUT": "5",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

Security considerations

Ensure you use secure methods to authenticate to HAProxy’s Runtime API, restrict access to the Runtime API port when using TCP4 mode, and set proper permissions on Unix sockets. Validate all inputs to prevent injection and unauthorized actions.

Development

You can run and test locally by building the MCP server, then starting it with appropriate environment variables that point to your HAProxy instance. Use dedicated test commands to verify specific MCP tools or API endpoints.

# Build the server from source
go build -o bin/haproxy-mcp-server cmd/server/main.go

# Example: Test with TCP Runtime API
HAPROXY_HOST=your-haproxy-host HAPROXY_PORT=9999 HAPROXY_RUNTIME_MODE=tcp4 HAPROXY_RUNTIME_TIMEOUT=10 MCP_TRANSPORT=stdio ./bin/haproxy-mcp-server

# Example: Test with Unix socket
HAPROXY_RUNTIME_MODE=unix HAPROXY_RUNTIME_SOCKET=/path/to/haproxy.sock HAPROXY_RUNTIME_TIMEOUT=10 MCP_TRANSPORT=stdio ./bin/haproxy-mcp-server

# Example: Test with Stats page
HAPROXY_STATS_ENABLED=true HAPROXY_STATS_URL="http://localhost:8404/stats" HAPROXY_STATS_TIMEOUT=5 MCP_TRANSPORT=stdio ./bin/haproxy-mcp-server

Tools and capabilities

The MCP server exposes a set of tools that map to HAProxy Runtime API commands. In this guide, two example tools are available for testing and interaction: show_info retrieves runtime information about the HAProxy instance, and show_stat retrieves statistical data based on the configured filters.

# Example tool names and descriptions
Tool: show_info — Retrieves runtime information about HAProxy
Tool: show_stat — Retrieves current statistics for monitoring and analysis

Troubleshooting

If you encounter connection issues, verify that the Runtime API is reachable from the MCP server host, confirm that the correct mode (tcp4 or unix) is configured, and check that the MCP transport is set to stdio when using local development. Inspect logs for authentication or permission errors when using the Unix socket.

Available tools

show_info

Retrieves runtime information about the HAProxy instance including version, process state, and basic configuration.

show_stat

Retrieves current HAProxy statistics, allowing you to monitor traffic, connections, and backend performance.