consul-mcp-server

Consul MCP Server

The Consul MCP Server is a Model Context Protocol (MCP) server that provides seamless integration with HashiCorp Consul APIs, enabling advanced automation and interaction capabilities for service discovery, configuration management, and service mesh operations.

Features

• Dual Transport Support: Both Stdio and StreamableHTTP transports
• Service Discovery: Query and manage services, nodes, and health checks in the Consul catalog
• Key-Value Store: Access and manage Consul's distributed key-value store
• Service Mesh: Interact with Consul Connect for service mesh functionality including intentions and certificates
• ACL Management: Manage Access Control Lists including tokens, policies, roles, and auth methods
• Agent Operations: Monitor and configure Consul agents, including health checks and services
• Cluster Operations: Access operator tools for cluster management, autopilot, and Raft operations
• Container Ready: Docker support for easy deployment

Caution: The outputs and recommendations provided by the MCP server are generated dynamically and may vary based on the query, model, and the connected MCP server. Users should thoroughly review all outputs/recommendations to ensure they align with their organization's security best practices, compliance requirements, and Consul deployment policies before implementation.

Security Note: When using the StreamableHTTP transport in production, always configure the MCP_ALLOWED_ORIGINS environment variable to restrict access to trusted origins only. This helps prevent DNS rebinding attacks and other cross-origin vulnerabilities.

Prerequisites

1. A running Consul cluster or agent that the MCP server can connect to
2. For containerized deployment, Docker installed and running
3. Appropriate Consul ACL tokens if ACL is enabled in your Consul cluster

Transport Support

The Consul MCP Server supports multiple transport protocols:

1. Stdio Transport (Default)

Standard input/output communication using JSON-RPC messages. Ideal for local development and direct integration with MCP clients.

2. StreamableHTTP Transport

Modern HTTP-based transport supporting both direct HTTP requests and Server-Sent Events (SSE) streams. This is the recommended transport for remote/distributed setups.

Features:

• Endpoint: http://{hostname}:8080/mcp
• Health Check: http://{hostname}:8080/health
• Environment Configuration: Set TRANSPORT_MODE=streamable-http or TRANSPORT_PORT=8080 to enable

Environment Variables:

TLS Configuration

The Consul MCP Server supports secure connections to Consul clusters with proper TLS configuration. Here are the key settings:

Certificate Verification

By default, the MCP server verifies TLS certificates when connecting to HTTPS Consul endpoints. If your Consul cluster uses self-signed certificates or certificates that cannot be verified against the system's certificate store, you may encounter errors like:

tls: failed to verify certificate: x509: "________" certificate is not trusted

Disabling Certificate Verification (Development/Testing Only)

⚠️ Security Warning: Only disable certificate verification in development or testing environments. Never use this in production.

To disable TLS certificate verification, set the environment variable:

export CONSUL_SKIP_VERIFY=true

Example Configurations for Development

Development with self-signed certificates:

export CONSUL_HTTP_ADDR=https://consul.example.com:8501
export CONSUL_HTTP_TOKEN=your-acl-token
export CONSUL_SKIP_VERIFY=true

Production with proper certificates:

export CONSUL_HTTP_ADDR=https://consul.example.com:8501
export CONSUL_HTTP_TOKEN=your-acl-token
export CONSUL_SKIP_VERIFY=false
# CONSUL_SKIP_VERIFY should remain false (default)

Docker example with TLS skip verification:

docker run -i --rm \
  -e CONSUL_HTTP_ADDR=https://host.docker.internal:8501 \
  -e CONSUL_HTTP_TOKEN=your-token \
  -e CONSUL_SKIP_VERIFY=true \
  hashicorp/consul-mcp-server

Command Line Options

# Stdio mode
consul-mcp-server stdio [--log-file /path/to/log]

# StreamableHTTP mode
consul-mcp-server streamable-http [--transport-port 8080] [--transport-host 127.0.0.1] [--mcp-endpoint /mcp] [--log-file /path/to/log]

Session Modes

The Consul MCP Server supports two session modes when using the StreamableHTTP transport:

• Stateful Mode (Default): Maintains session state between requests, enabling context-aware operations.
• Stateless Mode: Each request is processed independently without maintaining session state, which can be useful for high-availability deployments or when using load balancers.

To enable stateless mode, set the environment variable:

export MCP_SESSION_MODE=stateless

Installation

Usage with VS Code

Add the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing Ctrl + Shift + P and typing Preferences: Open User Settings (JSON).

More about using MCP server tools in VS Code's agent mode documentation.

{
  "mcp": {
    "servers": {
      "consul": {
        "command": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "-e", "CONSUL_HTTP_ADDR=http://host.docker.internal:8500",
          "hashicorp/consul-mcp-server"
        ]
      }
    }
  }
}

Optionally, you can add a similar example (i.e. without the mcp key) to a file called .vscode/mcp.json in your workspace. This will allow you to share the configuration with others.

{
  "servers": {
    "consul": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "CONSUL_HTTP_ADDR=http://host.docker.internal:8500",
        "hashicorp/consul-mcp-server"
      ]
    }
  }
}

Copilot client mode

{
  servers: {
    "consul-cluster-dc1": {
      "url": "http://<mcp-server-dc1-address>:<port>",
      "headers": {
        "X-Consul-Address": "<consul-address-dc1>",
        "X-Consul-Token": "<consul-acl-token-dc1>"
      }
    },
    "consul-cluster-dc2": {
      "url": "http://<mcp-server-dc2-address>:<port>",
      "headers": {
        "X-Consul-Address": "<consul-address-dc2>",
        "X-Consul-Token": "<consul-acl-token-dc2>"
      }
    }
  },
  "inputs": []
}

Usage with Claude Desktop / Amazon Q Developer / Amazon Q CLI

More about using MCP server tools in Claude Desktop user documentation. Read more about using MCP server in Amazon Q from the documentation.

{
  "mcpServers": {
    "consul-dc1": {
      "command": "consul-mcp-server",
      "args": ["--host", "localhost", "--port", "8080"],
      "env": {
        "CONSUL_HTTP_ADDR": "https://consul-dc1.example.com:8501",
        "CONSUL_HTTP_TOKEN": "${CONSUL_DC1_TOKEN}"
      }
    },
    "consul-dc2": {
      "command": "consul-mcp-server",
      "args": ["--host", "localhost", "--port", "8081"],
      "env": {
        "CONSUL_HTTP_ADDR": "https://consul-dc2.example.com:8501",
        "CONSUL_HTTP_TOKEN": "${CONSUL_DC2_TOKEN}"
      }
    }
  }
}

Tool Configuration

Available Toolsets

The following sets of tools are available for interacting with Consul:

Resource Configuration

Available Resources

Install from source

Use the latest release version:

go install github.com/hashicorp/consul-mcp-server/cmd/consul-mcp-server@latest

Use the main branch:

go install github.com/hashicorp/consul-mcp-server/cmd/consul-mcp-server@main

{
  "mcp": {
    "servers": {
      "consul": {
        "command": "/path/to/consul-mcp-server",
        "args": ["stdio"]
      }
    }
  }
}