---
title: "Connect Hex to ChatGPT: Manage Data Projects, Runs, and Cell Content"
slug: connect-hex-to-chatgpt-manage-data-projects-runs-and-cell-content
date: 2026-10-19
author: Nidhi KN
categories: ["AI & Agents"]
excerpt: "Learn how to connect Hex to ChatGPT using a managed MCP server. A complete engineering guide to automating project runs, cell contents, and data pipelines."
tldr: "Connect Hex to ChatGPT by generating a secure, managed MCP server via Truto. This guide covers how to handle Hex's asynchronous project runs, polymorphic cell contents, and complex data workspace operations."
canonical: https://truto.one/blog/connect-hex-to-chatgpt-manage-data-projects-runs-and-cell-content/
---

# Connect Hex to ChatGPT: Manage Data Projects, Runs, and Cell Content


If you need to connect Hex to ChatGPT to automate data workspaces, orchestrate complex project runs, or manage cell-level notebook content, you need a [Model Context Protocol (MCP) server](https://truto.one/what-is-mcp-model-context-protocol-the-2026-guide-for-saas-pms/). This server acts as the translation layer between ChatGPT's tool-calling logic and the highly structured Hex REST API. You can either spend weeks building, hosting, and maintaining a [custom MCP proxy](https://truto.one/how-to-build-mcp-servers-for-ai-agents-2026-hands-on-architecture-guide/), or you can use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL.

If your team uses Claude, check out our guide on [connecting Hex to Claude](https://truto.one/connect-hex-to-claude-control-data-connections-and-project-sharing/) or explore our broader architectural overview on [connecting Hex to AI Agents](https://truto.one/connect-hex-to-ai-agents-orchestrate-project-runs-and-agent-threads/).

Giving a Large Language Model (LLM) read and write access to a collaborative data science platform like Hex is an enormous engineering challenge. You have to handle polymorphic cell schemas, asynchronous project runs, and deeply nested sharing configurations. Every time an analyst adds a new dataset or modifies a compute profile, your custom integration layer must handle the state changes gracefully. 

This guide breaks down exactly how to use Truto to generate a secure, [managed MCP server for Hex](https://truto.one/auto-generated-mcp-tools-for-ai-agents-a-2026-architecture-guide/), connect it natively to ChatGPT, and execute complex data operations using natural language.

> Stop writing boilerplate API integration code. Let Truto generate secure, managed MCP servers for your AI agents in seconds.
>
> [Talk to us](https://truto.one/book-a-demo/)

## The Engineering Reality of the Hex API

Building a custom MCP server is essentially [building and self-hosting an integration layer](https://truto.one/what-is-mcp-and-mcp-servers-and-how-do-they-work/). While the open MCP standard provides a predictable way for models to discover tools, implementing it against Hex's API is exceptionally painful due to domain-specific complexities. 

If you decide to build a custom MCP server for Hex, you own the entire API lifecycle. Here are the specific integration challenges that break standard CRUD assumptions when working with Hex:

### Polymorphic Cell Contents
The Hex API allows you to read, create, and update individual cells within a draft notebook session. However, the cell contents are polymorphic. When sending a payload to create or update a cell, the `contents` field must be strictly wrapped by the cell type: `{"codeCell": {"source": "..."}}`, `{"sqlCell": {"source": "...", "dataConnectionId": "..."}}`, or `{"markdownCell": {"source": "..."}}`. An LLM naturally struggles with this level of nested discrimination. If your MCP server does not expose these constraints perfectly via JSON Schema, ChatGPT will hallucinate flat JSON structures, resulting in HTTP 400 validation errors.

### Asynchronous Runs and Threads
Unlike typical synchronous REST APIs, Hex leans heavily on asynchronous execution. When you trigger a project run or start a Hex agent thread, the API immediately returns a 202 Accepted status with a `runId` or `threadId`. The operation is now running in the background. Your LLM must know that it cannot simply wait for the data in a single turn. It has to invoke the creation tool, parse the ID, and then deliberately loop and poll a separate status endpoint until the state switches from `RUNNING` to `COMPLETED` or `ERROR`. Orchestrating this state machine purely via prompt instructions requires highly descriptive, tightly scoped MCP tool definitions.

### Atomic Bulk Updates for Sharing
Hex manages sharing and permissions via bulk update endpoints. When modifying user, group, or workspace sharing, the API expects an array of updates. The catch is that these endpoints are strictly atomic: if a single permission update in a batch of 25 fails validation (e.g., passing an invalid user ID or an unrecognized enum like `CAN_VIEW`), the entire request is rejected and no changes are applied. When an LLM generates these bulk payloads, it is highly prone to hallucinating enums or fabricating IDs. Your MCP server must enforce strict enum validation in the generated schemas before passing the request to Hex.

### Rate Limits and Pagination Rigidity
Hex enforces strict rate limits on API calls. When working with LLMs, iterative looping over paginated endpoints (like listing all project runs) can quickly exhaust these limits. 

**Factual note on rate limits:** Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Hex API returns an HTTP 429, Truto passes that error directly to the caller. Truto normalizes upstream rate limit info into standardized headers (`ratelimit-limit`, `ratelimit-remaining`, `ratelimit-reset`) per the IETF spec. The client is responsible for all retry and backoff logic. Truto will not automatically absorb rate limit errors.

## Creating the Hex MCP Server

With Truto, you bypass the need to write schema parsers, manage OAuth tokens, or host custom JSON-RPC endpoints. You connect the Hex account once, and Truto dynamically generates the MCP server URL based on the integration's underlying documentation and resources.

You can create this server in two ways: via the Truto UI or programmatically via the API.

### Method 1: Via the Truto UI

For ad-hoc internal tools or testing, the dashboard is the fastest route.

1. Log into your Truto account and navigate to the **Integrated Accounts** page for your Hex connection.
2. Click on the **MCP Servers** tab.
3. Click **Create MCP Server**.
4. Define your configuration. You can specify a human-readable name, select allowed methods (e.g., filtering for `read` only), and select specific tags to restrict the tool surface area.
5. Click Save and copy the generated MCP server URL (it will look like `https://api.truto.one/mcp/<secure_token>`).

### Method 2: Via the Truto API

If you are building an application where you need to programmatically provision Hex access for your own users, you should use the API. This single POST call validates that the Hex integration has tools available, generates a secure cryptographic token, stores it, and returns the ready-to-use URL.

```bash
curl -X POST https://api.truto.one/integrated-account/<INTEGRATED_ACCOUNT_ID>/mcp \
  -H "Authorization: Bearer $TRUTO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hex Data Ops for ChatGPT",
    "config": {
      "methods": ["read", "write", "custom"],
      "tags": ["projects", "runs", "cells"]
    }
  }'
```

The response will contain the exact URL you need to hand to ChatGPT:

```json
{
  "id": "mcp_srv_9x8y7z6",
  "name": "Hex Data Ops for ChatGPT",
  "config": {
    "methods": ["read", "write", "custom"],
    "tags": ["projects", "runs", "cells"]
  },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f6..."
}
```

That URL alone is enough to authenticate and serve JSON-RPC 2.0 tools. The token in the URL cryptographically encodes which specific Hex workspace to query and exactly which tools to expose.

## Connecting the MCP Server to ChatGPT

Once you have your Truto MCP URL, you need to register it with your ChatGPT environment. You can do this visually through the ChatGPT UI or via a local configuration file for programmatic agent setups.

### Method A: Via the ChatGPT UI

If you are using ChatGPT Pro, Plus, Business, Enterprise, or Education accounts, you can add custom connectors directly in the interface.

1. In ChatGPT, navigate to **Settings -> Apps -> Advanced settings**.
2. Enable **Developer mode** (MCP support is gated behind this setting).
3. Under **MCP servers / Custom connectors**, click to add a new server.
4. Enter a Name (e.g., "Hex Workspaces").
5. Paste your Truto MCP server URL into the **Server URL** field.
6. Click **Save**.

ChatGPT will immediately ping the server, run the MCP handshake, request `tools/list`, and populate its context window with the available Hex tools.

### Method B: Via Manual Config File

If you are integrating this into a headless architecture, a LangChain script, or using the official MCP CLI tooling, you can connect to the server using the standard Server-Sent Events (SSE) transport adapter.

Create an `mcp-config.json` file:

```json
{
  "mcpServers": {
    "hex_data_ops": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "--url",
        "https://api.truto.one/mcp/a1b2c3d4e5f6..."
      ]
    }
  }
}
```

Your agent framework will use this config to establish a persistent connection to the Truto proxy, dynamically discovering the schemas required to execute tasks against Hex.

## Hex Hero Tools for AI Agents

Truto dynamically generates tools for Hex based directly on the integration's documentation and resource configuration. When ChatGPT requests the tool list, it receives strict JSON schemas outlining exactly how to construct queries and request bodies. 

Here are the most powerful operations you can expose to an LLM.

### Trigger a Project Run
**Tool name:** `create_a_hex_project_run`

To execute complex data pipelines, ChatGPT needs to trigger project runs. This tool initiates a run on the latest published version of a Hex project. 

*Usage Note:* This returns a 202 response containing the `runId`, `runUrl`, and `projectId`. The LLM must capture the `runId` from this response to check the status later. It does not return the final data output.

> "Trigger a run for the 'Monthly Financial Rollup' Hex project (id: proj_123) and let me know the run ID so we can track it."

### Poll Project Run Status
**Tool name:** `get_single_hex_project_run_by_id`

Because project execution is asynchronous, this tool is critical. It allows ChatGPT to check if a previously triggered run has finished.

*Usage Note:* Requires both the `id` (the run ID) and the `project_id`. The LLM will parse the `status` field (e.g., COMPLETED, ERRORED, RUNNING) and the `elapsedTime` to determine if it should query again or proceed with the workflow.

> "Check the status of run 'run_456' for project 'proj_123'. If it is completed, tell me the elapsed time."

### List Queried Tables for Dependency Analysis
**Tool name:** `list_all_hex_project_queried_tables`

If you need an AI agent to perform impact analysis before dropping a data warehouse table, this tool lists exactly which warehouse tables are actively queried by a specific Hex project.

*Usage Note:* Returns a paginated list of `dataConnectionId`, `dataConnectionName`, and `tableName`. LLMs can use this to map lineage between Snowflake/BigQuery and Hex logic.

> "List all the warehouse tables queried by project 'proj_123'. I need to know if it relies on the 'dim_users' table."

### Retrieve Chart Images
**Tool name:** `get_single_hex_cell_image_by_id`

ChatGPT can actually pull visual data out of Hex. This tool fetches a rendered PNG image of a specific chart cell from the active draft notebook session.

*Usage Note:* Only executed, non-error chart cells are supported. The endpoint returns a base64 encoded string (`imageBase64`). ChatGPT can render or analyze this image natively using its vision capabilities.

> "Fetch the rendered image for the revenue forecast chart cell (id: cell_890) and summarize the visual trend for the last quarter."

### Update Project Sharing
**Tool name:** `hex_sharing_users_bulk_update`

This tool gives ChatGPT administrative control over who can view or edit a project. It updates project sharing access for specific users in bulk.

*Usage Note:* The `sharing` array must specify the exact access level enum (`CAN_VIEW`, `APP_ONLY`, `CAN_EDIT`, `FULL_ACCESS`) or `NONE` to remove access. Max 25 users per request. If any user ID is invalid, the entire batch fails.

> "Update the sharing settings for project 'proj_123'. Grant 'CAN_EDIT' access to user ID 'usr_789' and remove access for user ID 'usr_999'."

### Start an Agent Thread
**Tool name:** `create_a_hex_thread`

Hex has its own internal agent capabilities for contextual data analysis. You can have ChatGPT orchestrate Hex's own agent by starting a thread with a specific prompt.

*Usage Note:* Pass the `prompt` string. This runs asynchronously. It returns a `threadId` and a `url`. ChatGPT will need to follow up or poll a thread status endpoint to read the Hex agent's reply.

> "Start a Hex agent thread asking it to analyze the anomalies in the latest daily active user dataset, and give me the thread ID."

*For the complete inventory of available Hex tools and their full JSON schemas, visit the [Hex integration page](https://truto.one/integrations/detail/hex).* 

## Workflows in Action

Connecting tools together is where MCP servers show their true value. Instead of forcing users to click through the Hex UI, ChatGPT can orchestrate multi-step data workflows autonomously.

### Scenario 1: The Data Lead Triggering End-of-Month Reports
Data leaders often need to force-refresh specific dashboards and verify the output before notifying stakeholders. 

> "Run the End of Month Revenue project (id: proj_123). Wait for it to finish, then grab the rendered image of the final revenue chart (cell_890) so I can review it."

**Step-by-step Execution:**
1. **`create_a_hex_project_run`**: ChatGPT triggers the execution pipeline and extracts the `runId` from the 202 Accepted response.
2. **`get_single_hex_project_run_by_id`**: ChatGPT enters a loop, calling this tool to poll the status. It sees `RUNNING`, waits, and checks again until it reads `COMPLETED`.
3. **`get_single_hex_cell_image_by_id`**: Knowing the run is finished, ChatGPT requests the chart image for `cell_890`, receives the base64 string, and renders the visual output directly in the chat window for the user to verify.

### Scenario 2: The Analytics Admin Auditing and Provisioning Access
When new analysts join a team, or when sensitive datasets are involved, administrators need to quickly adjust workspace permissions without navigating complex settings menus.

> "Check which warehouse tables the 'Q3 Financials' project (id: proj_444) queries. If it touches the 'secure_payroll' table, remove access for user 'usr_999' immediately."

**Step-by-step Execution:**
1. **`list_all_hex_project_queried_tables`**: ChatGPT queries the project dependencies and receives an array of table names.
2. **Analysis**: ChatGPT inspects the array, finds `secure_payroll`, and determines that the condition is met.
3. **`hex_sharing_users_bulk_update`**: ChatGPT constructs a bulk payload targeting `proj_444`, setting the sharing access for `usr_999` to `NONE`, effectively revoking their permissions atomically.

```mermaid
sequenceDiagram
    participant User
    participant ChatGPT
    participant TrutoMCP as Truto MCP Server
    participant HexAPI as Hex API

    User->>ChatGPT: "If proj_444 queries 'secure_payroll', remove usr_999."
    ChatGPT->>TrutoMCP: Call list_all_hex_project_queried_tables(proj_444)
    TrutoMCP->>HexAPI: GET /api/v1/projects/proj_444/queried-tables
    HexAPI-->>TrutoMCP: Returns ["public.users", "public.secure_payroll"]
    TrutoMCP-->>ChatGPT: Validates schema, returns JSON array
    ChatGPT->>TrutoMCP: Call hex_sharing_users_bulk_update(proj_444, NONE)
    TrutoMCP->>HexAPI: POST /api/v1/projects/proj_444/sharing/users
    HexAPI-->>TrutoMCP: 200 OK (Access Revoked)
    TrutoMCP-->>ChatGPT: Returns updated project sharing state
    ChatGPT-->>User: "Access for usr_999 has been successfully revoked."
```

## Security and Access Control

Giving an AI agent access to a platform that can run arbitrary SQL against your data warehouse requires rigid security controls. Truto's MCP architecture provides multiple layers of defense:

*   **Method Filtering**: When generating the MCP server, you can pass `config: { methods: ["read"] }`. This restricts the LLM entirely. It can query project data and poll runs, but any attempt to call `create` or `update` tools (like editing a cell or changing permissions) is structurally blocked at the proxy layer.
*   **Tag Filtering**: You can scope the server to specific functional areas using tags. For example, `config: { tags: ["projects", "runs"] }` ensures the LLM cannot see or access the API endpoints for user administration or group sharing.
*   **Time-to-Live (TTL)**: By providing an `expires_at` ISO datetime when generating the server, Truto will automatically destroy the MCP token and terminate access at the exact millisecond requested. This is ideal for granting an AI agent temporary, session-based access to Hex.
*   **API Token Enformcement**: For zero-trust environments, setting `require_api_token_auth: true` ensures that possessing the MCP URL is not enough. The connecting client (e.g., a custom LangChain backend) must also inject a valid Truto API bearer token in the headers to execute tools.

## Move Faster with Managed MCP Servers

Connecting Hex to ChatGPT should not require you to build a custom schema translation layer, implement async polling safeguards, or host a dedicated proxy application. Hex's API is powerful, but its complexity around polymorphic payloads and asynchronous runs makes it hostile to raw LLM interactions.

By leveraging Truto's SuperAI MCP Server, you offload the entire integration lifecycle. Truto translates the upstream documentation into perfect JSON-RPC 2.0 schemas, normalizes error handling and rate limit headers, and routes requests securely. You spend zero time maintaining integration infrastructure, and all your time actually building autonomous AI workflows for your data teams.