Connect Hex to Claude: Control Data Connections and Project Sharing

If your data teams rely on Hex for collaborative analytics and data apps, connecting it to Claude transforms how you manage workspace infrastructure. Instead of manually navigating menus to update data connection credentials or bulk-updating project sharing permissions, you can instruct Claude to do it natively. To enable this, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's natural language tool calls and Hex's REST APIs.

You can either build and maintain this translation layer from scratch, dealing with stateful authentication and schema drift, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL.

If your team uses ChatGPT, check out our guide on connecting Hex to ChatGPT. For a broader architectural overview of agentic workflows in Hex, explore our guide on connecting Hex to AI Agents.

Giving a Large Language Model (LLM) read and write access to a sprawling data ecosystem like Hex is an engineering challenge. You have to map highly nested JSON schemas to MCP tool definitions, manage strict workspace access controls, and handle asynchronous execution states for analytical runs. Every time Hex updates an endpoint, your custom server has to be refactored, redeployed, and tested.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Hex, connect it natively to Claude, and execute complex workspace administration workflows using natural language.

The Engineering Reality of the Hex API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable JSON-RPC 2.0 handshake for models to discover tools, the reality of implementing it against specialized data APIs is painful. Hex is designed to isolate drafts, govern data connections strictly, and execute arbitrary analytical runs asynchronously. Its API reflects that complexity.

If you decide to build a custom Hex MCP server, here are the specific integration challenges you will face:

The Separation of Drafts, Published Versions, and Runs Hex projects do not operate as single monolithic entities. The API strictly separates the working draft of a project from its published state. If an LLM tries to query the SQL or Python contents of a project, it is querying the draft cells via /cells. However, when triggering an execution, you cannot "run a draft" via API—you trigger a run on the latest published version using the /project-runs resource. An LLM has no inherent context on this architectural split. Your integration layer must expose discrete tools that guide the model to interact with the correct state layer, preventing it from hallucinating that a draft edit automatically translates to the production app.

Asynchronous Execution and Polling When you instruct Hex to run a project, the operation is asynchronous. The create_a_hex_project_run endpoint returns a run ID and a status of RUNNING or QUEUED. An LLM cannot simply wait for the HTTP request to finish; the connection will time out. You must provide the model with a polling mechanism (e.g., get_single_hex_project_run_by_id) and explicitly instruct it via tool descriptions to check the status periodically until it resolves to COMPLETED or ERROR.

Atomic Bulk Updates for Sharing and Schemas Access control in Hex is highly granular. Updating project sharing or data connection schemas is handled via bulk update endpoints (e.g., hex_sharing_users_bulk_update). These endpoints enforce strict, atomic validation. If an LLM submits a batch request to update 10 users and one role enum is malformed (e.g., sending VIEWER instead of CAN_VIEW), the entire batch fails. There is no partial success. Your MCP server must strictly map and enforce these JSON schema constraints so the model understands exactly what enum values are permitted before it attempts a mutation.

How to Generate a Managed MCP Server for Hex

Rather than hand-coding a Node.js or Python MCP server to manage these API quirks, you can use Truto to generate one dynamically. Truto derives MCP tool definitions directly from Hex's API documentation and OpenAPI schemas, meaning tools are always up-to-date.

Each MCP server is scoped to a specific integrated Hex account and authenticated via a secure, cryptographically hashed token in the URL. There are two ways to generate this server.

Method 1: Via the Truto UI

For IT admins and operators, the simplest path is the dashboard:

1. Log in to your Truto environment.
2. Navigate to the Integrated Accounts page and select your active Hex connection.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Configure the server name, expiration time, and access filters (e.g., read-only).
6. Click Generate and copy the resulting MCP server URL (e.g., https://api.truto.one/mcp/a1b2c3d4...).

Method 2: Via the Truto API

For developers building programmatic agent workflows, you can generate MCP servers on the fly. This is ideal for provisioning short-lived servers for specific AI agent tasks.

Send a POST request to the /integrated-account/:id/mcp endpoint:

curl -X POST https://api.truto.one/api/integrated-account/YOUR_ACCOUNT_ID/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hex Infrastructure Admin Server",
    "config": {
      "methods": ["read", "write"],
      "tags": ["projects", "data_connections", "sharing"]
    },
    "expires_at": "2026-12-31T23:59:59Z"
  }'

The API responds with a secure URL backed by edge-distributed token storage.

A factual note on rate limits: Hex enforces API rate limits to protect workspace stability. Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Hex API returns an HTTP 429 (Too Many Requests), Truto passes that error directly to the caller (Claude). Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. The caller or agent framework is responsible for handling retry and backoff logic.

Connecting the MCP Server to Claude

