Running with Docker

This guide covers deploying the Infrahub MCP server as a container, including running it alongside Infrahub in the same Docker Compose stack.

Quick start with Docker Compose

docker compose up -d

This pulls the published image from the Opsmill registry and starts the MCP server. Configure it with a .env file or environment variables (see Configuration reference).

Build the image locally

docker build -f development/Dockerfile -t infrahub-mcp .

Run standalone

docker run -p 8001:8001 \
  -e INFRAHUB_ADDRESS=http://your-infrahub-host:8000 \
  -e INFRAHUB_API_TOKEN=your-token \
  registry.opsmill.io/opsmill/infrahub-mcp:latest

The server listens on http://localhost:8001/mcp using the MCP Streamable HTTP transport.

Deploy alongside Infrahub

The MCP server connects to Infrahub over HTTP, making it a natural sidecar in a Docker Compose stack. Add the infrahub-mcp service to your existing docker-compose.yml:

services:
  # ... your existing Infrahub services ...

  infrahub-mcp:
    image: registry.opsmill.io/opsmill/infrahub-mcp:latest
    ports:
      - "8001:8001"
    environment:
      INFRAHUB_ADDRESS: "http://infrahub-server:8000"
      INFRAHUB_API_TOKEN: "${INFRAHUB_API_TOKEN}"
      MCP_HOST: "0.0.0.0"
      MCP_PORT: "8001"
    depends_on:
      - infrahub-server
    restart: unless-stopped

Replace infrahub-server with the service name of your Infrahub instance.

Connect your MCP client

Once the container is running, point your MCP client at the HTTP endpoint instead of running a local subprocess:

Cursor

{
  "mcpServers": {
    "infrahub_mcp": {
      "type": "streamable-http",
      "url": "http://localhost:8001/mcp"
    }
  }
}

VS Code

{
  "servers": {
    "infrahub_mcp": {
      "type": "http",
      "url": "http://localhost:8001/mcp"
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "infrahub_mcp": {
      "transport": "streamable-http",
      "url": "http://localhost:8001/mcp"
    }
  }
}

Configuration reference

Variable	Description	Default
INFRAHUB_ADDRESS	URL of your Infrahub instance	required
INFRAHUB_API_TOKEN	API token (or use username + password)	—
INFRAHUB_USERNAME	Username for basic-auth login	—
INFRAHUB_PASSWORD	Password for basic-auth login	—
INFRAHUB_TIMEOUT	HTTP request timeout in seconds	30
MCP_HOST	Bind address for the HTTP server	0.0.0.0
MCP_PORT	Port for the HTTP server	8001
INFRAHUB_MCP_READ_ONLY	Disable write operations	false
INFRAHUB_MCP_RATE_LIMIT_RPS	Rate limit (requests/sec, 0 = off)	0
INFRAHUB_MCP_CACHE_ENABLED	Enable response caching	false
INFRAHUB_MCP_PROMETHEUS_ENABLED	Prometheus format for /metrics	false

For the full list including retry, auth, OpenTelemetry, and more, see the Configuration reference.

Endpoints

Path	Method	Description
/mcp	POST	MCP Streamable HTTP transport
/health	GET	Health check for container orchestration probes
/metrics	GET	Request counts, errors, and latency (JSON or Prometheus)