HAProxy MCP Server

A Model Context Protocol (MCP) server for HAProxy implemented in Go, leveraging HAProxy Runtime API and mcp-go.

Overview

The HAProxy MCP Server provides a standardized way for LLMs to interact with HAProxy's runtime API via the Model Context Protocol (MCP). This enables LLMs to perform HAProxy administration tasks, monitor server status, manage backend servers, and analyze traffic patterns, all through natural language interfaces.

Features

Full HAProxy Runtime API Support: Comprehensive coverage of HAProxy's runtime API commands
Context-Aware Operations: All operations support proper timeout and cancellation handling
Stats Page Integration: Support for HAProxy's web-based statistics page for enhanced metrics and visualization
Secure Authentication: Support for secure connections to HAProxy runtime API
Multiple Transport Options: Supports both stdio and HTTP transports for flexibility in different environments
Enterprise Ready: Designed for production use in enterprise environments
Docker Support: Pre-built Docker images for easy deployment

Installation

Homebrew

# Add the tap
brew tap tuannvm/tap

# Install the package
brew install haproxy-mcp-server

From Binary

Using Go

go install github.com/tuannvm/haproxy-mcp-server/cmd/server@latest

Using Docker

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

MCP Integration

To use this server with MCP-compatible LLMs, configure the assistant with the following connection details:

HAProxy Runtime API over TCP4:

{
  "mcpServers": {
    "haproxy": {
      "command": "haproxy-mcp-server",
      "env": {
        "HAPROXY_HOST": "localhost",
        "HAPROXY_PORT": "9999",
        "HAPROXY_RUNTIME_MODE": "tcp4",
        "HAPROXY_RUNTIME_TIMEOUT": "10",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

HAProxy Runtime API over Unix Socket:

{
  "mcpServers": {
    "haproxy": {
      "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 with Stats Page Support:

{
  "mcpServers": {
    "haproxy": {
      "command": "haproxy-mcp-server",
      "env": {
        "HAPROXY_STATS_ENABLED": "true",
        "HAPROXY_STATS_URL": "http://localhost:8404/stats",
        "HAPROXY_STATS_TIMEOUT": "5",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

When using only the stats page functionality, there's no need to define Runtime API parameters like host and port. You can use both Runtime API and Stats Page simultaneously for complementary capabilities, or use only one of them based on your environment's constraints.

Available MCP Tools

The HAProxy MCP Server exposes tools that map directly to HAProxy's Runtime API commands, organized into the following categories:

Statistics & Process Info: Retrieve statistics, server information, and manage counters
Topology Discovery: List frontends, backends, server states, and configuration details
Dynamic Pool Management: Add, remove, enable/disable servers and adjust their properties
Session Control: View and manage active sessions
Maps & ACLs: Manage HAProxy maps and ACL files
Health Checks & Agents: Control health checks and agent-based monitoring
Miscellaneous: View errors, run echo tests, and get help information

Configuration

The server can be configured using the following environment variables:

Variable

Description

Default

HAPROXY_HOST

Host of the HAProxy instance (TCP4 mode only)

127.0.0.1

HAPROXY_PORT

Port for the HAProxy Runtime API (TCP4 mode only)

9999

HAPROXY_RUNTIME_MODE

Connection mode: "tcp4" or "unix"

tcp4

HAPROXY_RUNTIME_SOCKET

Socket path (Unix mode only)

/var/run/haproxy/admin.sock

HAPROXY_RUNTIME_URL

Direct URL to Runtime API (optional, overrides other runtime settings)

HAPROXY_RUNTIME_TIMEOUT

Timeout for runtime API operations in seconds

HAPROXY_STATS_ENABLED

Enable HAProxy stats page support

true

HAPROXY_STATS_URL

URL to HAProxy stats page (e.g., http://localhost:8404/stats)

http://127.0.0.1:8404/stats

HAPROXY_STATS_TIMEOUT

Timeout for stats page operations in seconds

MCP_TRANSPORT

MCP transport method (stdio/http)

stdio

MCP_PORT

Port for HTTP transport (when using http)

8080

LOG_LEVEL

Logging level (debug/info/warn/error)

info

Note: You can use the Runtime API (TCP4 or Unix socket mode), the Stats API, or both simultaneously. At least one must be properly configured for the server to function.

Security Considerations

Authentication: Connect to HAProxy's Runtime API using secure methods
Network Security: When using TCP4 mode, restrict connectivity to the Runtime API port
Unix Socket Permissions: When using Unix socket mode, ensure proper socket file permissions
Input Validation: All inputs are validated to prevent injection attacks

Development

Testing

# Run all tests
go test ./...

# Run tests excluding integration tests
go test -short ./...

# Run integration tests with specific HAProxy instance
export HAPROXY_HOST="your-haproxy-host"
export HAPROXY_PORT="9999"
go test ./internal/haproxy -v -run Test

You can test the HAProxy MCP server locally in several ways:

Direct CLI Testing

Build and run the server directly with environment variables:

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

# Option 1: Test with TCP connection mode
HAPROXY_HOST=<your-haproxy-host> HAPROXY_PORT=9999 HAPROXY_RUNTIME_MODE=tcp4 HAPROXY_RUNTIME_TIMEOUT=10 LOG_LEVEL=debug MCP_TRANSPORT=stdio ./bin/haproxy-mcp-server

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

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

# Option 4: Test with both Runtime API and Stats page
HAPROXY_HOST=<your-haproxy-host> HAPROXY_PORT=9999 HAPROXY_RUNTIME_MODE=tcp4 HAPROXY_RUNTIME_TIMEOUT=10 HAPROXY_STATS_ENABLED=true HAPROXY_STATS_URL="http://localhost:8404/stats" HAPROXY_STATS_TIMEOUT=5 LOG_LEVEL=debug MCP_TRANSPORT=stdio ./bin/haproxy-mcp-server

Test Individual MCP Tools

You can test specific MCP tools with JSON-RPC calls:

# Test show_info tool
echo '{"jsonrpc":"2.0","id":1,"method":"callTool","params":{"name":"show_info","arguments":{}}}' | HAPROXY_HOST=<your-haproxy-host> HAPROXY_PORT=9999 HAPROXY_RUNTIME_MODE=tcp4 LOG_LEVEL=debug ./bin/haproxy-mcp-server

# Test show_stat tool
echo '{"jsonrpc":"2.0","id":2,"method":"callTool","params":{"name":"show_stat","arguments":{"filter":""}}}' | HAPROXY_HOST=<your-haproxy-host> HAPROXY_PORT=9999 HAPROXY_RUNTIME_MODE=tcp4 LOG_LEVEL=debug ./bin/haproxy-mcp-server

Technical Implementation

The HAProxy MCP Server includes several technical improvements designed for reliability and robustness:

Context-Aware Operations: All API calls support context-based timeout and cancellation, allowing graceful termination of long-running operations.
Fallback Mechanisms: Automatic fallback to socat if direct connection fails, ensuring compatibility across different HAProxy deployments.
Unified Socket Handling: Common code for both TCP and Unix socket connections, reducing duplication and improving maintainability.
Resilient Connection Management: Dynamic buffer management for large responses and proper resource cleanup with deadline handling.
Comprehensive Error Handling: Structured error handling and logging for easier troubleshooting.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

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

NextCHANGELOG

Last updated 1 month ago

Was this helpful?