Once you have your Truto MCP URL, connecting it to Claude requires zero additional coding. The URL contains everything needed to authenticate and serve the JSON-RPC 2.0 handshake.

Method A: Via the Claude UI

If you are using Claude Enterprise or a supported Claude UI interface, you can add the connector directly from the settings menu:

1. In Claude, navigate to Settings -> Integrations -> Add MCP Server.
2. Paste your Truto MCP URL.
3. Click Add.

Claude will immediately call the /initialize and /tools/list endpoints on the server, populating its context with the available Hex capabilities.

Method B: Via Manual Config File (Claude Desktop)

If you are using Claude Desktop locally, you configure the server via the claude_desktop_config.json file. Since Truto provides an SSE (Server-Sent Events) endpoint, you use the standard MCP SSE client wrapper.

Edit your configuration file (located at ~/Library/Application Support/Claude/claude_desktop_config.json on Mac, or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "hex-admin-server": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/YOUR_SECURE_TOKEN"
      ]
    }
  }
}

Restart Claude Desktop. The "plug" icon will indicate that the Hex tools are loaded and ready for use.

Hero Tools for Hex

Truto automatically exposes dozens of endpoints across the Hex API. Here are 7 high-leverage hero tools your agents can use to administer a Hex workspace.

list_all_hex_projects

This tool retrieves all viewable Hex projects in the workspace. It is essential for discovery, allowing the LLM to map project names to their internal UUIDs before taking action.

Usage notes: Projects are returned sorted by creation date. The response includes vital metadata like status, creator, and analytics, which Claude can use to identify abandoned or highly utilized apps.

"Claude, list all the projects in our Hex workspace. Find any projects that haven't been edited in the last six months and summarize their titles and creators."

list_all_hex_data_connections

This tool lists all data connections available in the workspace, including Snowflake, Postgres, BigQuery, and other integrations.

Usage notes: The LLM can view connection types, schema refresh schedules, and sharing rules. This is crucial for auditing infrastructure security to ensure only authorized groups have access to production databases.

"Claude, pull a list of all data connections. Identify any connections typed as 'POSTGRES' that allow writeback cells."

update_a_hex_data_connection_by_id

This tool updates an existing data connection. It is heavily utilized for programmatic credential rotation or enforcing schema filters without requiring an admin to log into the UI.

Usage notes: The input schema is strict. The LLM must pass the id and the specific fields to update. If modifying connectionDetails, it must adhere to the required keys for that specific connection type.

"Claude, update the data connection ID dc-9f3a2b to disable writeback cells, and change its description to 'Deprecated: migrating to new Snowflake warehouse'."

hex_sharing_users_bulk_update

This tool modifies access control for specific users across a Hex project. It supports atomic batch operations.

Usage notes: Valid sharing enums are CAN_VIEW, APP_ONLY, CAN_EDIT, FULL_ACCESS, or NONE (to remove access). A maximum of 25 users can be updated per API call. If one user configuration is malformed, the batch fails.

"Claude, update the project sharing for project ID proj-123. Grant CAN_EDIT access to user ID usr-456 and remove access (NONE) for user ID usr-789."

create_a_hex_project_run

This tool triggers a new analytical run on the latest published version of a project.

Usage notes: Because execution is asynchronous, this tool returns a runId and a status of RUNNING or QUEUED. The LLM must be prompted to capture this ID and poll for completion if it needs the final result.

"Claude, trigger a run for the 'Monthly Revenue Dashboard' project. Please initiate the run and give me the run ID."

get_single_hex_project_run_by_id

This tool retrieves the current status of an initiated project run.

Usage notes: The LLM uses this in a loop to check if a run has hit COMPLETED, ERROR, or KILLED. It returns detailed telemetry including startTime, elapsedTime, and traceId.

"Claude, check the status of run ID run-999 for project ID proj-123. If it has errored, retrieve the failure state events."

create_a_hex_thread

This tool starts an agentic thread natively within Hex, allowing the LLM to leverage Hex's internal AI capabilities to analyze data or debug SQL.

Usage notes: The thread runs asynchronously. The tool returns a threadId and url. Claude can start a thread, wait, and then query the thread status to fetch the internal agent's analysis.

"Claude, start a new Hex thread in project ID proj-123 with the prompt 'Analyze the queried tables and suggest optimizations for the SQL cell'."

To view the complete schema definitions and the full inventory of available tools, visit the Hex Integration Page.

Workflows in Action

Connecting these tools enables Claude to operate as an autonomous data infrastructure administrator. Here are two concrete workflows.

Workflow 1: Infrastructure Audit and Remediation

Data teams frequently need to audit connection security, particularly ensuring that broad access or write capabilities are restricted to production-grade connections.

