Merge Unified's Hex integration Merge Agent Handler's Hex MCP server

Connect your AI Agents to Hex in minutes

Merge lets you securely connect your agents to Hex and thousands of tools instantly

Start building for free

Read docs

Hex

Learn more about Merge Agent Handler

Available tools

list_cells

List cells in a project with pagination. Use cursor from page_info for next page.

get_cell

Get a cell by ID within a project.

create_cell

Create a new cell in a project. Pass cell type and content in cell_data.

update_cell

Update a cell's content or configuration within a project.

delete_cell

Delete a cell from a project permanently.

list_collections

List collections in the workspace with pagination. Use cursor from page_info for next page.

get_collection

Get a collection by ID including name, description, creator, and sharing settings.

create_collection

Create a new collection to organize projects.

update_collection

Update a collection's name or description.

list_data_connections

List accessible data connections with pagination. Use cursor from page_info for next page.

get_data_connection

Get a data connection by ID including configuration, sharing, and schema settings.

create_data_connection

Create a new data connection. Requires name, type (e.g. snowflake, postgres, bigquery), and type-specific connection details.

update_data_connection

Update a data connection's name, description, configuration, or sharing settings.

update_connection_schema

Update a data connection's schema filters to include or exclude databases, schemas, or tables. Each update: {"type": "DATABASE"|"SCHEMA"|"TABLE", "name": "<name>", "status": "INCLUDED"|"EXCLUDED"}.

list_groups

List workspace groups with pagination. Sort by CREATEDAT or NAME. Use cursor from pageinfo for next page.

get_group

Get a group by ID including name and creation date.

create_group

Create a new workspace group with optional initial members. Use list_users to find user IDs for members.

update_group

Update a group's name and membership. Add or remove users by ID. Use list_users to find user IDs.

delete_group

Delete a workspace group permanently. This cannot be undone.

list_guide_drafts

List guide drafts with pagination. Use cursor from page_info for next page.

upsert_guide_draft

Create or update a guide draft. Pass guide data including title, content, and configuration.

publish_guide_drafts

Publish guide drafts. Optionally specify guide IDs, or omit to publish all drafts.

delete_guide_draft

Delete a guide draft permanently. Use listguidedrafts to find IDs.

get_queried_tables

Get warehouse tables queried within a project. Enterprise plan only. Use list_projects to find project IDs.

list_projects

List projects in the workspace. Filter by status, category, creator, owner, or collection. Supports sorting and pagination. Use cursor from page_info for next page.

get_project

Get metadata for a single project by ID. Optionally include sharing details.

create_project

Create a new project in the workspace with a title and optional description.

update_project

Update a project's status or endorsements.

share_project_users

Share a project with specific users. Set access level per user (CANVIEW, CANEDIT, FULLACCESS, NONE). Use listusers to find user IDs.

share_project_groups

Share a project with groups. Set access level per group (CANVIEW, CANEDIT, FULLACCESS, NONE). Use listgroups to find group IDs.

share_project_collections

Add a project to collections with specific access levels (APPONLY, CANVIEW, CANEDIT, FULLACCESS, NONE). Use list_collections to find collection IDs.

update_project_visibility

Update workspace-wide and public web sharing for a project. Access levels: NONE, APPONLY, CANVIEW, CANEDIT, FULLACCESS.

run_project

Trigger a run of a published project. Optionally pass input parameters, notification configs, and cache settings. Project must be published first.

list_project_runs

List run history for a project. Filter by status (PENDING, RUNNING, ERRORED, COMPLETED, KILLED) or trigger type (API, SCHEDULED, APP_REFRESH). Uses offset pagination.

get_run_status

Get detailed status of a specific project run including timing, state events, and notifications.

cancel_run

Cancel an in-progress project run. Only works on runs with PENDING or RUNNING status.

get_run_chart_image

Get a rendered PNG chart image from a completed project run. Returns base64-encoded image data. Requires the chart cell's static ID.

get_current_user

Get the authenticated user's profile including name, email, and workspace role.

list_users

List workspace users with pagination. Use cursor from page_info for next page.

deactivate_user

Deactivate a workspace user. Use list_users to find user IDs. This action cannot be undone via API.

validate_credential

Validate Hex API token by retrieving the current user profile.

View all tools by creating a free account See more tools

How to set up Merge Agent Handler

In an mcp.json file, add the configuration below, and restart Cursor.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "url": "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
5      "headers": {
6        "Authorization": "Bearer yMt*****"
7      }
8    }
9  }
10}
11

Copy Code

Open your Claude Desktop configuration file and add the server configuration below. You'll also need to restart the application for the changes to take effect.

Make sure Claude is using the Node v20+.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "command": "npx",
5      "args": [
6        "-y",
7        "mcp-remote@latest",
8        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
9        "--header",
10        "Authorization: Bearer ${AUTH_TOKEN}"
11      ],
12      "env": {
13        "AUTH_TOKEN": "yMt*****"
14      }
15    }
16  }
17}

Copy Code

Open your Windsurf MCP configuration file and add the server configuration below.
Click on the refresh button in the top right of the Manage MCP server page or in the top right of the chat box in the box icon.

Learn more in the official documentation ↗

