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.

Security Note: At this stage, the MCP server is intended for local use only. The MCP server should only be deployed in trusted networks with trusted clients. If using the StreamableHTTP transport, always configure the MCP_ALLOWED_ORIGINS environment variable to restrict access to trusted browser origins only. This helps prevent DNS rebinding attacks and other cross-origin browser attacks. MCP_ALLOWED_ORIGINS is a CORS protection and not a network connection allowlist.

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.

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

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:

Variable	Description	Default
TRANSPORT_MODE	Set to streamable-http to enable HTTP transport (legacy http value still supported)	stdio
TRANSPORT_HOST	Host to bind the HTTP server	127.0.0.1
TRANSPORT_PORT	HTTP server port	8080
MCP_ENDPOINT	HTTP server endpoint path	/mcp
MCP_SESSION_MODE	Session mode: stateful or stateless	stateful
MCP_ALLOWED_ORIGINS	Comma-separated list of allowed origins for CORS	"" (empty)
MCP_CORS_MODE	CORS mode: strict, development, or disabled	strict
INSECURE_NO_TLS	Allow the StreamableHTTP server to start without TLS. Set to true only for local development or testing. See TLS Configuration.	false
CONSUL_HTTP_ADDR	Consul agent HTTP API address	http://127.0.0.1:8500
CONSUL_HTTP_TOKEN	Consul ACL token for authentication	"" (empty)
CONSUL_SKIP_VERIFY	Skip TLS certificate verification (use only for development/testing)	false
CONSUL_ENTERPRISE	Enable Consul Enterprise features and API endpoints	true
CONSUL_MCP_SERVER_READ_GITHUB_RESOURCES	For latest Consul context, the flag enables the fetching resource from https://github.com/hashicorp/consul/blob/main/website/content/api-docs	true

TLS Configuration

The Consul MCP Server has two distinct TLS concerns:

1. Server TLS — the certificate the MCP server presents to MCP clients over the StreamableHTTP transport.
2. Client TLS — the certificate verification the MCP server performs when it connects to a Consul HTTPS endpoint.

Server TLS (StreamableHTTP transport)

When using the StreamableHTTP transport the server requires TLS by default. You must supply a certificate and key via environment variables:

Variable	Description
MCP_TLS_CERT_FILE	Path to the PEM-encoded TLS certificate file
MCP_TLS_KEY_FILE	Path to the PEM-encoded TLS private key file

export MCP_TLS_CERT_FILE=/path/to/server.crt
export MCP_TLS_KEY_FILE=/path/to/server.key
./consul-mcp-server streamable-http --transport-host 0.0.0.0 --transport-port 8080

Opting out of server TLS (development/testing only)

⚠️ Security Warning: Only disable server TLS in local development or testing environments. Never use this in production.

If you do not have TLS certificates available, you can explicitly opt out using the --insecure-no-tls CLI flag or the INSECURE_NO_TLS=true environment variable. This applies uniformly regardless of the bind host — there is no implicit exemption for localhost or 0.0.0.0.

CLI flag:

./consul-mcp-server streamable-http \
  --transport-host 127.0.0.1 --transport-port 8080 \
  --insecure-no-tls

Environment variable (container / env-driven deployments):

export INSECURE_NO_TLS=true
export TRANSPORT_HOST=0.0.0.0
export TRANSPORT_PORT=8080
./consul-mcp-server

Docker example:

docker run -i --rm \
  -e TRANSPORT_MODE=streamable-http \
  -e TRANSPORT_HOST=0.0.0.0 \
  -e INSECURE_NO_TLS=true \
  -p 8080:8080 \
  hashicorp/consul-mcp-server

Client TLS (connections to Consul)

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

# Download the Binary
# Find the compatible build for your operating system from the official releases page.
# e.g. for Mac Apple silicon
curl -LO https://releases.hashicorp.com/consul-mcp-server/0.1.1/consul-mcp-server_0.1.1_darwin_arm64.zip && unzip ./consul-mcp-server_0.1.1_darwin_arm64.zip

# common step to start the server
export CONSUL_HTTP_ADDR=<consul addr>
export CONSUL_HTTP_TOKEN=<consul double default acl token with read privilege>
./consul-mcp-server streamable-http --transport-port <8080 default> --transport-host 127.0.0.1


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

# StreamableHTTP mode (with TLS)
consul-mcp-server streamable-http [--transport-port 8080] [--transport-host 0.0.0.0] [--mcp-endpoint /mcp] [--log-file /path/to/log]
# MCP_TLS_CERT_FILE and MCP_TLS_KEY_FILE must be set in the environment.

# StreamableHTTP mode (without TLS — development/testing only)
consul-mcp-server streamable-http [--transport-port 8080] [--transport-host 127.0.0.1] [--mcp-endpoint /mcp] --insecure-no-tls

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:

Toolset	Tools	Description
catalog	get_catalog_services, get_catalog_nodes, get_catalog_service, get_catalog_connect, get_catalog_node, get_catalog_datacenters, get_catalog_gateway_services	Query and explore services and nodes in the Consul catalog
agent	get_agent_self, get_agent_config, get_agent_members, get_agent_metrics, get_agent_host, get_agent_version, get_agent_reload	Monitor and configure Consul agents
health	get_health_node, get_health_checks, get_health_service, get_health_connect, get_health_ingress, get_health_state	Query health information for services and nodes
kv	get_kv, get_kv_keys, get_kv_recursive	Access and manage the Consul key-value store
acl	get_acl_tokens, get_acl_policies, get_acl_roles, get_acl_auth_methods, get_acl_binding_rules, get_acl_templated_policies	Manage Access Control Lists and authentication
connect	get_connect_ca_roots, get_connect_ca_configuration, get_connect_intentions, get_connect_intention, get_connect_intention_match, get_connect_intention_check	Manage Consul Connect service mesh features
operator	get_operator_autopilot_*, get_operator_keyring, get_operator_license, get_operator_raft_*, get_operator_usage	Access cluster operational tools and configuration
session	get_session, get_session_node, get_session_list	Manage Consul sessions for distributed locking
status	get_status_leader, get_status_peers	Query cluster status and leadership information
peering	get_peerings, get_peering, get_peering_exported_services	Manage cluster peering relationships
config	get_config_entries, get_config_entry	Access Consul configuration entries
discovery	get_discovery_chain	Query service discovery chains
query	get_query, get_query_by_id, get_query_execute, get_query_explain	Execute and manage prepared queries
namespaces	get_namespaces, get_namespace	Manage Consul Enterprise namespaces (Enterprise only)
identity	Various identity-related tools	Manage service identity and certificates

Resource Configuration

Available Resources

Resource URI	Description
consul://connect/ca/roots	Consul Cluster Identity - Provides access to the Consul Connect CA root certificates and cluster identity information
consul://api-docs/*	Consul API Documentation - Dynamic access to official Consul API documentation from the GitHub repository

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"]
      }
    }
  }
}

Contributing

Thank you for your interest in contributing! Please refer to CONTRIBUTING.md

License

This project is licensed under the terms of the Business Source License 1.1. Please refer to the LICENSE file for the full terms.

Security

For security issues, please contact security@hashicorp.com or follow our security policy.

Support

For bug reports and feature requests, please open an issue on GitHub.

For general questions and discussions, open a GitHub Discussion.