"Claude, audit our Hex data connections. Find any Postgres connections that allow writeback cells. For any you find, update them immediately to disable writebacks and update their descriptions to 'Writebacks disabled for security audit'."

Step-by-step execution:

1. Claude calls list_all_hex_data_connections to retrieve the workspace infrastructure.
2. It parses the JSON array, filtering for records where type is POSTGRES and allowWritebackCells is true.
3. For each violating connection, Claude calls update_a_hex_data_connection_by_id, passing allowWritebackCells: false and the new description.
4. Claude returns a summary of the connections it successfully locked down.

sequenceDiagram
  participant User as User
  participant Claude as Claude
  participant MCP as Truto MCP Server
  participant Hex as Hex API

  User->>Claude: "Audit Postgres connections..."
  Claude->>MCP: Call list_all_hex_data_connections
  MCP->>Hex: GET /api/v1/data-connections
  Hex-->>MCP: Returns [ { id: "dc-1", type: "POSTGRES", allowWritebackCells: true } ]
  MCP-->>Claude: JSON response
  Claude->>MCP: Call update_a_hex_data_connection_by_id (dc-1)
  MCP->>Hex: PATCH /api/v1/data-connections/dc-1<br>payload: { allowWritebackCells: false }
  Hex-->>MCP: 200 OK Updated
  MCP-->>Claude: Success
  Claude-->>User: "Audited and updated dc-1."

Workflow 2: Onboarding and Delegating Project Access

When a new data scientist joins, they often need edit access to specific domain projects. Claude can handle the discovery and provisioning instantly.

"Claude, find the project titled 'Q3 Churn Prediction Model'. Once you have the ID, update the sharing permissions to grant CAN_EDIT access to user ID usr-888."

Step-by-step execution:

1. Claude calls list_all_hex_projects to pull the directory.
2. It matches the title 'Q3 Churn Prediction Model' to extract its UUID.
3. Claude calls hex_sharing_users_bulk_update, passing the project UUID and an array containing [{ userId: "usr-888", accessLevel: "CAN_EDIT" }].
4. Claude confirms to the user that access has been provisioned.

sequenceDiagram
  participant User as User
  participant Claude as Claude
  participant MCP as Truto MCP Server
  participant Hex as Hex API

  User->>Claude: "Find 'Q3 Churn Prediction Model' and grant CAN_EDIT..."
  Claude->>MCP: Call list_all_hex_projects
  MCP->>Hex: GET /api/v1/projects
  Hex-->>MCP: Returns [ { id: "proj-abc", title: "Q3 Churn Prediction Model" } ]
  MCP-->>Claude: JSON response
  Claude->>MCP: Call hex_sharing_users_bulk_update (proj-abc)
  MCP->>Hex: POST /api/v1/projects/proj-abc/sharing/users<br>payload: [{userId: "usr-888", accessLevel: "CAN_EDIT"}]
  Hex-->>MCP: 200 OK
  MCP-->>Claude: Success
  Claude-->>User: "Access granted to usr-888."

Security and Access Control

Giving an LLM access to your Hex workspace infrastructure requires strict governance. Truto's MCP architecture provides multiple layers of access control, enforced at the token level via secure edge storage.

• Method Filtering: When generating the MCP server, you can pass methods: ["read"] to restrict the server entirely to GET and LIST requests. Any attempt by Claude to execute a POST, PATCH, or DELETE tool will fail at the router level, preventing accidental deletions or credential modifications.
• Tag Filtering: You can restrict the server to specific operational domains by passing tags like ["projects", "sharing"]. If a tool's underlying integration resource isn't tagged accordingly, it is completely excluded from the /tools/list response sent to Claude.
• Expiration Controls: Using the expires_at field, you can issue short-lived MCP servers (e.g., valid for 24 hours). Once the timestamp passes, the token is automatically evicted from storage, immediately terminating Claude's access to Hex.
• Secondary Authentication (require_api_token_auth): For environments where the MCP URL might be exposed in configuration files, you can enable secondary authentication. This forces the MCP client to pass a valid Truto API bearer token or session cookie alongside the URL token, ensuring only authorized engineers can invoke the tools.

Control Your Data Infrastructure with AI

Building a custom integration layer to translate LLM tool calls into strict, heavily validated Hex API payloads is a massive engineering sink. Every bulk update failure, asynchronous run loop, and unhandled 429 rate limit pulls your team away from core product work.

By leveraging Truto's managed MCP architecture, you replace fragile point-to-point scripts with a dynamically generated, strictly governed API layer. Claude gets the exact JSON schemas and endpoints it needs to orchestrate data connections, manage project access, and execute analytical runs—all governed by the security and rate limit pass-throughs required for enterprise infrastructure.