Hyperstruck

Install the MCP server

Add Hyperstruck's hosted MCP server to Claude Code, Claude, Cursor, VS Code or Codex, signing in with OAuth or using an API key.

In short

Pick how you sign in, copy the configuration, and add it to your host. OAuth is the default: you sign in to Hyperstruck in the browser the first time the host connects, and there is no key to paste or rotate. Use an API key for scripts, CI and hosts that cannot sign in.

Two addresses, one server

The server has two addresses. They serve the same tools; they differ only in how you sign in.

Sign in withAddressWhat you need
OAuth (recommended)https://mcp.hyperstruck.com/mcpA Hyperstruck login. The host opens a browser to sign in the first time it connects
API keyhttps://mcp.hyperstruck.com/mcp-keyA Hyperstruck API key, sent as Authorization: Bearer <key>

The configuration

Most hosts read the same mcpServers JSON. Copy the one for how you sign in, with the copy button at the top right of the block, and paste it into your host's MCP settings. The tab you pick here is used for every host below.

mcp.json
{
  "mcpServers": {
    "hyperstruck": {
      "type": "http",
      "url": "https://mcp.hyperstruck.com/mcp"
    }
  }
}

No key goes in the file. When the host first connects, it opens Hyperstruck's sign-in page; sign in and it is connected.

mcp.json
{
  "mcpServers": {
    "hyperstruck": {
      "type": "http",
      "url": "https://mcp.hyperstruck.com/mcp-key",
      "headers": {
        "Authorization": "Bearer <YOUR_HYPERSTRUCK_API_KEY>"
      }
    }
  }
}

Replace <YOUR_HYPERSTRUCK_API_KEY> with your key. The key needs the scopes for the tools you call; for the learning loop, use one with agents:write. Keep the file out of source control.

Add it to your host

Claude Code

claude mcp add --transport http hyperstruck https://mcp.hyperstruck.com/mcp --scope user

Start a session, run /mcp, choose hyperstruck and then Authenticate. Claude Code opens the browser for you to sign in.

claude mcp add --transport http hyperstruck https://mcp.hyperstruck.com/mcp-key \
  --header "Authorization: Bearer <YOUR_HYPERSTRUCK_API_KEY>" \
  --scope user

--scope user makes it available in every project; use --scope local for just the current one, or --scope project to share it with your team through the repository's .mcp.json. Check it connected with claude mcp list, and run /mcp in a session to see the tools.

Claude desktop and claude.ai

  1. Open Settings, then Connectors.
  2. Choose Add custom connector.
  3. Name it Hyperstruck and set the URL to https://mcp.hyperstruck.com/mcp.
  4. Choose Add, then Connect, and sign in to Hyperstruck in the window that opens.

On a Team or Enterprise plan, an owner adds the connector for the organization first; each member then connects and signs in.

Custom connectors in Claude cannot send an Authorization header, so use OAuth here. To use a key from your own machine, use Claude Code instead.

Cursor

Add this to ~/.cursor/mcp.json for every project, or .cursor/mcp.json for one:

~/.cursor/mcp.json
{
  "mcpServers": {
    "hyperstruck": {
      "url": "https://mcp.hyperstruck.com/mcp"
    }
  }
}

Then find hyperstruck in Cursor's MCP settings (Customize, then MCPs, or Cursor Settings, then Tools & MCP in older versions) and choose Connect where it says Needs login.

~/.cursor/mcp.json
{
  "mcpServers": {
    "hyperstruck": {
      "url": "https://mcp.hyperstruck.com/mcp-key",
      "headers": {
        "Authorization": "Bearer <YOUR_HYPERSTRUCK_API_KEY>"
      }
    }
  }
}

In Cursor's MCP settings (Customize, then MCPs, or Cursor Settings, then Tools & MCP in older versions), the server shows green with its tools listed when it is connected.

VS Code (GitHub Copilot)

Add this to .vscode/mcp.json in your workspace, or run MCP: Open User Configuration from the Command Palette to add it for every workspace:

.vscode/mcp.json
{
  "servers": {
    "hyperstruck": {
      "type": "http",
      "url": "https://mcp.hyperstruck.com/mcp"
    }
  }
}

Choose Start above the server entry, and allow VS Code to sign in when it asks.

VS Code prompts for the key once and stores it securely, so it never sits in the file:

.vscode/mcp.json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "hyperstruck-api-key",
      "description": "Hyperstruck API key",
      "password": true
    }
  ],
  "servers": {
    "hyperstruck": {
      "type": "http",
      "url": "https://mcp.hyperstruck.com/mcp-key",
      "headers": {
        "Authorization": "Bearer ${input:hyperstruck-api-key}"
      }
    }
  }
}

Use the tools from Copilot Chat in Agent mode; the tools button lists them under hyperstruck.

Codex

codex mcp add hyperstruck --url https://mcp.hyperstruck.com/mcp

Codex opens the browser to sign in. If it doesn't, run codex mcp login hyperstruck.

Codex reads the key from an environment variable, so it never sits in the config:

export HYPERSTRUCK_API_KEY=<YOUR_HYPERSTRUCK_API_KEY>
codex mcp add hyperstruck --url https://mcp.hyperstruck.com/mcp-key \
  --bearer-token-env-var HYPERSTRUCK_API_KEY

Run codex mcp list to check it was added. The same server is shared by the Codex CLI and the Codex IDE extension, through ~/.codex/config.toml.

Any other host

Any host that supports remote MCP servers over streamable HTTP can connect. Use https://mcp.hyperstruck.com/mcp if it can sign in with OAuth, or https://mcp.hyperstruck.com/mcp-key with the header Authorization: Bearer <YOUR_HYPERSTRUCK_API_KEY> if it can send a custom header. A host that can do neither is not supported.

Name the agent

The learning loop tools (resolve, complete_run and distill) use the agent named by the X-Hyperstruck-Agent-Name header, or default when you send none. To keep one tool's learnings apart, add the header to the same headers object as the URL. With an API key, it sits beside Authorization in one object; a second headers key would replace the first and drop the key:

"headers": {
  "Authorization": "Bearer <YOUR_HYPERSTRUCK_API_KEY>",
  "X-Hyperstruck-Agent-Name": "support-bot"
}

In Claude Code, add --header "X-Hyperstruck-Agent-Name: support-bot" to claude mcp add. Custom connectors in Claude desktop and claude.ai cannot set headers, so they always use default.

An agent with a new name is created the first time it is used, which needs agents:write. See Which agent the tools use.

If it does not connect

You seeWhat to do
The sign-in page never opensReconnect or toggle the server in the host so it fetches the sign-in details again
401 after signing inDisconnect the server in the host, check the URL is https://mcp.hyperstruck.com/mcp, and sign in again
401 with an API keyCheck the key is current, the URL ends in /mcp-key, and the header reads Bearer then the key
403The login or key lacks a scope the tool needs, the subscription is not active, or your sign-in organization is not linked to a Hyperstruck account. See Authentication
503Hyperstruck could not verify your sign-in or plan. Try again shortly
429The key or login is over its rate. Wait a minute and try again