Hex MCP

🚀 Hex-MCP Server

A MCP server implemented for Hex, supporting the following tools:

• list_hex_projects: List available Hex projects.
• search_hex_projects: Search for Hex projects by pattern.
• get_hex_project: Get detailed information about a specific project.
• get_hex_run_status: Check the running status of a project.
• get_hex_project_runs: Get the running history of a project.
• run_hex_project: Execute a Hex project.
• cancel_hex_run: Cancel a running project.

🚀 Quick Start

📦 Installation

The recommended way to install is using uv:

uv add hex-mcp

Alternatively, you can use pip:

pip install hex-mcp

To confirm if it works properly, use the following command:

hex-mcp --version

⚙️ Configuration

Using the config command (Recommended)

Configure hex-mcp using the config command, passing your API key and API URL (optional, default is https://app.hex.tech/api/v1):

hex-mcp config --api-key "your_hex_api_key" --api-url "https://app.hex.tech/api/v1"

⚠️ Important Note

This will save the configuration to a file in your user directory (e.g., ~/.hex-mcp/config.yml), making it available for all hex-mcp calls.

Using Environment Variables

Alternatively, the Hex MCP server can also be configured through environment variables:

• HEX_API_KEY: Your Hex API key.
• HEX_API_URL: The base URL of the Hex API.

When setting the environment variables for the MCP server in Cursor, they need to be globally available or passed using the --env-file flag of uv when invoking the server.

💻 Usage with Cursor

Cursor allows AI agents to interact with Hex through the MCP protocol. Follow these steps to set up and use hex-mcp with Cursor:

Create a .cursor/mcp.json file in the project root directory with the following content:

{
  "mcpServers": {
    "hex-mcp": {
      "command": "uv",
      "args": ["run", "hex-mcp", "run"]
    }
  }
}

Or, if the hex-mcp command is in your PATH, you can use it directly:

{
  "mcpServers": {
    "hex-mcp": {
      "command": "hex-mcp",
      "args": ["run"]
    }
  }
}

Once it's up and running, you can use it in Cursor by starting a new AI (agent) conversation and asking it to list or run Hex projects.

⚠️ Important Note

The MCP server and CLI are still under development, and there may be breaking changes.