Skip to main content

Troubleshooting Guide

Common issues with the hosted Hyperstack API MCP Server and with instances you run yourself, plus diagnostic procedures.

This guide outlines common issues with the Hyperstack API MCP Server, whether you connect to the hosted server or run your own instance. Each section provides structured diagnostic procedures and verified resolutions.

Start with Hosted MCP Server Issues if you connect to https://console.hyperstack.cloud/ai/mcp. The sections from Server Issues onward apply to an instance you run yourself, apart from Claude Desktop Issues and API Errors, which apply to both.

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.

Hosted MCP Server Issues​

Use the guidance below when your client connects to the Hyperstack-hosted MCP Server at https://console.hyperstack.cloud/ai/mcp. These issues involve the sign-in flow rather than a server you run.

Your Client Cannot Add the Server​

The hosted server accepts connections from clients whose redirect address it recognizes, which covers clients running on your own machine, Claude on the web, and Open WebUI's hosted service.

If your client is rejected when it registers, it is reachable at an address the server does not recognize. This applies to an Open WebUI instance you host on your own public domain. Connect that instance to a self-hosted MCP Server instead, as described in the Local Installation Guide.

Sign-In Does Not Complete​

If the browser opens the Hyperstack sign-in page but your client never reports a connection, the sign-in was not returned to the client.

  1. Complete the Sign-In in the Same Browser Session​

    Finish the sign-in in the browser window your client opened, rather than copying the address into another browser or profile.

  2. Retry the Connection​

    Remove the server from your client and add it again. Each attempt starts a new sign-in, and an abandoned attempt expires on its own.

Tool Calls Fail After Working Earlier​

Your session credentials expire, and your client renews them automatically. A tool call that fails after a period of inactivity usually means the renewal did not complete.

  • Error: Refresh temporarily unavailable, please retry

    Another renewal for the same session is already running. Run the request again.

  • A failure that persists across retries means the session can no longer be renewed. Remove the server from your client, add it again, and sign in.

Server Issues​

Use the guidance below to resolve problems that prevent a self-hosted 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.

    terminalFind 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, publish the container on another port.

    terminalRun MCP Server on Port 8081
    docker run --rm \
      --name hyperstack-mcp \
      -p 8081:8080 \
      -e HYPERSTACK_API_KEY=your_api_key_here \
      ghcr.io/nexgencloud/hyperstack-mcp-server:latest

    The server always listens on port 8080 inside the container. The first number maps it to a different port on your machine, so the server is reachable at http://localhost:8081. Update your client's MCP URL to match.

Authentication Failed​

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

Error: a tool call returns an error with "status_code": 401 and Invalid API Key in its details

This means the HYPERSTACK_API_KEY the server was started with is malformed or no longer valid. A server started with no key at all does not run: it stops at startup with AUTH_MODE=api_key requires HYPERSTACK_API_KEY.

  1. Check the Existing API Key​

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

    terminalCheck 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.

    terminalUpdate 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​

Claude Desktop shows no MCP tools, or reports that the server is unavailable.

Each requirement below has a step in the Claude Desktop Setup Guide. Check them in order, and return to that guide for the full procedure.

  1. Confirm the Connector Is Connected (hosted server)​

    Open Settings → Connectors and find the connector you added. Check that its Remote MCP server URL is https://console.hyperstack.cloud/ai/mcp. If the connector does not show as connected, click Connect and complete the sign-in in the browser window that opens.

    The hosted server needs neither Node.js nor the mcp-remote proxy, so the steps below apply only to an instance you run yourself.

  2. Confirm the Server Is Reachable (self-hosted)​

    Check your instance's health endpoint.

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

    A response confirms the server is running. If nothing responds, start it as described in the Local Installation Guide.

  3. Confirm Node.js and mcp-remote Are Installed (self-hosted)​

    Claude Desktop reaches your own instance through the mcp-remote proxy, which needs Node.js v18.0.0 or later.

    terminalCheck Prerequisites
    node --version
    npm list -g mcp-remote

    If either is missing, install them as described in Prepare the Local Environment.

  4. Confirm the Configuration Values (self-hosted)​

    In claude_desktop_config.json, check that the Node.js path and the proxy.js path are absolute and match your system, and that the MCP endpoint is the URL of the server you intend to reach. The file's location on each operating system, and a worked example for each, are in Configure Claude Desktop.

  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. This file is used only when Claude Desktop reaches an instance you run yourself, because the hosted server is added as a custom connector instead.

Error: Failed to parse configuration

  1. Review Configuration Structure​

    Ensure your configuration matches the following structure:

    jsonValid 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:

    terminalValidate JSON (macOS/Linux)
    python3 -m json.tool ~/Library/Application\ Support/Claude/claude_desktop_config.json
    terminalValidate 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 a self-hosted 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.

Diagnostics for a Self-Hosted Instance​

Run the following commands to verify the environment around an instance you run yourself.

Execute Diagnostic Commands​

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

  1. Check Server Health​

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

  2. Check Node.js Installation​

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

  3. Check mcp-remote Installation​

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

  4. Check API Key Configuration​

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

Common Fixes for a Self-Hosted Instance​

If issues persist, use the remediation steps below to reset an instance you run yourself.

Complete Reset​

Perform a clean restart of all services.

  1. Stop and Remove the Container​

    terminalStop and Remove
    docker stop hyperstack-mcp
    docker rm hyperstack-mcp

    This stops the MCP Server and removes the container, so the next run starts from a clean state.

  2. Pull the Latest Image and Start Again​

    terminalPull and Run
    docker pull ghcr.io/nexgencloud/hyperstack-mcp-server:latest

    docker run -d \
      --name hyperstack-mcp \
      -p 8080:8080 \
      -e HYPERSTACK_API_KEY=your_api_key_here \
      ghcr.io/nexgencloud/hyperstack-mcp-server:latest

    This fetches the current image and starts a fresh 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​

terminalTest 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.

On this page