Configuration Reference

Configure the MCP Server through environment variables that control how it authenticates, connects to the API, and manages runtime behavior.

The Hyperstack API MCP Server is configured entirely through environment variables that control how it authenticates, connects to the Hyperstack API, and manages runtime behavior.

This guide provides a reference for all supported configuration variables and demonstrates how to apply them in local and production environments.

Configuration Overview

All MCP Server configuration is managed through environment variables.

You can configure the server by:

• Setting variables in a .env file
• Exporting variables in your shell
• Passing variables directly to Docker using -e
• Supplying environment configuration via orchestration tools (e.g., Kubernetes, Docker Compose)

Environment Variable Precedence

Environment variables always take precedence over .env file defaults.

Core Configuration

These variables control authentication and basic runtime behavior.

Variable	Type	Default	Required	Description
HYPERSTACK_API_KEY	string	–	Yes	Your Hyperstack API key used for authenticating API requests.
HYPERSTACK_API_URL	string	https://infrahub-api.nexgencloud.com/v1	No	Base URL for the Hyperstack Infrahub API. Override only if using a staging or private endpoint.
ENVIRONMENT	string	local	No	Runtime environment (local, dev, prod).

HYPERSTACK_API_KEY (Required)

This key is used to authenticate all outbound API requests.

You can generate an API key from the:

Hyperstack Console → API Keys
https://console.hyperstack.cloud/api-keys

API Key Security

Never commit your API key to version control. Inject it securely using environment variables or secret managers.

Logging Configuration

These variables control logging level and output format.

Variable	Type	Default	Required	Description
LOG_LEVEL	string	INFO	No	Logging verbosity (DEBUG, INFO, WARNING, ERROR, CRITICAL).
LOG_FORMAT	string	json	No	Log output format (json or text).

Recommended Production Settings

These settings configure the server to use standard informational logging with structured JSON output suitable for production environments.

LOG_LEVEL=INFO
LOG_FORMAT=json

Recommended Development Settings

These settings configure the server to use verbose debug logging with human-readable text output for local troubleshooting.

LOG_LEVEL=DEBUG
LOG_FORMAT=text

Connection Pool Configuration

These variables control HTTP connection pooling behavior.

Variable	Type	Default	Required	Description
MAX_CONNECTIONS	integer	100	No	Maximum total concurrent connections in the HTTP pool.
MAX_KEEPALIVE_CONNECTIONS	integer	50	No	Maximum number of keep-alive connections.
KEEPALIVE_EXPIRY	integer (seconds)	5	No	Idle connection keep-alive duration in seconds.

Request and Retry Configuration

These variables control request timeouts and retry behavior.

Variable	Type	Default	Required	Description
REQUEST_TIMEOUT	integer (seconds)	30	No	Timeout duration for API requests.
MAX_RETRIES	integer	3	No	Maximum number of retry attempts for failed API calls.
RETRY_BACKOFF_FACTOR	float	0.5	No	Exponential backoff multiplier between retries.

Retry Behavior

Retries use exponential backoff:

delay = RETRY_BACKOFF_FACTOR * (2 ^ retry_attempt)

Example Configuration (.env)

This example shows a complete .env configuration.

.env

# Core
HYPERSTACK_API_KEY=your_api_key_here
HYPERSTACK_API_URL=https://infrahub-api.nexgencloud.com/v1
ENVIRONMENT=local

# Logging
LOG_LEVEL=INFO
LOG_FORMAT=json

# Connection Pool
MAX_CONNECTIONS=100
MAX_KEEPALIVE_CONNECTIONS=50
KEEPALIVE_EXPIRY=5

# Request Handling
REQUEST_TIMEOUT=30
MAX_RETRIES=3
RETRY_BACKOFF_FACTOR=0.5

Start the MCP Server:

docker run --env-file .env -p 8080:8080 ghcr.io/nexgencloud/hyperstack-mcp-server:latest

Docker Configuration Example

This example injects configuration using Docker flags.

Run MCP Server with Custom Configuration

docker run --rm \
  --name hyperstack-mcp \
  -p 8080:8080 \
  -e HYPERSTACK_API_KEY=your_api_key_here \
  -e LOG_LEVEL=DEBUG \
  -e LOG_FORMAT=text \
  -e MAX_RETRIES=5 \
  ghcr.io/nexgencloud/hyperstack-mcp-server:latest

Production Deployment Considerations

These are common hardening practices for production deployments.

• Use secure secret storage (e.g., Kubernetes Secrets, Vault).
• Avoid exposing debug logs.
• Monitor retry counts and timeout errors.
• Use a reverse proxy (e.g., NGINX) if exposing beyond localhost.
• Restrict network access to trusted clients only.

Related Documentation

• Hyperstack API MCP Server - Quickstart Guide — Launch the MCP Server, connect Claude Desktop, and validate your setup.
• Installation Guide — Complete Docker setup, runtime configuration, and container lifecycle management.
• Claude Desktop Setup Guide — Configure Claude Desktop with Node.js and mcp-remote to connect to the MCP Server.
• MCP Tools and Operations Reference — Detailed reference for supported MCP tools, operations, and API mappings.
• Troubleshooting — Diagnose and resolve Docker, authentication, and Claude connectivity issues.

Back to top