MCP Server

Introduction

The HyperTrack MCP server provides a set of tools that AI assistants can use to query your HyperTrack account. Ask "where is worker John?" or "how many orders are running late?" and the assistant reads live data from your account instead of guessing.

The server implements the Model Context Protocol, an open standard for connecting AI assistants to external systems. Any MCP-capable client can connect to it, including Claude Desktop, Claude Code, Cursor, VS Code, and custom agents.

This page covers connecting a client to the server. If you want your coding agent to write the integration itself, see Agent Skills instead.

What the server can do

Every tool on the server is read-only. The server can read orders, workers, routes, places, devices, geotags, visits, geofences, and account usage. The complete set is listed in Available tools below.

The server cannot create, update, or delete anything. It will not assign an order, start tracking, or change a worker's status. Use the Orders API for those operations.

📘 The server is on version 0.1.x

The tool set is still growing and tool names may change between releases. If a tool you need is missing, write to us at help@hypertrack.com.

Get your credentials

Open the Setup page in the dashboard and copy your AccountID and SecretKey. The server needs both to authenticate to the HyperTrack API on your behalf.

Your SecretKey grants read access to your entire account, so treat it the way you would treat a password. Where your client supports it, keep the configuration file outside your project directory so the key does not end up in version control.

Connect your client

Claude Desktop

Add the following to ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, or %APPDATA%\Claude\claude_desktop_config.json on Windows, then restart Claude Desktop.

{
  "mcpServers": {
    "hypertrack": {
      "command": "npx",
      "args": ["-y", "@hypertrack/mcp-server"],
      "env": {
        "HYPERTRACK_ACCOUNT_ID": "your-account-id",
        "HYPERTRACK_SECRET_KEY": "your-secret-key"
      }
    }
  }
}

Claude Code

Run the following command, then run claude mcp list to confirm the server connected.

claude mcp add hypertrack \
  --env HYPERTRACK_ACCOUNT_ID=your-account-id \
  --env HYPERTRACK_SECRET_KEY=your-secret-key \
  -- npx -y @hypertrack/mcp-server

Cursor

Add the following to ~/.cursor/mcp.json to enable the server in all projects, or to .cursor/mcp.json to enable it in the current project only.

{
  "mcpServers": {
    "hypertrack": {
      "command": "npx",
      "args": ["-y", "@hypertrack/mcp-server"],
      "env": {
        "HYPERTRACK_ACCOUNT_ID": "your-account-id",
        "HYPERTRACK_SECRET_KEY": "your-secret-key"
      }
    }
  }
}

VS Code

Add the following to .vscode/mcp.json in your workspace.

{
  "servers": {
    "hypertrack": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@hypertrack/mcp-server"],
      "env": {
        "HYPERTRACK_ACCOUNT_ID": "your-account-id",
        "HYPERTRACK_SECRET_KEY": "your-secret-key"
      }
    }
  }
}

Other MCP clients

The server communicates over stdio. Point your client at npx -y @hypertrack/mcp-server with both environment variables set. Your client documentation will explain where its MCP configuration lives.

HTTP mode

If your client expects a network endpoint, or if you want to embed the server in your own dashboard, run it over Streamable HTTP instead.

HYPERTRACK_ACCOUNT_ID=your-account-id \
HYPERTRACK_SECRET_KEY=your-secret-key \
npx -y hypertrack-mcp-http

The server listens on http://127.0.0.1:3000/mcp and binds to localhost by default. The endpoint carries your account credentials and has no authentication of its own, so only set HOST=0.0.0.0 if you have understood that exposure.

Verify the connection

Ask your assistant the following question.

How many orders are active right now?

The assistant should answer with a count drawn from your account. If it reports that it has no HyperTrack tools available, the server did not start. Confirm that Node.js 18 or later is installed and that both environment variables are set.

Available tools

Orders

Workers

Routes

Places

Devices

Geotags

Visits

Geofences

Account

Example questions

Once the server is connected, you can ask your assistant questions like these.

• "How many orders are active right now?"
• "Show me all completed orders from today"
• "Where is worker John?"
• "What's the ETA for order ORD-123?"
• "List all devices that are currently tracking"
• "Show me the delivery geotags from this week"
• "What's our API usage this month?"
• "Find the closest workers to this order"

Configuration

The server requires Node.js 18 or later.

Security

Your SecretKey grants read access to the whole account. Anything the assistant can ask about, it can see, including worker locations, customer addresses, and order history. Give the key only to clients you trust.

Client configuration files that contain credentials are committed to version control by accident more often than you would expect. Add them to your .gitignore before you paste the key in.

If your assistant also reads untrusted content such as support tickets, emails, or web pages, that content can attempt to instruct the assistant to fetch your data and leak it elsewhere. Enable tool confirmation prompts in your client to reduce this risk. The read-only tool set is the main safeguard here, because a successful prompt injection can read your data but cannot cancel an order or reassign a worker.

Related

• Agent Skills teaches your coding agent how to build a HyperTrack integration.
• API Reference documents the underlying REST API.
• @hypertrack/mcp-server is published on npm.