Connect AI agents to the Hex MCP server

Vendor MCP

The Hex MCP connector routes your AI agent's tool calls to Hex's own MCP server through Scalekit. Each user signs in to Hex once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 20 tools.

Tools: 20
What they doRead · write · destructive: 11 · 8 · 111 read8 write1 destructive
Users sign in with: OAuth
OAuth app: Scalekit's or your own

Setup

Install the SDK
- Node.js
- Python
Terminal window
npm install @scalekit-sdk/node dotenv
Terminal window
pip install scalekit-sdk-python python-dotenv
Set your credentials
Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.
.env
```
SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
SCALEKIT_CLIENT_ID=<your-client-id>
SCALEKIT_CLIENT_SECRET=<your-client-secret>
```
Create the Hex MCP connection
In AgentKit > Connections, create a Hex MCP connection. The name you give it is the connection_name your code passes. See Configure connections.
Scalekit credentials are available for Hex MCP server, so you don't need to register an OAuth app.

Authorize a user and make your first call

Node.js
Python

1
import { ScalekitClient } from '@scalekit-sdk/node'
2
import 'dotenv/config'
3
import { createInterface } from 'node:readline/promises'
4

5
const scalekit = new ScalekitClient(
6
  process.env.SCALEKIT_ENVIRONMENT_URL,
7
  process.env.SCALEKIT_CLIENT_ID,
8
  process.env.SCALEKIT_CLIENT_SECRET,
9
)
10
const actions = scalekit.actions
11

12
const connector = 'hexmcp'
13
const identifier = 'user_123'
14

15
// Generate an authorization link for the user
16
const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
17
console.log('Authorize Hex MCP:', link)
18
const rl = createInterface({ input: process.stdin, output: process.stdout })
19
await rl.question('Press Enter after authorizing...')
20
rl.close()
21

22
// Make your first call
23
const result = await actions.executeTool({
24
  connector,
25
  identifier,
26
  toolName: 'hexmcp_get_me',
27
  toolInput: {},
28
})
29
console.log(result)

npx tsx quickstart.mts

1
import os
2
from scalekit import ScalekitClient
3
from dotenv import load_dotenv
4
load_dotenv()
5

6
scalekit_client = ScalekitClient(
7
    env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
8
    client_id=os.getenv("SCALEKIT_CLIENT_ID"),
9
    client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
10
)
11
actions = scalekit_client.actions
12

13
connection_name = "hexmcp"
14
identifier = "user_123"
15

16
# Generate an authorization link for the user
17
link_response = actions.get_authorization_link(
18
    connection_name=connection_name,
19
    identifier=identifier,
20
)
21
print("Authorize Hex MCP:", link_response.link)
22
input("Press Enter after authorizing...")
23

24
# Make your first call
25
result = actions.execute_tool(
26
    tool_input={},
27
    tool_name="hexmcp_get_me",
28
    connection_name=connection_name,
29
    identifier=identifier,
30
)
31
print(result)

python quickstart.py

Each user signs in once. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool

Try in Playground Request a tool

