Skip to main content

Connection Guide

The Hyperstack API MCP Server enables natural-language infrastructure management through MCP-compatible AI clients.

Instead of writing API calls by hand, you describe what you want in plain English, and the Hyperstack API MCP (Model Context Protocol) Server translates the request into an authenticated Hyperstack API operation.

This guide walks you through connecting an AI client to the Hyperstack-hosted MCP Server.

Warning: 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.

About the Hyperstack API MCP Server​

The MCP Server works with any MCP-compatible AI client, including Claude Code, Claude Desktop, and Open WebUI. It presents Hyperstack operations as tools your client can call, and turns each call into an authenticated request to the Hyperstack Infrahub API.

Once connected, you can:

  • Create and manage Virtual Machines
  • Provision and scale Kubernetes clusters
  • Create and attach Volumes
  • Retrieve Billing and usage information
  • Manage Environments
  • Execute multi-step infrastructure workflows

Connect to the hosted MCP Server​

Hyperstack hosts an MCP Server, so you can connect an AI client without installing or running anything yourself. Point your client at this URL:

Hosted MCP Server URL
https://console.hyperstack.cloud/ai/mcp

The hosted server authenticates you through your Hyperstack account. The first time a client connects, your browser opens the sign-in page. Once you sign in, the client receives its own credentials and every tool call runs against your account, so there is no API key to configure.

Claude Code​

Claude Code connects over HTTP, so it needs no proxy and no additional packages. Execute the following command to add the server:

terminalAdd the hosted MCP Server to Claude Code
claude mcp add --transport http hyperstack-mcp https://console.hyperstack.cloud/ai/mcp

The server is added at the local scope, which makes it available to you in the current project. Add --scope user to make it available across all your projects, or --scope project to share it with your team through a .mcp.json file.

Adding the server does not sign you in. To sign in, start a Claude Code session, run /mcp, select hyperstack-mcp, and complete the sign-in in the browser window that opens. Claude Code stores the resulting credentials and renews them for you, so you sign in once.

Execute the following command to confirm the connection:

terminalList configured MCP servers
claude mcp list

Until you have signed in, this command reports the server as needing authentication.

Claude Desktop​

Claude Desktop connects to the hosted server as a custom connector, natively over HTTP, so it needs no proxy and no additional packages.

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 https://console.hyperstack.cloud/ai/mcp, then click Add

The connector appears in the Connectors list. Click Connect to sign in, and complete the sign-in in the browser window that opens. Claude Desktop stores the resulting credentials and renews them for you, so you sign in once.

To confirm the connection, start a new chat and ask Claude to show you all Hyperstack tools.

Connecting Claude Desktop to an instance you run yourself uses the mcp-remote proxy instead. For that procedure, including the configuration file location for each operating system, see the Claude Desktop Setup Guide.

Open WebUI​

Open WebUI connects to the MCP Server as a tool server. If you do not already have Open WebUI running, start it with Docker:

terminalRun Open WebUI
docker run -d \
  -p 3000:3000 \
  -e PORT=3000 \
  --name open-webui \
  ghcr.io/open-webui/open-webui:main

Open WebUI is available at http://0.0.0.0:3000.

  1. Configure the MCP Server in Open WebUI​

    a. Navigate to Admin Panel, switch to the Settings tab, then select Integrations under Tools
    b. Click the + icon under External Tool Servers to add a new connection
    c. Click the Type toggle to change it from OpenAPI to MCP Streamable HTTP
    d. Set the API Base URL to https://console.hyperstack.cloud/ai/mcp
    e. Enter a Name. Leave ID as auto unless you need a specific value
    f. Set Auth to OAuth 2.1, so Open WebUI signs you in with your Hyperstack account
    g. Click Register Client. The badge beside it changes from Not Registered to Registered
    h. Click Save

    Register the client before you save

    Open WebUI refuses to save an MCP connection that uses OAuth 2.1 until you have registered the client, and the Authorize OAuth button stays disabled until the connection is saved. Complete these steps in order.

  2. Authorize Open WebUI​

    Reopen the connection you just saved and click Authorize OAuth. Your browser opens the Hyperstack sign-in page. Sign in and approve access, then return to Open WebUI. Open WebUI stores the resulting credentials and renews them for you, so you sign in once.

  3. Add an AI Studio Model​

    a. Navigate to Admin Panel → Settings → Connections
    b. Under OpenAI API, click + to add a new connection
    c. Set the server URL to https://console.hyperstack.cloud/ai/api/v1
    d. Add your Hyperstack API key under Authorization: Bearer <YOUR_API_KEY>
    e. (Optional) If you know the specific model you want to use, add it under Model IDs and click +
    f. Click Save

    After saving, the newly added model should be visible in the Chat section.

  4. Configure Function Calling and Enable MCP Tools​

    Once both the model and MCP server have been set up, complete the following steps within a New Chat session.

    a. Navigate to New Chat
    b. Toggle Controls and set Function Calling to Native
    c. Open Integrations → Tools and enable the MCP Server connection you configured

  5. Validate the Integration​

    If setup is successful, you should be able to:

    • See the newly added model available in chat
    • Enable the MCP tools for the session
    • Run prompts such as:
      • List all virtual machines in my account
      • Show current billing information
      • What environments are available?

    Open WebUI invokes the appropriate MCP tool through the Hyperstack API MCP Server and returns the results.

    Next Steps

    For a complete list of supported operations and additional example usage, see the full guide: MCP Tools and Operations Reference.

Run your own instance​

To run the MCP Server inside your own network, or to authenticate it with a single API key rather than per user, see the Local Installation Guide. That guide covers when to choose a self-hosted instance, how to run it with Docker, and how to point the clients above at it.

Troubleshooting​

If you encounter any issues:

  • Confirm the MCP connection URL is set to https://console.hyperstack.cloud/ai/mcp
  • Complete the sign-in in the browser window your client opens, and sign in with the Hyperstack account whose resources you want to manage
  • Confirm your client appears as connected, using claude mcp list in Claude Code or the tool server entry in Open WebUI

For detailed troubleshooting guidance, see the Troubleshooting Guide.

On this page