Skip to main content

Troubleshooting Guide

Common issues when running the Hyperstack API MCP Server or integrating it with Claude Desktop, with diagnostic procedures.

This guide outlines common issues that may occur when running the Hyperstack API MCP Server or integrating it with Claude Desktop. Each section provides structured diagnostic procedures and verified resolutions.

Important: Live Infrastructure Changes & Data Loss Risk

This MCP server can create, modify, and delete real Hyperstack resources, which may incur charges on your account. Always review actions before confirming them. NexGen Cloud is not liable for any unintended resource usage, costs, or data loss resulting from the use of this tool. Use it at your own risk.

Server Issues​

Use the guidance below to resolve problems that prevent the MCP Server from starting or authenticating correctly.

Server Won't Start​

Startup failures are most commonly caused by port conflicts or local environment configuration issues.

Error: Port 8080 is already in use

Another process is already bound to port 8080, which prevents the MCP Server from starting on its default port.

  1. Identify the Process Using Port 8080​

    Determine which process is currently bound to port 8080.

    Find Process Using Port 8080
    lsof -i :8080  # macOS/Linux
    netstat -ano | findstr :8080  # Windows

    These commands return the process ID (PID) using port 8080, allowing you to stop or reconfigure the conflicting service.

  2. Run the MCP Server on a Different Port​

    If you prefer not to stop the existing process, configure the MCP Server to use another port.

    Run MCP Server on Port 8081
    export MCP_PORT=8081
    make dev

    Setting MCP_PORT overrides the default port and starts the development server on port 8081.

Authentication Failed​

Authentication errors occur when the configured API key cannot be validated.

Error: Authentication failed - Invalid API key

This typically means the HYPERSTACK_API_KEY is missing, malformed, or no longer valid.

  1. Check the Existing API Key​

    Confirm that the API key is correctly configured in your .env file.

    Check API Key
    cat .env | grep HYPERSTACK_API_KEY

    This command prints the configured API key entry so you can verify that it exists and is correctly formatted.

  2. Generate a New API Key​

    If the key is missing or invalid, generate a new one from Hyperstack Console – API Keys.

  3. Update the Environment File​

    Replace the existing value in your .env file.

    Update API Key
    HYPERSTACK_API_KEY=your_new_key_here

    Ensure the HYPERSTACK_API_KEY variable contains a valid Hyperstack API key.

  4. Restart the MCP Server​

    Restart the server so the updated environment variable is loaded.

Claude Desktop Issues​

The following checks help resolve connection problems between Claude Desktop and the MCP Server.

MCP Server Not Connected​

Work through these steps to confirm that all required components are installed and correctly configured.

If Claude Desktop does not detect the MCP Server, complete the following checks.

  1. Verify Server Health​

    Confirm that the MCP Server is running and reachable.

    Health Check
    curl http://localhost:8080/health

    This queries the MCP Server health endpoint. A successful response confirms that the service is reachable on port 8080. If the server is not running:

    Start MCP Server
    cd hyperstack-mcp-server
    make docker-run

    These commands start the MCP Server using the project's Docker configuration.

  2. Verify Node.js Installation​

    Ensure Node.js v18.0.0 or later is installed.

    Check Node Version
    node --version

    This prints the installed Node.js version. If the version is below v18.0.0, install the latest LTS release from https://nodejs.org.

  3. Verify mcp-remote Installation​

    Confirm that mcp-remote is installed globally.

    Check mcp-remote
    npm list -g mcp-remote

    This checks whether the mcp-remote package is installed globally. If it is not listed, install it:

    Install mcp-remote
    npm install -g mcp-remote

    This installs the MCP proxy required for Claude Desktop connectivity.

  4. Validate Claude Configuration File​

    Ensure the configuration file exists and contains the correct values:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json
    • Linux: ~/.config/Claude/claude_desktop_config.json

    Confirm that it includes:

    • The absolute path to the Node.js executable
    • The absolute path to the proxy.js file from mcp-remote
    • The MCP endpoint: http://127.0.0.1:8080/mcp

  5. Restart Claude Desktop​

    Fully quit Claude Desktop and reopen it to load the updated configuration.

Invalid JSON Configuration​

JSON parsing errors indicate a syntax issue in the Claude Desktop configuration file.

Error: Failed to parse configuration

  1. Review Configuration Structure​

    Ensure your configuration matches the following structure:

    Valid Configuration Example
    {
      "mcpServers": {
        "hyperstack-mcp": {
          "command": "/path/to/node",
          "args": [
            "/path/to/mcp-remote/dist/proxy.js",
            "http://127.0.0.1:8080/mcp"
          ]
        }
      }
    }

    This shows the minimum valid structure required for Claude Desktop to load the MCP configuration.

  2. Validate JSON Using CLI​

    Validate your configuration file using one of the following commands:

    Validate JSON (macOS/Linux)
    python3 -m json.tool ~/Library/Application\ Support/Claude/claude_desktop_config.json
    Validate JSON (Windows)
    python -m json.tool %APPDATA%\Claude\claude_desktop_config.json

    These commands validate JSON syntax and report formatting errors if the file contains invalid structure.

API Errors​

The following errors are returned directly by the Hyperstack API.

Rate Limit Exceeded​

A 429 response indicates that too many requests were sent in a short period of time.

Error: Rate limit exceeded (429)

  1. Wait Before Retrying​

    Wait approximately 60 seconds before retrying your request so the rate limit window can reset.

Request Timeout​

Timeout errors occur when a request takes longer than the allowed processing time.

Error: Request timeout

  1. Reduce Request Size​

    Break large requests into smaller operations to reduce processing time.

  2. Retry the Request​

    Wait briefly before attempting the request again.

Docker Issues​

Use the steps below if Docker-related errors prevent the MCP Server from running.

Docker Not Running​

This error occurs when the Docker daemon is not active.

Error: Cannot connect to Docker daemon

  1. Start Docker Desktop​

    Ensure Docker Desktop is installed and running.

  2. Confirm Docker Initialization​

    Wait until Docker reports that it is fully initialized before retrying.

Quick Diagnostics​

Run the following commands to quickly verify your local environment.

Execute Diagnostic Commands​

Follow the steps below to validate server health, Node.js installation, proxy installation, and API key configuration.

  1. Check Server Health​

    Check Server Health
    curl http://localhost:8080/health || echo "Server not running"

  2. Check Node.js Installation​

    Check Node Version
    node --version || echo "Node.js not installed"

  3. Check mcp-remote Installation​

    Check mcp-remote
    npm list -g mcp-remote || echo "mcp-remote not installed"

  4. Check API Key Configuration​

    Check API Key
    [ -n "$HYPERSTACK_API_KEY" ] && echo "API key set" || echo "API key not set"

Common Fixes​

If issues persist, use the remediation steps below to reset your environment.

Complete Reset​

Perform a clean restart of all services.

  1. Stop All Services​

    Stop Services
    make docker-down

    This stops and removes running Docker containers defined in the project configuration.

  2. Rebuild and Restart​

    Rebuild and Restart
    make build
    make docker-run

    These commands rebuild the Docker image and restart the MCP Server container.

  3. Restart Claude Desktop​

    Fully quit and reopen Claude Desktop.

Test Your API Key​

Use a direct API request to confirm your API key is valid.

Send Test Request​

Test API Key
curl -H "api-key: YOUR_API_KEY" \
  https://infrahub-api.nexgencloud.com/v1/core/environments

A successful response returns a list of environments.


Back to top

On this page