Hex

You can install and run a Hex MCP server to orchestrate, monitor, and manage access to Hex projects, cells, collections, and data connections from external systems or scripts. This server enables automated project runs, run status checks, content access for SQL and CODE cells, and programmatic permission management across workspaces and collections.

How to use

You will interact with the MCP server through a client or automation tool that communicates via the MCP protocol. Typical usage patterns include listing projects, triggering project runs, checking run status, reading cell SQL and CODE sources, updating cell content, and managing sharing and collection structures. You can integrate these actions into external orchestration systems (for example, CI/CD pipelines or Airflow DAGs) or automate routine governance tasks across your Hex workspace.

How to install

Prerequisites: you need Python installed and a running network path to access Hex via its API. You will install the MCP server package and optionally install a client tool to run the MCP server locally.

# Install the MCP server package using uv (recommended)
uv add hex-mcp

# Or install via pip if you prefer Python tooling
pip install hex-mcp

# Verify the MCP server is installed and accessible
hex-mcp --version

Configuration

Configure the MCP server to connect to your Hex instance. You can configure via the command line to supply your Hex API key and base URL, or set environment variables for persistent use.

# Recommended configuration by command
hex-mcp config --api-key "your_hex_api_key" --api-url "https://app.hex.tech/api/v1"

Configuration is saved to a file in your home directory (for example, ~/.hex-mcp/config.yml) and is used by all hex-mcp invocations.

# Alternative: use environment variables
export HEX_API_KEY=your_hex_api_key
export HEX_API_URL=https://app.hex.tech/api/v1

Using with Cursor

Cursor can interact with Hex through the MCP protocol by using a dedicated MCP server entry. You can define the MCP server in a project’s Cursor configuration to enable AI agents to list or run Hex projects.

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

Alternatively, you can run the MCP server directly if it is on your PATH.

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

Usage examples

The MCP server exposes endpoints to list and manage Hex projects, execute runs, read notebook cells, and manage permissions and collections. You can wire these endpoints into scripts or automation to orchestrate Hex workloads, migrate content, or enforce governance across the workspace.

Configuration details and security notes

Security considerations: protect your API key and control who can run MCP commands. Use workspace-level access controls and limit permissions to only what is necessary for automation.

Troubleshooting

If you encounter connection issues, verify that your API key and API URL are correct, the MCP server process is running, and outbound network access to Hex is allowed.

Available tools

list_hex_projects

List available Hex projects in the workspace.

search_hex_projects

Search Hex projects by pattern across workspaces.

get_hex_project

Get detailed information about a specific Hex project.

run_hex_project

Execute a Hex project run.

get_hex_run_status

Check the status of a running Hex project.

get_hex_project_runs

Retrieve the run history for a project.

cancel_hex_run

Cancel an ongoing Hex project run.

list_hex_cells

List cells in a Hex project and read contents for SQL and CODE cells.

update_hex_cell

Update SQL or CODE cell content and data connections.

update_hex_project_user_sharing

Grant or revoke user access to a Hex project.

update_hex_project_group_sharing

Grant or revoke group access to a Hex project.

update_hex_project_collection_sharing

Add or remove projects from collections.

update_hex_project_workspace_sharing

Manage workspace-wide and public access to projects.

list_hex_collections

List all collections in the workspace.

get_hex_collection

Get details about a specific collection including sharing.

create_hex_collection

Create a new collection with optional sharing.

update_hex_collection

Update collection name, description, or sharing.

list_hex_groups

List all groups in the workspace.

get_hex_group

Get details about a specific group.

create_hex_group

Create a new group with optional initial members.

update_hex_group

Update group name or membership (add/remove up to 100 users).

delete_hex_group

Delete a group from the workspace.

list_hex_data_connections

List all data connections with pagination and sharing.

get_hex_data_connection

Get details about a specific data connection.

create_hex_data_connection

Create a new data connection for a warehouse or database.

update_hex_data_connection

Update connection configuration, credentials, and sharing.