Claude Desktop Setup

Connect Claude Desktop to the Hyperstack API MCP Server, natively for the hosted server or through the mcp-remote proxy for your own instance.

Claude Desktop reaches the hosted MCP Server natively over HTTP, as a custom connector, so there is nothing to install. Connecting to an instance you run yourself uses the mcp-remote proxy, which bridges Claude Desktop's configuration file to your server's endpoint.

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.

Choose your MCP endpoint

Claude Desktop can connect to either the Hyperstack-hosted MCP Server or an instance you run yourself. The two use different procedures, so choose your endpoint before you start.

Endpoint	URL	How Claude Desktop connects	Authentication
Hosted	`https://console.hyperstack.cloud/ai/mcp`	Custom connector, natively over HTTP	Your Hyperstack account, through your browser
Self-hosted	`http://127.0.0.1:8080/mcp`	The `mcp-remote` proxy, which requires Node.js	The API key you set on the server

Using Claude Code Instead

Claude Code also connects directly over HTTP, so it needs neither Node.js nor the mcp-remote proxy. See Claude Code in the connection guide.

Connect to the hosted MCP Server

Claude Desktop connects to the hosted server as a custom connector, so neither Node.js nor the mcp-remote proxy is required. The only prerequisite is the latest version of Claude Desktop.

Add the Custom Connector

a. Open Claude Desktop and go to Settings
b. Select Connectors
c. Click Add, then Add custom connector
d. In the Name field, enter a name for the server, for example Hyperstack
e. In the Remote MCP server URL field, enter the hosted URL
f. Click Add
Hosted MCP Server URL
```
https://console.hyperstack.cloud/ai/mcp
```
Authenticate

The connector now appears in the Connectors list. Click Connect to start the authentication flow.

Your browser opens the Hyperstack sign-in page. Sign in to your Hyperstack account and approve access, then return to Claude Desktop, where the connector is shown as connected. Claude Desktop stores the resulting credentials and renews them for you, so you sign in once.
Validate the Connection

Start a new chat and enter the following prompt:
```
Show me all hyperstack tools
```
This prompt instructs Claude Desktop to query the connected MCP Server and retrieve the list of exposed tools. If the connector is configured correctly, Claude returns the available MCP operations without errors.

Connect to a self-hosted instance

Claude Desktop reaches an instance you run yourself through the mcp-remote proxy, which requires Node.js. Both parts of this procedure must be completed for successful integration.

Prerequisites

Before you begin, ensure the following requirements are met:

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.
The MCP Server is running and accessible at http://127.0.0.1:8080. To install it, see the Local Installation Guide.

Part 1 – Prepare the Local Environment

Verify the MCP Server

Confirm that your instance is running and healthy.
terminalMCP 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:
json
```
{
  "status": "ok",
  "service": "hyperstack-mcp-server"
}
```
If the server does not respond, ensure it is running and that port 8080 is not in use by another service.
Install Node.js (if not already installed)

Verify your installed version:
terminal
```
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
Install mcp-remote

Install the MCP proxy package globally:
terminal
```
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.
Locate the Node.js Executable Path
- macOS / Linux:
  terminal
```
which node
```
- Windows:
  powershell
```
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.
Locate the mcp-remote Proxy Script
- macOS / Linux:
  terminal
```
ls -la $(npm root -g)/mcp-remote/dist/proxy.js
```
- Windows:
  powershell
```
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

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.
Update the MCP Configuration

Update the configuration file to point to your MCP Server via mcp-remote. Substitute your own server's URL wherever http://127.0.0.1:8080/mcp appears.

macOS Example
json
```
{
  "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).
json
```
{
  "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
json
```
{
  "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
json
```
{
  "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 your 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.
Restart Claude Desktop

Fully quit Claude Desktop and reopen it. This ensures the updated MCP configuration is loaded. A self-hosted instance authenticates with the API key you set on the server, so it does not prompt you to sign in.
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:

Confirm the MCP endpoint URL matches the server you intend to reach, https://console.hyperstack.cloud/ai/mcp for the hosted server.
Connecting to the hosted server, confirm the connector shows as connected in Settings → Connectors, and complete the browser sign-in if it does not.
Connecting to your own instance, verify the MCP Server health endpoint, confirm Node.js and mcp-remote are installed globally, and double-check all file paths in claude_desktop_config.json.

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

Hyperstack API MCP Server - Connection Guide: Connect an AI client to the hosted MCP Server and run your first request.
MCP Tools and Operations Reference: Every supported tool, grouped by domain, with example prompts.
Self-hosted MCP Server: Run your own instance when the hosted server does not fit, with its installation and configuration guides.
Troubleshooting Guide: Hosted sign-in problems, plus Docker, authentication, and client connectivity on your own instance.

Was this page helpful?

Choose your MCP endpoint​

Connect to the hosted MCP Server​

Add the Custom Connector​

Authenticate​

Validate the Connection​

Connect to a self-hosted instance​

Prerequisites​

Part 1 – Prepare the Local Environment​

Verify the MCP Server​

Install Node.js (if not already installed)​

Install mcp-remote​

Locate the Node.js Executable Path​

Locate the mcp-remote Proxy Script​

Part 2 – Configure Claude Desktop​

Locate the Claude Desktop Configuration File​

Update the MCP Configuration​

macOS Example​

macOS (nvm) Example​

Windows Example​

Linux Example​

Restart Claude Desktop​

Validate the Connection​

Troubleshooting​

Related Documentation​

Choose your MCP endpoint

Connect to the hosted MCP Server

Add the Custom Connector

Authenticate

Validate the Connection

Connect to a self-hosted instance

Prerequisites

Part 1 – Prepare the Local Environment

Verify the MCP Server

Install Node.js (if not already installed)

Install mcp-remote

Locate the Node.js Executable Path

Locate the mcp-remote Proxy Script

Part 2 – Configure Claude Desktop

Locate the Claude Desktop Configuration File

Update the MCP Configuration

macOS Example

macOS (nvm) Example

Windows Example

Linux Example

Restart Claude Desktop

Validate the Connection

Troubleshooting

Related Documentation