Overview

This project provides an MCP (Model Context Protocol) server written in Go that integrates with HAProxy through the Runtime API. The server maintains a registry of model endpoints and metadata, and exposes a simple HTTP API to manage models and runtime routing. By connecting to HAProxy’s Runtime API, the server can update runtime configuration (weights, backends, ACLs) without restarting HAProxy, enabling dynamic model routing and canary-style rollouts.

This is useful when you run multiple model backends (different versions, providers, or sizes) and need fine-grained control over traffic distribution or metadata-based routing. Instead of editing static HAProxy config files and reloading the process, the MCP server issues runtime commands to HAProxy and also serves a model-management surface for automation, CI/CD pipelines, and operator tooling.

Features

Lightweight Go implementation designed for production use
Integrates with HAProxy Runtime API to change routing/weights without reloads
HTTP management API for model registration, updates, and querying
Supports canary rollouts and dynamic traffic redistribution
Stores model metadata for discovery and routing decisions
Health and metrics endpoints for observability
Simple configuration via CLI flags or environment variables

Installation / Configuration

Requirements:

Go 1.18+ (for building from source) or Docker
HAProxy 2.0+ (Runtime API via stats socket recommended)

Clone and build:

git clone https://github.com/tuannvm/haproxy-mcp-server.git
cd haproxy-mcp-server
go build -o haproxy-mcp-server ./cmd/server

Run with defaults (example):

./haproxy-mcp-server \
  --listen :8080 \
  --haproxy-socket /var/run/haproxy.sock \
  --storage ./data/models.json

Docker:

# Dockerfile (example)
FROM golang:1.20-alpine AS build
WORKDIR /src
COPY . .
RUN go build -o /bin/haproxy-mcp-server ./cmd/server

FROM alpine
COPY --from=build /bin/haproxy-mcp-server /bin/haproxy-mcp-server
CMD ["/bin/haproxy-mcp-server", "--listen", ":8080", "--haproxy-socket", "/var/run/haproxy.sock"]

HAProxy configuration snippet to enable a runtime socket (recommended UNIX socket):

global
    # socket accessible by the MCP server
    stats socket /var/run/haproxy.sock mode 600 level admin
    # optional: bind HTTP stats (alternative to UNIX socket)
    # stats socket [email protected]:9999 level admin

Configuration options (typical flags / env vars):

–listen: HTTP listen address for the MCP server (default :8080)
–haproxy-socket: path to HAProxy runtime socket (unix or tcp form)
–storage: file or directory to persist model metadata
–log-level: logging verbosity

Adjust the socket permissions so the MCP server can connect to the HAProxy socket (match UID/GID or use a group with access).

Available Resources

HTTP management API (examples below)
Health and metrics endpoints: /healthz, /metrics
Persistent model store (JSON file by default)
Integration layer that translates management API calls to HAProxy Runtime API commands

Common endpoints (examples):

Endpoint	Method	Purpose
/models	GET	List registered models and metadata
/models	POST	Register a new model
/models/{id}	PUT	Update model metadata or weights
/models/{id}	DELETE	Unregister a model
/healthz	GET	Health check
/metrics	GET	Prometheus metrics

Example: register a model via the MCP server API:

curl -X POST http://localhost:8080/models \
  -H "Content-Type: application/json" \
  -d '{
    "id": "gpt-4-small",
    "address": "http://10.0.0.5:8000",
    "weight": 100,
    "tags": {"version":"v1","provider":"internal"}
  }'

Example: instruct HAProxy to adjust routing weights (via MCP server):

curl -X PUT http://localhost:8080/models/gpt-4-small \
  -H "Content-Type: application/json" \
  -d '{"weight": 50}'

The server converts this into the appropriate HAProxy Runtime API commands to update backend server weights or ACL maps.

Use Cases

Canary rollouts: Gradually shift traffic from one model version to another by adjusting weights through the MCP API without reloading HAProxy.
A/B testing: Route a percentage of requests to different model backends and modify distributions at runtime.
Multi-provider routing: Maintain a registry of internal and external model endpoints and steer traffic based on metadata (latency, cost, capability).
Emergency rollback: Quickly direct all traffic back to a stable model by changing runtime weights or disabling a backend.
Observability and automation: Integrate with CI/CD or orchestration systems to programmatically update routing when models are deployed.

Tips and Best Practices

Prefer a UNIX domain socket for the HAProxy Runtime API in production and limit its filesystem permissions.
Persist model metadata to durable storage to survive MCP server restarts.
Use health checks on model backends so HAProxy can automatically mark unhealthy servers and avoid routing traffic to failed model instances.
Expose metrics and alerts for weight changes, failed runtime commands, and HAProxy connectivity issues.

HAProxy MCP Server in Go with Runtime API