# Hex — how to use (mcp.ai)

Connect your Hex account and use 32 tools for analytics straight from your AI agent. Connect with your own API key. Hex is a collaborative data workspace that combines SQL, Python, and R notebooks for analytics and data science.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_hex?ms=1787291460000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `hex_cancel_run`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/hex`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/hex/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/hex/cancel/run` — Tool to cancel a project run that is in progress. Use when you need to stop a currently executing Hex project run before it completes.
  - body: { run_id: string, project_id: string }
- `POST https://api.mcp.ai/api/hex/create/cell` — Tool to create a new cell in the draft version of a Hex project. Use when adding CODE or SQL cells to a project. Only CODE and SQL cell types are supported. Requires EDIT_PROJECT_CONTENTS permission.
  - body: { label?: string, cellType: string, contents: object, location?: object, projectId: string }
- `POST https://api.mcp.ai/api/hex/create/collection` — Tool to create a new collection in the Hex workspace. Use when you need to organize projects and resources into a collection.
  - body: { name: string, sharing?: object, description?: string }
- `POST https://api.mcp.ai/api/hex/create/group` — Tool to create a new group in the Hex workspace. Use when you need to organize users into groups for collaboration and access control.
  - body: { name: string, members?: object }
- `POST https://api.mcp.ai/api/hex/deactivate/user` — Deactivates a user in the Hex workspace. Use this when you need to deactivate a user by their ID.
  - body: { user_id: string }
- `POST https://api.mcp.ai/api/hex/delete/cell` — Permanently delete a cell from the draft version of a project. Requires EDIT_PROJECT_CONTENTS permission. Use when you need to remove a cell from a Hex project's draft.
  - body: { cellId: string }
- `POST https://api.mcp.ai/api/hex/delete/group` — Deletes a group from the Hex workspace. Use this when you need to permanently remove a group by its ID.
  - body: { group_id: string }
- `POST https://api.mcp.ai/api/hex/delete/guide/draft` — Deletes a guide draft by ID from Hex. Use this when you need to permanently remove a draft guide.
  - body: { orgGuideFileId: string }
- `POST https://api.mcp.ai/api/hex/edit/collection` — Tool to edit a collection's name, description, and sharing settings in Hex. Use when you need to update collection metadata or change sharing permissions.
  - body: { name?: string, sharing?: object, description?: string, collectionId: string }
- `POST https://api.mcp.ai/api/hex/edit/group` — Tool to edit a group's name and/or members in Hex. Use when you need to update group details, add users to a group, or remove users from a group.
  - body: { name?: string, members?: object, group_id: string }
- `POST https://api.mcp.ai/api/hex/edit/project/sharing/collections` — Tool to add a project to collections or remove it from collections. Use when you need to update project sharing by adding or modifying collection access. Workspace tokens need Collections -> Write acc
  - body: { sharing: object, projectId: string }
- `POST https://api.mcp.ai/api/hex/edit/project/sharing/groups` — Tool to edit project sharing settings for groups in Hex. Use when you need to add or modify group access to a project. Supports up to 25 groups per request.
  - body: { sharing: object, projectId: string }
- `POST https://api.mcp.ai/api/hex/edit/project/sharing/org/and/public` — Tool to edit project sharing settings for workspace members and public web access. Use when you need to control who can access a Hex project and what permissions they have.
  - body: { sharing: object, projectId: string }
- `POST https://api.mcp.ai/api/hex/edit/project/sharing/users` — Tool to edit project sharing settings for individual users in Hex. Add or modify user access to a project by specifying access levels (NONE, APP_ONLY, CAN_VIEW, CAN_EDIT, FULL_ACCESS). Use when you ne
  - body: { sharing: object, projectId: string }
- `POST https://api.mcp.ai/api/hex/get/cell` — Tool to get a single cell by ID from the draft version of a Hex project. Use when you need to retrieve cell details including source contents for CODE and SQL cells. Returns complete cell information 
  - body: { cellId: string }
- `POST https://api.mcp.ai/api/hex/get/collection` — Tool to get information about a specific collection in Hex. Returns collection details including name, description, creator, and sharing settings. Use when you need to retrieve metadata about a collec
  - body: { collectionId: string }
- `POST https://api.mcp.ai/api/hex/get/group` — Tool to retrieve information about a specific Hex group. Use when you need to get details about a group including its ID, name, and creation date.
  - body: { group_id: string }
- `POST https://api.mcp.ai/api/hex/get/project` — Tool to get metadata about a single Hex project. Use when you need to retrieve project details including title, description, creator, owner, status, categories, analytics, schedules, and sharing infor
  - body: { project_id: string, include_sharing?: boolean }
