Consul MCP Server: Service Management, Health, KV Store

Overview

Consul MCP Server is a lightweight service that provides core service discovery and configuration primitives: service registration, health checking, and a key-value (KV) store. It is designed for development, testing, and small deployments where you need a simple, reliable way to coordinate services and share configuration without running a full Consul cluster.

The server exposes a familiar HTTP-style API surface for managing services and KV entries and runs as a single binary (or container). Developers can register services, attach health checks, and read/write configuration flags or secrets to the KV store. This makes it useful for local development, CI pipelines, or minimal staging environments that require service discovery and dynamic configuration.

Features

• Service registration and discovery (register, deregister, list services)
• Health check management and periodic check execution
• Simple KV store for configuration and feature flags
• HTTP API compatible with common Consul patterns (register/check/kv)
• Single-binary or container deployment for easy use in CI and dev machines
• Pluggable configuration via CLI flags or a small configuration file

Installation / Configuration

Clone and build from source (requires Go installed):

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

Run the server with default options:

./consul-mcp-server

Run the server with explicit options (address, data directory, log level):

./consul-mcp-server \
  --bind=0.0.0.0:8500 \
  --data-dir=/var/lib/consul-mcp \
  --log-level=info

Example YAML configuration (alternative to flags):

bind: "0.0.0.0:8500"
data_dir: "/var/lib/consul-mcp"
log_level: "info"
check_interval: "10s"

Start with a configuration file:

./consul-mcp-server --config=config.yaml

Networking and storage considerations:

• Bind to an address reachable by your services (default 127.0.0.1 for local development).
• Choose a persistent data directory for KV and service metadata if you want state across restarts; otherwise use a temporary directory for ephemeral runs.

API quick reference

Below are the commonly used operations and their typical endpoint patterns. The server follows familiar Consul-style paths so existing tooling and scripts can often be adapted with minimal change.

curl -X PUT http://localhost:8500/v1/agent/service/register \
  -H "Content-Type: application/json" \
  -d '{
    "ID": "orders-1",
    "Name": "orders",
    "Address": "10.0.0.15",
    "Port": 8080,
    "Check": {
      "HTTP": "http://10.0.0.15:8080/health",
      "Interval": "10s"
    }
  }'

# Put
curl -X PUT http://localhost:8500/v1/kv/config/feature_x -d 'true'

# Get (returns base64-encoded value in typical Consul format)
curl http://localhost:8500/v1/kv/config/feature_x