hexmcp_get_cellGet a single cell by IDRead-only
Get Cell
Get a single cell by ID
Inputs
cellIdstringrequired
No description.
hexmcp_get_cell_imageGet the rendered PNG image of a chart cell, returned as an image.Read-only
Get Cell Image
Get the rendered PNG image of a chart cell, returned as an image. The cell must live in its project's draft version, must have been executed, and must not be in an error state. Only chart-type cells are supported. `get_thread` reports the cellId of each chart in a thread that can be fetched this way. Omit width and height unless you need more detail: the default image is tens of kilobytes, while the maximum 2000x2000 can exceed 500KB for a dense chart. Request one chart at a time.
Inputs
cellIdstringrequired
The id of the chart cell (scoped to a specific version); a staticCellId is also accepted and resolved within the draft version.
heightinteger
Output image height in pixels, between 100 and 2000. Both width and height must be provided to apply.
includeTitleboolean
Include the chart title in the image when true.
widthinteger
Output image width in pixels, between 100 and 2000. Both width and height must be provided to apply.
hexmcp_get_cell_outputGet the latest output preview for a SQL cell in the active draft notebook session.Read-only
Get Cell Output
Get the latest output preview for a SQL cell in the active draft notebook session.
Inputs
cellIdstringrequired
The SQL cell ID or static cell ID to read output for.
hexmcp_get_dashboard_import_job_statusCheck the original reconstruction run for a Claude dashboard import.Read-only
Get Dashboard Import Job Status
Check the original reconstruction run for a Claude dashboard import. processing means the run is active; done means it finished without an agent error; failed means it ended unsuccessfully. Completion does not certify visual fidelity. A lookup failure is returned as an error and never reported as done.
Inputs
job_idstringrequired
The import job ID returned when reconstruction started.
hexmcp_get_meReturn information about the currently authenticated user.Read-only
Get Me
Return information about the currently authenticated user.
Inputs
This tool takes no inputs.
hexmcp_get_projectGet metadata about a single project.Read-only
Get Project
Get metadata about a single project.
Inputs
projectIdstringrequired
The project to fetch.
includeSharingboolean
Whether to include sharing metadata in the response.default false
includeUnlistedboolean
Whether to return unlisted projects. Defaults to false.default false
hexmcp_get_runGet the status of a project run.Read-only
Get Run
Get the status of a project run.
Inputs
projectIdstringrequired
The project the run belongs to.
runIdstringrequired
The run to retrieve.
hexmcp_get_threadFetch a Hex Thread by its ID, including the latest response and status.Read-only
Get Thread
Fetch a Hex Thread by its ID, including the latest response and status.
Inputs
idstringrequired
No description.
hexmcp_list_cellsList cells from the draft version of a project.Read-only
List Cells
List cells from the draft version of a project. Returns code, SQL, and markdown cell contents.
Inputs
projectIdstringrequired
The project to list cells from
afterstring
No description.
beforestring
No description.
limitnumber
No description.default 25
hexmcp_list_data_connectionsList the workspace's data connections.Read-only
List Data Connections
List the workspace's data connections. Use this to resolve a connection name to a dataConnectionId before creating or updating a SQL cell with `create_cell` or `update_cell`. Results are paginated: pass the returned `pagination.after` cursor to fetch the next page, and stop when it comes back null. If a listed id later fails, re-list before retrying â the connection may have been removed or become inaccessible.
Inputs
afterstring
No description.
beforestring
No description.
limitnumber
No description.default 25
sortBystring
No description.one of NAMECREATED_ATdefault NAME
sortDirectionstring
No description.one of ASCDESCdefault ASC
hexmcp_search_projectsSearch for Hex projects by keyword.Read-only
Search Projects
Search for Hex projects by keyword.
Inputs
querystringrequired
The search query to find relevant projects. This should be a non-empty string without wildcards.
hexmcp_continue_threadContinue an existing Hex Thread by adding a new message and triggering the agent to process it.Write
Continue Thread
Continue an existing Hex Thread by adding a new message and triggering the agent to process it.
Inputs
idstringrequired
The ID of the thread to continue
promptstringrequired
The message to add to continue the thread
hexmcp_create_cellCreate a new cell in the draft version of a project.Write
Create Cell
Create a new cell in the draft version of a project. For SQL cells that query a warehouse, reuse the dataConnectionId of an existing SQL cell in the project (`list_cells` returns it), falling back to `list_data_connections` to resolve one by name (or set isDataframeSql). Do not invent connection ids.
Inputs
cellTypestringrequired
The type of cell to create. Determines which `contents` variant is required.one of CODESQLMARKDOWN
contentsstringrequired
Cell contents. Provide exactly the variant matching `cellType`: `codeCell` for CODE, `sqlCell` for SQL, `markdownCell` for MARKDOWN.
projectIdstringrequired
The project to create the cell in.
labelstring
Optional label for the cell.
locationobject
Controls where the new cell is placed. If omitted, the cell is appended to the end of the project.
hexmcp_create_projectCreate a new project in the workspace with the specified title, and optionally a description.Write
Create Project
Create a new project in the workspace with the specified title, and optionally a description.
Inputs
titlestringrequired
The title of the new project.
descriptionstring
An optional description for the new project.
hexmcp_create_threadCreate a new Hex Thread to ask a question about your data using natural language.Write
Create Thread
Create a new Hex Thread to ask a question about your data using natural language.
Inputs
promptstringrequired
No description.
hexmcp_import_claude_dashboard_from_urlDownload a Claude dashboard JSON export containing top-level query metadata and an HTML snapshot, then start reconstructing it in a Hex project.Write
Import Claude Dashboard From Url
Download a Claude dashboard JSON export containing top-level query metadata and an HTML snapshot, then start reconstructing it in a Hex project. When download_token is provided, it is sent as a bearer token; otherwise the URL is fetched exactly as given. Use claude_design_project_id to update the same project on later imports. Reconstruction runs asynchronously; poll the returned job_id. The dashboard_url is a project draft, and acceptance does not mean reconstruction is complete. After an ambiguous timeout, reconcile existing activity before retrying the import.
Inputs
urlstringrequired
HTTPS URL on *.frame.claudeusercontent.com with a /_handoff/ path for one JSON dashboard export; download immediately and exactly as given, including its query string; maximum 8192 characters
claude_design_project_idstring
Stable Claude source dashboard ID for updating the same Hex project; maximum 512 characters
download_tokenstring
Optional separate bearer token for the export download, sent unchanged in the Authorization header when provided; when omitted, fetch url exactly as given without an Authorization header; 1â512 letters, digits, periods, underscores, or hyphens
titlestring
Suggested dashboard title; maximum 500 characters
hexmcp_run_cellRun a cell and its upstream dependencies in the draft (notebook) version of a project.Write
Run Cell
Run a cell and its upstream dependencies in the draft (notebook) version of a project. The run is asynchronous: for SQL cells, poll `get_cell_output` every 5 seconds to read the result or error. The returned runId identifies the long-running draft session and may correlate with earlier cell runs, so an early poll can still return the previous execution's output â after editing a cell, verify the output reflects the latest source.
Inputs
cellIdstringrequired
The cell to run (draft version, or resolved to draft by static ID).
dryRunboolean
Validate the request without executing.default false
hexmcp_run_notebookTrigger a run of the draft (notebook) version of a project.Write
Run Notebook
Trigger a run of the draft (notebook) version of a project. The run is asynchronous: poll `get_run` with the returned runId every 5 seconds until the status is terminal (COMPLETED, ERRORED, KILLED, or UNABLE_TO_ALLOCATE_KERNEL). The runId identifies the long-running draft session and may correlate with earlier runs of the project, so if the project ran recently, confirm the reported startTime is at or after this call before trusting a terminal status.
Inputs
projectIdstringrequired
The project whose draft notebook version should run.
useCachedSqlResultsboolean
Allow SQL cells to reuse cached results.default true
hexmcp_update_cellUpdate a cell's source and/or data connection.Write
Update Cell
Update a cell's source and/or data connection. For SQL cells, can update the SQL source, output dataframe, and data connection. Take a warehouse dataConnectionId from an existing SQL cell in the project or from `list_data_connections` before attaching one. If an id later fails, re-list connections before retrying. Returns the updated cell.
Inputs
cellIdstringrequired
No description.
contentsobject
No description.
dataConnectionIdstring
Data connection to attach to a SQL cell. Pass null to detach the existing data connection.
hexmcp_delete_cellDelete a cell from the draft version of a project by IDDestructive
Delete Cell
Delete a cell from the draft version of a project by ID
Inputs
cellIdstringrequired
No description.

Setup

Install the SDK

Set your credentials

Create the Hex MCP connection

Authorize a user and make your first call

Tools

Call it

Returns

Get Cell

Inputs

Get Cell Image

Inputs

Get Cell Output

Inputs

Get Dashboard Import Job Status

Inputs

Get Me

Inputs

Get Project

Inputs

Get Run

Inputs

Get Thread

Inputs

List Cells

Inputs

List Data Connections

Inputs

Search Projects

Inputs

Continue Thread

Inputs

Create Cell

Inputs

Create Project

Inputs

Create Thread

Inputs

Import Claude Dashboard From Url

Inputs

Run Cell

Inputs

Run Notebook

Inputs

Update Cell

Inputs

Delete Cell

Inputs

Related: other Analytics connectors