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, and Cursor, as well as most standard MCP Clients. Support for ChatGPT is coming soon.
• Users will need the Explorer workspace role 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

Configure the Hex MCP Server

Connect to Claude

In Claude settings, go to Settings > Connectors > Add Custom Connector.

To configure an Enterprise account, go to Admin Settings > Connectors > Add Custom Connector.

From the Add Custom Connector Settings, provide the Hex MCP 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 providing your base URL, click 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 Configure.

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 other MCP Clients

Hex MCP Server is also supported in clients outside of Cursor and Claude. 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