- `POST https://api.mcp.ai/api/hex/get/project/runs` — Tool to retrieve the status of API-triggered runs for a specific Hex project. Use when you need to check the execution status, timing, or history of project runs. Returns a paginated list of runs with
  - body: { limit?: integer, offset?: integer, projectId: string, statusFilter?: string }
- `POST https://api.mcp.ai/api/hex/get/run/chart/image` — Tool to retrieve a rendered chart image from a Hex project run. Use when you need to get a visual representation of a chart cell from a completed run. Only supports chart-type cells that have executed
  - body: { runId: string, staticId: string, projectId: string }
- `POST https://api.mcp.ai/api/hex/get/run/status` — Tool to retrieve the status of a specific Hex project run. Use when you need to check the current state, timing, or completion status of a project execution. Returns detailed information including sta
  - body: { runId: string, projectId: string, enable_expanded_stats?: string }
- `POST https://api.mcp.ai/api/hex/list/cells` — Tool to list all cells from the draft version of a Hex project. Use when you need to retrieve cells with source code for SQL and CODE cells. Returns paginated results with cell details including type,
  - body: { after?: string, limit?: integer, before?: string, projectId: string }
- `POST https://api.mcp.ai/api/hex/list/collections` — Tool to retrieve all collections in the workspace with pagination support. Use when you need to list or discover available collections.
  - body: { after?: string, limit?: integer, before?: string, sortBy?: string, sortDirection?: string }
- `POST https://api.mcp.ai/api/hex/list/data/connections` — Tool to list all data connections in the Hex workspace with pagination support. Use when you need to retrieve, browse, or audit data connections configured in Hex. Supports filtering by sort criteria 
  - body: { after?: string, limit?: integer, before?: string, sortBy?: string, sortDirection?: string }
- `POST https://api.mcp.ai/api/hex/list/groups` — Tool to list all groups in the Hex workspace with pagination support. Use when you need to retrieve groups with optional sorting and pagination.
  - body: { after?: string, limit?: integer, before?: string, sortBy?: string, sortDirection?: string }
- `POST https://api.mcp.ai/api/hex/list/projects` — Tool to list all viewable Hex projects with pagination and filtering support. Use when you need to retrieve projects sorted by creation date or filter by status, categories, creator, owner, or collect
  - body: { after?: string, limit?: integer, before?: string, sortBy?: string, statuses?: string[], categories?: string[], ownerEmail?: string, collectionId?: string, creatorEmail?: string, sortDirection?: string, includeSharing?: boolean, includeTrashed?: boolean, includeArchived?: boolean, includeComponents?: boolean }
- `POST https://api.mcp.ai/api/hex/list/users` — Tool to list all users in the Hex workspace with pagination support. Returns user details including names, emails, roles, and last login dates. Use when you need to retrieve users, filter by group, or
  - body: { after?: string, limit?: integer, before?: string, sortBy?: string, groupId?: string, sortDirection?: string }
- `POST https://api.mcp.ai/api/hex/publish/guide/drafts` — Tool to publish all currently drafted guides or specific guides by ID. Use when you need to make draft guides publicly available. Specify either publishAllDraftGuides=true or provide specific guide ID
  - body: { orgGuideFileIds?: string[], publishAllDraftGuides?: boolean }
- `POST https://api.mcp.ai/api/hex/run/project` — Tool to trigger a run of the latest published version of a Hex project. Use when you need to execute a project programmatically. Rate limited to 20 requests per minute and 60 requests per hour.
  - body: { dry_run?: boolean, view_id?: string, project_id: string, input_params?: object, notifications?: object[], flag_config_override?: string, use_cached_sql_results?: boolean, update_published_results?: boolean }
- `POST https://api.mcp.ai/api/hex/update/cell` — Tool to update a cell's source code and/or data connection in Hex. Use when you need to modify the contents of a code cell or SQL cell. Requires EDIT_PROJECT_CONTENTS permission.
  - body: { cellId: string, contents?: object, dataConnectionId?: string }
- `POST https://api.mcp.ai/api/hex/update/project` — Tool to add or remove a status (including endorsements) from a Hex project. Use when you need to update the project's status or remove an existing status by setting it to null.
  - body: { status?: string, project_id: string }
- `POST https://api.mcp.ai/api/hex/upsert/guide/draft` — Tool to update or create guide drafts by filePath. Creates a new guide if it doesn't exist, creates a draft if the guide exists without a draft, or updates an existing draft. Use when you need to prog
  - body: { files: object[], forceWrite?: boolean }

## Example prompts
- "What can I do in Hex?"
- "Show me a summary of my Hex account"

## More
- Page: https://mcp.ai/hex
- Agent spec (llms.txt): https://mcp.ai/hex/llms.txt
- Postman collection: https://mcp.ai/hex/postman.json