> ## Documentation Index
> Fetch the complete documentation index at: https://hyperspeed.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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. |

<Warning>
  The server exits immediately if any of these variables are missing or empty.
</Warning>

## Running the server

<Steps>
  <Step title="Build or run from source">
    From the repository root, run the server directly:

    ```bash theme={null}
    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:

    ```bash theme={null}
    go build -o mcp-hyperspeed ./apps/api/cmd/mcp-hyperspeed
    ```

    Then run it:

    ```bash theme={null}
    HYPERSPEED_API_URL=http://localhost:8080 \
    HYPERSPEED_TOKEN=sa_... \
    HYPERSPEED_ORG_ID=<your-org-uuid> \
    ./mcp-hyperspeed
    ```
  </Step>

  <Step title="Configure your MCP client">
    Add `mcp-hyperspeed` as a server in your MCP client configuration. See the example configs below.
  </Step>
</Steps>

## MCP protocol

The server speaks **stdio JSON-RPC** using the [Model Context Protocol](https://modelcontextprotocol.io) (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.

<Info>
  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`.
</Info>

## 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.

```json theme={null}
{
  "_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

<CodeGroup>
  ```json Cursor (mcp.json) theme={null}
  {
    "mcpServers": {
      "hyperspeed": {
        "command": "/path/to/mcp-hyperspeed",
        "env": {
          "HYPERSPEED_API_URL": "https://hyperspeed.example.com",
          "HYPERSPEED_TOKEN": "sa_...",
          "HYPERSPEED_ORG_ID": "<your-org-uuid>"
        }
      }
    }
  }
  ```

  ```json Claude Desktop (claude_desktop_config.json) theme={null}
  {
    "mcpServers": {
      "hyperspeed": {
        "command": "/path/to/mcp-hyperspeed",
        "env": {
          "HYPERSPEED_API_URL": "https://hyperspeed.example.com",
          "HYPERSPEED_TOKEN": "sa_...",
          "HYPERSPEED_ORG_ID": "<your-org-uuid>"
        }
      }
    }
  }
  ```

  ```json go run (development) theme={null}
  {
    "mcpServers": {
      "hyperspeed": {
        "command": "go",
        "args": ["run", "./apps/api/cmd/mcp-hyperspeed"],
        "env": {
          "HYPERSPEED_API_URL": "http://localhost:8080",
          "HYPERSPEED_TOKEN": "sa_...",
          "HYPERSPEED_ORG_ID": "<your-org-uuid>"
        }
      }
    }
  }
  ```
</CodeGroup>

<Tip>
  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.
</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.