MCP Server

Run the mcp-hyperspeed stdio MCP server to expose Hyperspeed tools to Cursor, Claude, and other MCP-compatible AI coding assistants.

mcp-hyperspeed is a stdio JSON-RPC MCP server that proxies tool calls from an AI coding assistant to the Hyperspeed API. It lets Cursor, Claude Desktop, or any other MCP-compatible client invoke Hyperspeed’s agent tools — such as reading files, searching chat, and proposing patches — directly from the AI’s tool-calling loop.

Requirements

You need three environment variables before starting the server:

Variable	Description
HYPERSPEED_API_URL	Base URL of your Hyperspeed API, e.g. http://localhost:8080 or https://hyperspeed.example.com
HYPERSPEED_TOKEN	A service account token (sa_…) with appropriate permissions. Create one in Workspace Settings → AI Staff.
HYPERSPEED_ORG_ID	Your organization UUID, visible in Workspace Settings.

The server exits immediately if any of these variables are missing or empty.

Running the server

1. Build or run from source

   From the repository root, run the server directly:

   HYPERSPEED_API_URL=http://localhost:8080 \
   HYPERSPEED_TOKEN=sa_... \
   HYPERSPEED_ORG_ID=<your-org-uuid> \
   go run ./apps/api/cmd/mcp-hyperspeed
   

   Or build a binary first:

   go build -o mcp-hyperspeed ./apps/api/cmd/mcp-hyperspeed
   

   Then run it:

   HYPERSPEED_API_URL=http://localhost:8080 \
   HYPERSPEED_TOKEN=sa_... \
   HYPERSPEED_ORG_ID=<your-org-uuid> \
   ./mcp-hyperspeed
   
2. Configure your MCP client

   Add mcp-hyperspeed as a server in your MCP client configuration. See the example configs below.

MCP protocol

The server speaks stdio JSON-RPC using the Model Context Protocol (protocol version 2024-11-05). It supports:

Method	Description
initialize	Handshake — returns server name, version, and capabilities.
tools/list	Fetches the list of available Hyperspeed tools from the API.
tools/call	Invokes a named tool with the provided arguments via the Hyperspeed API.

Any other method returns a method not found error. Notification messages (prefixed notifications/) are silently ignored.

Authentication

The server authenticates every API request with Authorization: Bearer <HYPERSPEED_TOKEN>. Use a service account token (sa_…) created from Workspace Settings → AI Staff.

The service account must have permission to access the tools it will invoke. For most use cases, the default system roles assigned at creation are sufficient.

A 401 or 403 response from the API means the token is invalid or the service account does not have access to the requested org. Check HYPERSPEED_TOKEN and HYPERSPEED_ORG_ID.

Optional: per-call metadata

You can pass control metadata to the server by including a _hyperspeed key in any tool’s arguments object. The server strips this key before forwarding arguments to the API.

{
  "_hyperspeed": {
    "mode": "agent",
    "session_id": "abc123"
  },
  "path": "src/main.go"
}

Supported fields:

Field	Values	Description
mode	ask, plan, agent	Invocation mode forwarded to the API.
session_id	string	Session identifier for grouping related tool calls.

Example client configuration

Cursor (mcp.json)

{
  "mcpServers": {
    "hyperspeed": {
      "command": "/path/to/mcp-hyperspeed",
      "env": {
        "HYPERSPEED_API_URL": "https://hyperspeed.example.com",
        "HYPERSPEED_TOKEN": "sa_...",
        "HYPERSPEED_ORG_ID": "<your-org-uuid>"
      }
    }
  }
}

Use a dedicated service account for each MCP client (e.g. one for Cursor, one for Claude). This gives you per-client audit trails and lets you rotate tokens independently.