1{
2    "mcpServers": {
3      "agent-handler": {
4        "command": "npx",
5        "args": [
6          "-y",
7          "mcp-remote@latest",
8          "https://ah-api.merge.dev/api/v1/tool-packs/<tool-pack-id>/registered-users/<registered-user-id>/mcp",
9          "--header",
10          "Authorization: Bearer ${AUTH_TOKEN}"
11        ],
12        "env": {
13          "AUTH_TOKEN": "<ah-production-access-key>"
14        }
15      }
16    }
17  }

Copy Code

In Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows), run "MCP: Open User Configuration".

You can then add the configuration below and press "start" right under servers. Enter the auth token when prompted.

Learn more in the official documentation ↗

1{
2  "inputs": [
3    {
4      "type": "promptString",
5      "id": "agent-handler-auth",
6      "description": "Agent Handler AUTH_TOKEN", // "yMt*****" when prompt
7      "password": true
8    }
9  ],
10  "servers": {
11    "agent-handler": {
12      "type": "stdio",
13      "command": "npx",
14      "args": [
15        "-y",
16        "mcp-remote@latest",
17        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
18        "--header",
19        "Authorization: Bearer ${input:agent-handler-auth}"
20      ]
21    }
22  }
23}

Copy Code

FAQs on using Merge's Hex MCP server

What is a Hex MCP?

A Hex MCP is a server that connects your agents to Hex through a set of callable tools. Your agents can use those tools to run projects, check run status, manage data connections, and share projects with users or groups, and more.

Hex offers an official MCP server, but you can also use one from a third-party platform, like Merge Agent Handler.

How can I use the Hex MCP server?

The use cases naturally depend on the agent you've built, but here are a few common ones:

Event-triggered project runs: When a dbt model or upstream pipeline completes, an agent can automatically trigger the corresponding Hex project run so downstream analyses stay current without anyone clicking "Run" manually

Run monitoring and alerting: An agent can poll the status of long-running Hex projects and post a Slack alert if a project exceeds its expected runtime or fails, giving data teams visibility without watching the UI

Automated user provisioning: When a new analyst joins a team in your HR system, an agent can add them to the correct Hex group and share the relevant projects, so they have access to the right workspace from day one

Scheduled analysis delivery: An agent can run a Hex reporting project on a fixed schedule, retrieve the output chart image, and attach it to a weekly stakeholder email or Slack digest without any manual steps

What are popular tools for Hex's MCP server?

Here are some of the most commonly used tools:

run_project: triggers a Hex project to execute on demand, using the project's current logic and connected data sources. Use this when an agent needs to refresh an analysis in response to an upstream event

get_run_status: returns the current state of a project run, including whether it's running, completed, or failed. Useful for agents that need to wait for a run to finish before taking a downstream action

get_run_chart_image: fetches a rendered chart image from a completed project run. Good for workflows that need to attach a visual output to a report, email, or Slack message

list_projects: retrieves all projects available in a Hex workspace, including metadata like owner and visibility. Call this when an agent needs to locate a specific project before running or sharing it

share_project_groups: grants a Hex group access to a specific project. Helpful when an agent handles onboarding or permissions changes across multiple workspace members at once

list_data_connections: returns all data connections configured in the workspace, including type and connection details. Use this when an agent needs to verify that a data source is available before triggering a project run that depends on it

What makes Merge Agent Handler's Hex MCP server better than alternative Hex MCP servers?

Several things set Merge Agent Handler's Hex MCP server apart from building your own or using another:

Enterprise-grade security and DLP: Merge Agent Handler includes built-in data loss prevention controls that let you block or redact sensitive fields before they reach an agent. For Hex, this means you can prevent proprietary query logic, data connection credentials, and project output data from being surfaced to agents that only need to trigger runs or check status

Managed authentication and credentials: Merge stores and refreshes Hex credentials on your behalf. You never embed API tokens in agent code or risk a broken automation when a key rotates

Real-time observability and audit trail: Every tool call against Hex is logged with timestamp, tool name, inputs, and response metadata. You get a full record of which projects were run, which users were provisioned, and which data connections were accessed, with no custom logging required

Tool Packs and controlled access: Tool Packs let you define a precise set of Hex tools for each agent use case. A run-and-monitor agent gets run_project and get_run_status. A provisioning agent gets group and sharing tools. Neither can reach the other's operations

How can I start using Merge Agent Handler's Hex MCP server?

You can take the following steps:

1. Create or log into your Merge Agent Handler account.

2. Install the Merge CLI by running pipx install merge-api, then run merge configure to link the CLI to your Merge account and merge login to authenticate your session.

3. Register the Agent Handler MCP server with Claude Code by running claude mcp add --transport http agent-handler https://ah-api.merge.dev/mcp, then open Claude Code and run /mcp to confirm agent-handler appears with a connected status.

4. Select agent-handler from the MCP list. This opens a browser window where you select which integrations to authenticate. Choose Hex and complete the auth flow. Merge stores and manages the credentials going forward.

5. Open a Claude Code session and start querying Hex data directly. The first time you use a Hex tool, a Magic Link may appear to complete connector authentication.

If you want to connect Merge Agent Handler's Hex MCP with internal or customer-facing agentic products, you can follow the steps in our docs.