Hex MCP Server

Connect AI assistants to Hex through the Model Context Protocol (MCP).

info

• Available on the Team and Enterprise plans.
• Hex MCP Server works with Claude Desktop, Claude Code, ChatGPT, and Cursor, as well as most standard MCP clients.
• Users will need the Explorer workspace role or higher to interact with the create_thread and continue_thread tools.
• Hex MCP server is currently in beta.

Overview

The Model Context Protocol (MCP) allows AI applications to securely connect to external data sources and tools. The Hex MCP server enables AI assistants like Claude to interact directly with your Hex workspace. Through the MCP server, AI assistants can search your projects, create and continue Threads conversations, and help you explore your data through natural language.

The Hex MCP server provides four Tools:

• search_projects: Find projects in your Hex workspace
• create_thread: Start a new Thread conversation
• get_thread: Retrieve messages and results from a Thread
• continue_thread: Add follow-up questions to an existing Thread

The Hex MCP Server will use the default data connection as a source for any Thread it creates. The Hex MCP Server can only answer text-based prompts; currently it is not possible to upload files to your conversation and pass them along to Hex.

Configure the Hex MCP Server

Connect to Claude

info

Claude owners (on Claude Teams or Enterprise plans) or users (on a Claude Individual plan) can configure the Hex Connector for their workspace.

Add the Hex Connector to your Claude Workspace

1. In Claude, go to Settings > Connectors > Browse Connectors and search for "Hex".

2. Add the connector to your team.

3. Set the server URL to https://app.hex.tech/mcp and click "Continue".

tip

For single tenant, EU multi-tenant, or HIPAA multi-tenant customers, replace app.hex.tech with your custom Hex URL (e.g., your-company.hex.tech, eu.hex.tech, hc.hex.tech).

info

If you want to connect to multiple workspaces that have different URLs (e.g. app.hex.tech vs eu.hex.tech), you can configure additional custom Claude connectors.

How to use the Hex Connector in Claude

Once the Hex Connector is added by a Claude workspace owner, users can enable it by navigating to Settings -> Connectors and clicking "Connect" next to the Hex Connector.

Once you open a new chat, you should ensure that the Hex Connector is toggled on via the ‘+’ icon in the bottom left:

Search for existing projects

You can use the Hex Connector to search for relevant projects in your Hex workspace. Claude will return visual project cards that display the project title, description, and other information and include a link to the project in your Hex workspace.

Threads in the Hex Connector in Claude

You can ask open ended data questions in your Claude chat, and the Hex Connector will kick off a Thread to answer the question. An interactive widget in the Claude chat will appear and show the Hex Threads “thinking” steps, allowing you to follow along with the Thread in realtime without leaving Claude.

tip

You can click into each “thinking” block in the widget to understand what specific actions the Threads agent took to answer your question.

The Hex Connector will continually make get_thread calls without user prompting, checking in on the progress of the Thread and keeping you updated on its analysis. If the Threads agent creates any charts or tables in the course of its analysis, the Hex Connector will surface these as a carousel in an interactive widget in your Claude chat.

Once the Thread has finished its analysis, Claude will summarize its key findings and provide a link to the Thread in your Hex workspace. If you ask a follow up question, the Hex Connector in Claude will use a continue_thread tool call to continue the Thread within the Claude chat.

info

Interactive widgets that are created by the Hex Connector in a Claude chat, including thinking blocks and chart carousels, will expire after 24 hours.

Connect to Cursor

In Cursor settings, go to Settings > Cursor Settings > Tools & MCP.

From Tools & MCP Settings, add the Hex MCP server as a remote MCP server URL: https://app.hex.tech/mcp so Hex can connect via OAuth. You can also directly edit your ~/.cursor/mcp.json file to add Hex as an MCP:

{
  "mcpServers": {
    "hex": {
      "url": "https://app.hex.tech/mcp"
    }
  }
}

tip

For single tenant, EU multi-tenant, or HIPAA multi-tenant customers, replace app.hex.tech with your custom Hex URL (e.g., your-company.hex.tech, eu.hex.tech).

After adding the MCP server, go back to the Settings page and select Connect to start the OAuth flow. You will be redirected back to our external authentication provider to approve the connection (and specify a workspace if you have access to multiple).

When successfully connected, you should see the connected Hex MCP and you can configure tool permissions under Tools & MCP.

Connect to ChatGPT

Hex is available as an app in ChatGPT via our MCP Server. To use the Hex app in ChatGPT, just start your prompt with “/Hex” and select the Hex app from the menu that appears.

tip

