Skip to main content

Claude Desktop Setup

Connect Claude Desktop to a running MCP Server using the mcp-remote proxy.

This guide explains how to connect Claude Desktop to a running MCP Server using the mcp-remote proxy. The proxy bridges Claude Desktop’s MCP client configuration to the local MCP endpoint exposed by the MCP Server.

Both parts of this procedure must be completed for successful integration.

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.

Install and Configure Claude Desktop​

Follow these steps to prepare your environment, configure Claude Desktop, and validate the connection to the MCP Server.

Prerequisites​

Before you begin, ensure the following requirements are met:

  • The MCP Server is running locally and accessible at http://127.0.0.1:8080.
  • The latest version of Claude Desktop is installed.
  • Node.js v18.0.0 or later is installed on your system.
  • The mcp-remote package is installed globally using npm.

Part 1 – Prepare the Local Environment​

  1. Verify the MCP Server​

    Confirm that the MCP Server is running and healthy.

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

    This command queries the MCP Server health endpoint and verifies that the service is reachable on port 8080. A successful response should resemble the following:

    {
      "status": "ok",
      "service": "hyperstack-mcp-server",
      "version": "0.1.0"
    }

    If the server does not respond, ensure it is running and that port 8080 is not in use by another service.

  2. Install Node.js (if not already installed)​

    Verify your installed version:

    node --version

    This command prints the installed Node.js version. The output must be v18.0.0 or higher. If Node.js is not installed or is below version 18.0.0, install the latest LTS release from:

    https://nodejs.org

  3. Install mcp-remote​

    Install the MCP proxy package globally:

    npm install -g mcp-remote

    This command installs the mcp-remote package globally so it can be executed by Claude Desktop. Upon successful installation, npm will report that the package was added and display the installed version.

  4. Locate the Node.js Executable Path​

    • macOS / Linux:

      which node

    • Windows:

      where node

    These commands return the full filesystem path to the Node.js executable. This path must be used as the command value in the Claude Desktop configuration file.

  5. Locate the mcp-remote Proxy Script​

    • macOS / Linux:

      ls -la $(npm root -g)/mcp-remote/dist/proxy.js

    • Windows:

      dir "%APPDATA%\npm\node_modules\mcp-remote\dist\proxy.js"

    These commands confirm the exact filesystem location of the proxy.js script installed with mcp-remote. The output should display the full path to proxy.js. This path must be provided as the first argument in the Claude Desktop configuration file.

    Record both file paths exactly. These values are required in the Claude Desktop configuration file.

Part 2 – Configure Claude Desktop​

  1. Locate the Claude Desktop Configuration File​

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

    This file defines which MCP servers Claude Desktop connects to. If the file does not exist, create it manually.

  2. Update the MCP Configuration​

    Update the configuration file to point to your local MCP Server via mcp-remote.

    macOS Example​
    {
      "mcpServers": {
        "hyperstack-mcp": {
          "command": "/usr/local/bin/node",
          "args": [
            "/usr/local/lib/node_modules/mcp-remote/dist/proxy.js",
            "http://127.0.0.1:8080/mcp"
          ]
        }
      }
    }
    macOS (nvm) Example​

    If you installed Node.js using nvm, your Node executable will not be located in /usr/local/bin. Instead, it will reside inside your nvm directory (for example: /Users/your-user/.nvm/versions/node/v18.x.x/bin/node).

    Use the exact path returned by which node, and ensure the proxy.js path matches the global npm directory under your active nvm version (npm root -g).

    {
      "mcpServers": {
        "hyperstack-mcp": {
          "command": "/Users/your-user/.nvm/versions/node/v18.x.x/bin/node",
          "args": [
            "/Users/your-user/.nvm/versions/node/v18.x.x/lib/node_modules/mcp-remote/dist/proxy.js",
            "http://127.0.0.1:8080/mcp"
          ]
        }
      }
    }

    Ensure that:

    • The Node path exactly matches the output of which node.
    • The proxy.js path reflects the global npm directory for the active nvm version.

    Windows Example​
    {
      "mcpServers": {
        "hyperstack-mcp": {
          "command": "C:\\Program Files\\nodejs\\node.exe",
          "args": [
            "C:\\Users\\YOUR_USERNAME\\AppData\\Roaming\\npm\\node_modules\\mcp-remote\\dist\\proxy.js",
            "http://127.0.0.1:8080/mcp"
          ]
        }
      }
    }
    Linux Example​
    {
      "mcpServers": {
        "hyperstack-mcp": {
          "command": "/usr/bin/node",
          "args": [
            "/usr/lib/node_modules/mcp-remote/dist/proxy.js",
            "http://127.0.0.1:8080/mcp"
          ]
        }
      }
    }

    In this configuration:

    • command specifies the absolute path to the Node.js executable.
    • The first value in args is the absolute path to proxy.js.
    • The second value in args is the MCP Server endpoint (http://127.0.0.1:8080/mcp).

    Ensure that:

    • All file paths match the values discovered in Part 1.
    • Forward slashes (/) are used on macOS/Linux.
    • Escaped backslashes (\\) are used in Windows JSON paths.

  3. Restart Claude Desktop​

    Fully quit Claude Desktop and reopen it. This ensures the updated MCP configuration is loaded.

  4. Validate the Connection​

    Enter the following prompt inside Claude Desktop:

    Show me the available tools

    This prompt instructs Claude Desktop to query the connected MCP Server and retrieve the list of exposed tools. If configured correctly, Claude will return the available MCP operations without errors.

Troubleshooting​

If Claude Desktop does not connect successfully:

  • Verify the MCP Server health endpoint.
  • Confirm Node.js and mcp-remote are installed globally.
  • Double-check all file paths in claude_desktop_config.json.
  • Ensure the MCP endpoint URL is http://127.0.0.1:8080/mcp.

For comprehensive troubleshooting guidance, see the MCP Server Troubleshooting Guide.


Back to top

On this page