If you are on a custom stack (i.e. if your Hex workspace URL starts with something other than https://app.hex.tech), you will need to set up a custom ChatGPT app using the instructions here.

The first time you use the Hex app in ChatGPT, you will be directed to connect the app by authenticating into your Hex workspace. Once you authenticate, you're ready to use the Hex app in ChatGPT.

If you don't see the Hex app appear when you type "/Hex", an admin in your ChatGPT workspace will need to approve and connect the Hex app. To approve and connect the Hex app as a ChatGPT workspace admin, navigate to Settings -> Apps -> Browse Apps and search for the Hex app. You can also click here to be taken directly to the app.

Click on the Hex app, then click Connect.

You will be redirected to our external authentication provider to approve the connection (and specify a workspace if you have access to multiple). Once you've authed into Hex, you are ready to use the Hex app in ChatGPT.

Create a custom app for your Hex workspace (single tenant or custom stacks)

If your Hex workspace is not on our multi-tenant stack, you'll need to add a custom app in order to use the Hex app in ChatGPT. Ensure that you have turned on Developer Mode before proceeding.

In ChatGPT, navigate to Settings -> Apps -> Advanced settings and click Create App in the top right.

From the "New App" page, name your custom app (e.g. "Hex - [Your company name]").

In the MCP Server URL field, enter your workspace URL followed by /mcp (e.g. https://company-name.hex.tech/mcp).

Select OAuth as the authentication method, check the box at the bottom of the form, and click Create.

This will start the OAuth flow. You will be redirected to our external authentication provider to approve the connection. Once that is done, you are ready to start using the Hex app in ChatGPT!

How to use the Hex app in ChatGPT

Once you’ve connected ChatGPT to Hex, you can use the Hex app to explore projects and ask data questions directly from chat. ChatGPT uses the Hex MCP server under the hood to search projects and run Threads on your behalf.

Search for existing projects

You can ask the Hex app in ChatGPT to search your Hex workspace for relevant projects. The app will search your workspace and return links to matching projects with their titles and descriptions. Simply type "/Hex" into chat and then pose your question:

Threads in the Hex app in ChatGPT

You can start a new Hex Thread from the Hex app in ChatGPT to answer a data question. Begin your message with "/Hex" and ask it a question about your business. The Hex app in ChatGPT will create a new Thread and begin running the analysis. A link to the Thread will be provided in chat:

info

• Thread creation requires a default data connection to be configured in your workspace
• Threads typically take several minutes to complete as the agent analyzes your data

Once a Thread is running, you can ask the Hex app in ChatGPT to check on the existing thread. If the thread is still running, it will tell you as much and provide a link to the Thread in Hex. If the Thread is finished, it will return a summary of the results of the Thread and provide a link to the Thread in Hex:

After a Thread completes, you can ask follow-up questions to refine or expand the analysis. The Hex app in ChatGPT will continue the same Thread rather than starting a new one. This lets you iterate on your analysis in chat, just like continuing a conversation in a Thread within your Hex workspace.

Connect to other MCP Clients

Hex MCP Server is also supported in clients outside of Claude, Cursor, and ChatGPT. Any tool that supports MCP integrations can be linked to the Hex MCP Server, and you can embed the MCP Server URL in an internal tool, or a tool for which a native integration is not yet available.

To connect to another MCP client, open your configuration file and add the Hex MCP server configuration:

{
  "mcpServers": {
    "hex": {
      "url": "https://app.hex.tech/mcp"
    }
  }
}

After you've added the MCP server to your application, restart the application to apply the configuration. Then, when you first interact with Hex through the MCP, you'll be prompted to authenticate through our external authentication provider.

Available actions

Search for projects in your workspace

Input: Search query to find relevant projects. This action will return both published and unpublished Hex projects.

Output:

• projects (array): List of matching projects with the following fields:
  • projectId: Unique ID for the project
  • title: Project title
  • description: Project description
  • generated_summary: AI-generated summary of the project (if available)
  • url: Direct link to the project
  • type: Either "project" or "app"

info

The response structure and fields provided by the call output are subject to change.

Create a new Thread

Create a new Hex Thread to ask questions about your data using the Hex Agent.

Input: The question or analysis request for the Hex Agent

Output: Confirmation message with Thread ID and Thread URL

info

• Thread creation requires a default data connection to be configured in your workspace
• Threads typically take several minutes to complete as the agent analyzes your data

Get an existing Thread

Retrieve messages and results from an existing Hex Thread.

Input: Thread ID

Output: If the Thread has not yet completed, the call will return:

• Thread ID
• Thread status
• Wait time

If the Thread has completed, the call will return:

• Recent messages in the Thread conversation
• Any charts, tables, or visualizations generated by the agent
• Link to view the full Thread in Hex

tip

If the Thread hasn't finished, you can call get_thread again to check for updates. The tool is designed to be called multiple times until the Thread reaches idle status.

Continue an existing Thread

Continue a conversation by providing a new prompt to an existing Hex Thread.

Input: Thread ID, Thread prompt

Output:

• Recent messages in the Thread conversation
• Any charts, tables, or visualizations generated by the agent
• Link to view the full Thread in Hex

warning

You can only continue a Thread once it has finished running. If you try to continue a running Thread, you'll receive an error message asking you to wait for the current operation to complete.

Example workflows

Asking a data question

A typical workflow for asking a data question through the MCP server:

1. User asks a question:

   What were our top-selling products last quarter?

2. AI assistant creates a Thread:

   • Uses create_thread with the user's question
   • Receives a Thread ID and URL

3. AI assistant monitors progress:

   • Calls get_thread periodically
   • Checks if status is complete or still processing
   • Shows the user what the agent is thinking

4. AI assistant returns results:

   • Presents the agent's analysis, charts, and insights
   • Provides a link to view the full Thread in Hex

5. User asks a follow-up:

   Can you break that down by sales channel?

6. AI assistant continues the conversation:

   • Uses continue_thread with the follow-up question
   • Monitors with get_thread until complete
   • Presents the updated analysis

Finding and exploring projects

To help users discover relevant work:

1. User asks about existing analysis:

   Do we have any projects about customer segmentation?

2. AI assistant searches:

   • Uses search_projects with query "customer segmentation"

3. AI assistant presents results:

   • Shows project titles, descriptions, and generated summaries
   • Provides direct links to open projects in Hex

4. User can create a new Thread:

   • If they want to ask questions about the data in those projects
   • The AI assistant uses create_thread to start the analysis