hex-mcp

# hex-mcp MCP server A MCP server for Hex that implements orchestration, monitoring, cell content access, permission management, collection organization, and group management tools. ## What This Does (And Doesn't Do) ### Practical Use Cases **Orchestration and Automation**: - Trigger Hex project runs from external systems (Airflow DAGs, CI/CD pipelines) - Monitor run status programmatically - Cancel long-running or stuck executions - Discover and search projects across workspaces **Operational Monitoring**: - Check if scheduled runs completed successfully - Get run history for auditing - Programmatic access to project metadata (owner, last edited, description) **Cell Content Access** (NEW): - Read notebook structure and cell metadata - Read SQL query source code from SQL cells - Read Python/R code from CODE cells - Good for query migration, code analysis, and content auditing **Permission Management** (NEW): - Programmatically manage user and group access to projects - Bulk update permissions across multiple projects - Manage workspace-wide and public access settings - Add or remove projects from collections **Collection Organization** (NEW): - Create and manage collections for organizing projects - Organize projects by department, team, or topic - Control collection visibility and access - Bulk organize projects into collections **Group Management** (NEW): - Create and manage user groups for permission management - Add and remove users from groups in bulk - Use groups to simplify permission management across projects - Maintain organized team structures **Data Connection Management** (NEW): - List and manage database and warehouse connections - Create connections for BigQuery, Snowflake, Postgres, Redshift, Athena, Databricks - Update connection configurations and credentials - Control data connection sharing across workspace ### Critical Limitations **Limited notebook content access**: - ✅ Can read SQL and CODE cell source content - ❌ Cannot read MARKDOWN, INPUT, or visualization cells - ❌ Cannot create or delete cells - ❌ Cannot modify notebook structure - ❌ Cannot view query results or charts - ❌ Cannot manage notebook dependencies or parameters **Not suitable for**: - Building or authoring notebooks from scratch - Collaborative notebook development - Debugging queries or code execution - Full notebook backup (only SQL/CODE cells accessible) - Reading markdown documentation or input parameters ### When to Use This Use hex-mcp when you need to: - **Orchestrate** Hex executions from external systems - **Monitor** run status and history - **Read** SQL queries and code from existing notebooks - **Audit** or **migrate** SQL/CODE content across projects - **Manage** permissions and access control across projects - **Automate** bulk permission updates for users, groups, and collections - **Organize** projects into collections by department, team, or topic - **Maintain** user groups for simplified permission management - **Standardize** workspace organization across your Hex instance - **Manage** data connections and database integrations programmatically - **Automate** connection setup for new workspaces or environments For full notebook development and editing, use the Hex web UI directly. ## Available Tools ### Project Operations - `list_hex_projects`: Lists available Hex projects - `search_hex_projects`: Search for Hex projects by pattern - `get_hex_project`: Get detailed information about a specific project ### Project Execution - `run_hex_project`: Execute a Hex project - `get_hex_run_status`: Check the status of a project run - `get_hex_project_runs`: Get the history of project runs - `cancel_hex_run`: Cancel a running project ### Cell Operations (NEW) - `list_hex_cells`: List all cells in a project with source code for SQL/CODE cells - `update_hex_cell`: Update SQL or CODE cell source and/or data connection ### Permission Management (NEW) - `update_hex_project_user_sharing`: Grant or revoke user access to projects - `update_hex_project_group_sharing`: Grant or revoke group access to projects - `update_hex_project_collection_sharing`: Add or remove projects from collections - `update_hex_project_workspace_sharing`: Update workspace-wide and public access ### Collection Management (NEW) - `list_hex_collections`: List all collections in the workspace - `get_hex_collection`: Get detailed information about a specific collection - `create_hex_collection`: Create a new collection with optional sharing settings - `update_hex_collection`: Update collection name, description, or sharing settings ### Group Management (NEW) - `list_hex_groups`: List all groups in the workspace - `get_hex_group`: Get detailed information about a specific group - `create_hex_group`: Create a new group with optional initial members - `update_hex_group`: Update group name and/or membership (add/remove users) - `delete_hex_group`: Delete a group from the workspace ### Data Connection Management (NEW) - `list_hex_data_connections`: List all data connections in the workspace - `get_hex_data_connection`: Get detailed information about a specific data connection - `create_hex_data_connection`: Create a new database/warehouse connection - `update_hex_data_connection`: Update connection configuration, credentials, or sharing ## Installation Using uv is the recommended way to install hex-mcp: ```bash uv add hex-mcp ``` Or using pip: ```bash pip install hex-mcp ``` To confirm it's working, you can run: ```bash hex-mcp --version ``` ## Configuration ### Using the config command (recommended) The easiest way to configure hex-mcp is by using the `config` command and passing your API key and API URL (optional and defaults to `https://app.hex.tech/api/v1`): ```bash hex-mcp config --api-key "your_hex_api_key" --api-url "https://app.hex.tech/api/v1" ``` > [!NOTE] > This saves your configuration to a file in your home directory (e.g. `~/.hex-mcp/config.yml`), making it available for all hex-mcp invocations. ### Using environment variables Alternatively, the Hex MCP server can be configured with environment variables: - `HEX_API_KEY`: Your Hex API key - `HEX_API_URL`: The Hex API base URL When setting up environment variables for MCP servers they need to be either global for Cursor to pick them up or make use of uv's `--env-file` flag when invoking the server. ## Using with Cursor Cursor allows AI agents to interact with Hex via the MCP protocol. Follow these steps to set up and use hex-mcp with Cursor. You can create a `.cursor/mcp.json` file in your project root with the following content: ```json { "mcpServers": { "hex-mcp": { "command": "uv", "args": ["run", "hex-mcp", "run"] } } } ``` Alternatively, you can use the `hex-mcp` command directly if it's in your PATH: ```json { "mcpServers": { "hex-mcp": { "command": "hex-mcp", "args": ["run"] } } } ``` Once it's up and running, you can use it in Cursor by initiating a new AI (Agent) conversation and ask it to list or run a Hex project. > [!IMPORTANT] > The MCP server and CLI is still in development and subject to breaking changes. ## Usage Examples ### Reading Cell Content Use `list_hex_cells` to read the structure and source code of a Hex notebook: ```python # List all cells in a project cells = list_hex_cells(project_id="your-project-uuid") # The response includes cell metadata and source code for SQL/CODE cells # Example response structure: { "values": [ { "id": "cell-uuid-123", "staticId": "static-id-456", "cellType": "SQL", "label": "Load Customer Data", "dataConnectionId": "connection-uuid-789", "contents": { "sqlCell": { "source": "SELECT * FROM customers WHERE active = true" }, "codeCell": null } }, { "id": "cell-uuid-456", "cellType": "CODE", "label": "Process Data", "dataConnectionId": null, "contents": { "sqlCell": null, "codeCell": { "source": "import pandas as pd\ndf = df.dropna()" } } }, { "id": "cell-uuid-789", "cellType": "MARKDOWN", "label": "Documentation", "dataConnectionId": null, "contents": { "sqlCell": null, "codeCell": null } } ], "pagination": { "next": null, "previous": null } } ``` **Note**: Only SQL and CODE cells include source content. MARKDOWN, INPUT, and visualization cells return null for both `sqlCell` and `codeCell`. ### Pagination For projects with many cells, use pagination: ```python # First page page1 = list_hex_cells(project_id="your-project-uuid", limit=50) # Next page using cursor if page1["pagination"]["next"]: page2 = list_hex_cells( project_id="your-project-uuid", limit=50, after=page1["pagination"]["next"] ) # Previous page if page2["pagination"]["previous"]: page1_again = list_hex_cells( project_id="your-project-uuid", limit=50, before=page2["pagination"]["previous"] ) ``` ### Updating Cell Content Update SQL or CODE cells programmatically: ```python # Update SQL cell source code result = update_hex_cell( cell_id="cell-uuid-123", sql_source="SELECT * FROM updated_table WHERE active = true" ) # Update CODE cell source code result = update_hex_cell( cell_id="cell-uuid-456", code_source="import pandas as pd\ndf = df.dropna()" ) # Update SQL cell data connection (without changing source) result = update_hex_cell( cell_id="cell-uuid-123", data_connection_id="new-connection-uuid" ) # Update both SQL source and connection in one call result = update_hex_cell( cell_id="cell-uuid-123", sql_source="SELECT * FROM production.customers", data_connection_id="production-connection-uuid" ) ``` **Important**: - Can only update SQL and CODE cell types - Cannot update MARKDOWN, INPUT, or visualization cells - Requires `EDIT_PROJECT_CONTENTS` permission - Cannot update both `sql_source` and `code_source` in same call (cells are either SQL or CODE) ### Query Migration Example Extract and update SQL queries across projects: ```python import json # Get all cells from source project cells_response = list_hex_cells(project_id="source-project-uuid") cells = json.loads(cells_response) # Filter for SQL cells sql_cells = [ cell for cell in cells["values"] if cell["cellType"] == "SQL" and cell["contents"]["sqlCell"] ] # Migrate queries to new data connection new_connection_id = "production-bigquery-connection" for cell in sql_cells: original_query = cell["contents"]["sqlCell"]["source"] # Update table references (example: dev -> prod) updated_query = original_query.replace("dev.schema", "prod.schema") # Update the cell with new query and connection result = update_hex_cell( cell_id=cell["id"], sql_source=updated_query, data_connection_id=new_connection_id ) print(f"Updated cell: {cell['label']}") print(f"Migrated {len(sql_cells)} SQL cells to production") ``` ### Code Refactoring Example Bulk update Python code across multiple cells: ```python import json # Get all CODE cells cells_response = list_hex_cells(project_id="project-uuid") cells = json.loads(cells_response) code_cells = [ cell for cell in cells["values"] if cell["cellType"] == "CODE" and cell["contents"]["codeCell"] ] # Update import statements for cell in code_cells: original_code = cell["contents"]["codeCell"]["source"] # Replace deprecated import if "from old_library" in original_code: updated_code = original_code.replace( "from old_library import func", "from new_library import func" ) # Update the cell result = update_hex_cell( cell_id=cell["id"], code_source=updated_code ) print(f"Updated cell: {cell['label']}") ``` ### Managing Project Permissions Control access to Hex projects programmatically using the sharing endpoints. #### Grant User Access ```python from hex_mcp.server import update_hex_project_user_sharing # Grant edit access to a single user result = update_hex_project_user_sharing( project_id="project-123", user_permissions=[ {"user_id": "user-456", "access": "CAN_EDIT"} ] ) # Grant access to multiple users with different permissions result = update_hex_project_user_sharing( project_id="project-123", user_permissions=[ {"user_id": "user-001", "access": "CAN_VIEW"}, {"user_id": "user-002", "access": "CAN_EDIT"}, {"user_id": "user-003", "access": "FULL_ACCESS"} ] ) # Revoke user access result = update_hex_project_user_sharing( project_id="project-123", user_permissions=[ {"user_id": "user-456", "access": "NONE"} ] ) ``` **Access Levels**: - `NONE`: Revoke all access - `APP_ONLY`: Access only within apps (published versions) - `CAN_VIEW`: View project in logic view (read-only) - `CAN_EDIT`: Edit project contents - `FULL_ACCESS`: Edit contents and manage project settings/permissions #### Grant Group Access ```python from hex_mcp.server import update_hex_project_group_sharing # Grant access to a group result = update_hex_project_group_sharing( project_id="project-123", group_permissions=[ {"group_id": "group-789", "access": "CAN_VIEW"} ] ) # Grant access to multiple groups result = update_hex_project_group_sharing( project_id="project-123", group_permissions=[ {"group_id": "analytics-team", "access": "CAN_EDIT"}, {"group_id": "leadership-team", "access": "CAN_VIEW"} ] ) ``` #### Add Projects to Collections ```python from hex_mcp.server import update_hex_project_collection_sharing # Add project to a collection result = update_hex_project_collection_sharing( project_id="project-123", collection_permissions=[ {"collection_id": "collection-456", "access": "CAN_VIEW"} ] ) # Add to multiple collections with different access levels result = update_hex_project_collection_sharing( project_id="project-123", collection_permissions=[ {"collection_id": "public-dashboards", "access": "APP_ONLY"}, {"collection_id": "internal-analytics", "access": "CAN_EDIT"} ] ) # Remove from collection result = update_hex_project_collection_sharing( project_id="project-123", collection_permissions=[ {"collection_id": "collection-456", "access": "NONE"} ] ) ``` #### Manage Workspace and Public Access ```python from hex_mcp.server import update_hex_project_workspace_sharing # Make project viewable by entire workspace result = update_hex_project_workspace_sharing( project_id="project-123", workspace_access="CAN_VIEW" ) # Make project publicly accessible result = update_hex_project_workspace_sharing( project_id="project-123", public_access="APP_ONLY" ) # Update both workspace and public access result = update_hex_project_workspace_sharing( project_id="project-123", workspace_access="CAN_EDIT", public_access="APP_ONLY" ) # Revoke public access (keep workspace access) result = update_hex_project_workspace_sharing( project_id="project-123", public_access="NONE" ) ``` #### Bulk Permission Management Example Standardize permissions across multiple projects: ```python import json from hex_mcp.server import ( list_hex_projects, update_hex_project_user_sharing, update_hex_project_workspace_sharing ) # Get all projects projects_response = list_hex_projects() projects = json.loads(projects_response) # Define standard access policies analytics_team_users = ["user-001", "user-002", "user-003"] leadership_users = ["user-100", "user-101"] for project in projects: project_id = project["projectId"] # Grant analytics team edit access update_hex_project_user_sharing( project_id=project_id, user_permissions=[ {"user_id": user_id, "access": "CAN_EDIT"} for user_id in analytics_team_users ] ) # Grant leadership view access update_hex_project_user_sharing( project_id=project_id, user_permissions=[ {"user_id": user_id, "access": "CAN_VIEW"} for user_id in leadership_users ] ) # Make viewable by workspace, not public update_hex_project_workspace_sharing( project_id=project_id, workspace_access="CAN_VIEW", public_access="NONE" ) print(f"Updated permissions for: {project['name']}") ``` **Important Notes**: - All sharing operations require appropriate workspace permissions - User/group IDs must exist in your Hex workspace - Collection IDs must be valid collections you have access to - Workspace access applies to all workspace members - Public access (`publicWeb`) allows anyone with the link to access ### Managing Collections Organize projects into collections for better workspace organization. #### List Collections ```python from hex_mcp.server import list_hex_collections import json # List all collections collections = list_hex_collections() data = json.loads(collections) for collection in data["values"]: print(f"{collection['name']}: {collection['id']}") print(f" Created by: {collection.get('creator', {}).get('email', 'N/A')}") # List with pagination page1 = list_hex_collections(limit=10) data = json.loads(page1) if data["pagination"]["next"]: page2 = list_hex_collections(limit=10, after=data["pagination"]["next"]) ``` #### Get Collection Details ```python from hex_mcp.server import get_hex_collection import json # Get specific collection collection = get_hex_collection(collection_id="collection-123") data = json.loads(collection) print(f"Collection: {data['name']}") print(f"Description: {data.get('description', 'No description')}") print(f"Sharing with {len(data['sharing'].get('users', []))} users") print(f"Sharing with {len(data['sharing'].get('groups', []))} groups") ``` #### Create Collections ```python from hex_mcp.server import create_hex_collection import json # Create simple collection collection = create_hex_collection( name="Q4 2026 Analytics", description="Analytics projects for Q4 2026" ) data = json.loads(collection) print(f"Created collection: {data['id']}") # Create with sharing settings collection = create_hex_collection( name="Executive Dashboards", description="Dashboards for executive team", sharing_users=[ {"id": "user-ceo", "access": "CAN_VIEW"}, {"id": "user-cfo", "access": "CAN_VIEW"} ], workspace_access="NONE" # Only specified users can access ) # Create with group access collection = create_hex_collection( name="Finance Reports", description="Financial reporting and analysis", sharing_groups=[ {"id": "finance-team", "access": "CAN_EDIT"} ], workspace_access="CAN_VIEW" ) ``` #### Update Collections ```python from hex_mcp.server import update_hex_collection import json # Update collection name and description result = update_hex_collection( collection_id="collection-123", name="Q1 2027 Analytics", description="Updated for Q1 2027" ) # Update sharing settings result = update_hex_collection( collection_id="collection-123", sharing_users=[ {"id": "user-456", "access": "CAN_EDIT"} ], workspace_access="CAN_VIEW" ) # Update multiple fields at once result = update_hex_collection( collection_id="collection-123", name="Updated Collection Name", description="Updated description", sharing_groups=[ {"id": "analytics-team", "access": "CAN_EDIT"} ], workspace_access="CAN_VIEW" ) ``` #### Collection Organization Example Organize all projects by department: ```python import json from hex_mcp.server import ( list_hex_projects, list_hex_collections, create_hex_collection, update_hex_project_collection_sharing ) # Define department structure departments = { "Engineering": ["user-eng-lead", "group-engineering"], "Finance": ["user-fin-lead", "group-finance"], "Marketing": ["user-mkt-lead", "group-marketing"] } # Create collections for each department collection_ids = {} for dept_name, members in departments.items(): # Create collection collection = create_hex_collection( name=f"{dept_name} Projects", description=f"All {dept_name} department projects", workspace_access="CAN_VIEW" ) data = json.loads(collection) collection_ids[dept_name] = data["id"] print(f"Created collection for {dept_name}: {data['id']}") # Get all projects projects = list_hex_projects() projects_data = json.loads(projects) # Organize projects into collections based on name patterns for project in projects_data: project_id = project["projectId"] project_name = project["name"].lower() # Determine which collection(s) this project belongs to if "engineering" in project_name or "technical" in project_name: update_hex_project_collection_sharing( project_id=project_id, collection_permissions=[ {"collection_id": collection_ids["Engineering"], "access": "CAN_EDIT"} ] ) print(f"Added '{project['name']}' to Engineering collection") elif "finance" in project_name or "revenue" in project_name: update_hex_project_collection_sharing( project_id=project_id, collection_permissions=[ {"collection_id": collection_ids["Finance"], "access": "CAN_EDIT"} ] ) print(f"Added '{project['name']}' to Finance collection") elif "marketing" in project_name or "campaign" in project_name: update_hex_project_collection_sharing( project_id=project_id, collection_permissions=[ {"collection_id": collection_ids["Marketing"], "access": "CAN_EDIT"} ] ) print(f"Added '{project['name']}' to Marketing collection") print("Collection organization complete!") ``` **Collection Management Notes**: - Collections help organize projects by team, department, or topic - Collections can have their own sharing settings independent of projects - A project can belong to multiple collections - Workspace access on collections controls who can see the collection exists - Creating collections requires appropriate workspace permissions ### Managing Groups Organize users into groups for simplified permission management. #### List Groups ```python from hex_mcp.server import list_hex_groups import json # List all groups groups = list_hex_groups() data = json.loads(groups) for group in data["values"]: print(f"{group['name']}: {group['id']}") print(f" Created: {group['createdAt']}") # List with pagination and sorting page1 = list_hex_groups( limit=10, sort_by="name", sort_direction="asc" ) data = json.loads(page1) if data["pagination"]["next"]: page2 = list_hex_groups(limit=10, after=data["pagination"]["next"]) ``` #### Get Group Details ```python from hex_mcp.server import get_hex_group import json # Get specific group group = get_hex_group(group_id="group-123") data = json.loads(group) print(f"Group: {data['name']}") print(f"ID: {data['id']}") print(f"Created: {data['createdAt']}") ``` #### Create Groups ```python from hex_mcp.server import create_hex_group import json # Create simple group group = create_hex_group(name="Analytics Team") data = json.loads(group) print(f"Created group: {data['id']}") # Create with initial members group = create_hex_group( name="Finance Team", member_user_ids=[ "user-123", "user-456", "user-789" ] ) data = json.loads(group) print(f"Created group with 3 members: {data['id']}") ``` #### Update Groups ```python from hex_mcp.server import update_hex_group import json # Update group name result = update_hex_group( group_id="group-123", name="Senior Analytics Team" ) # Add members to group result = update_hex_group( group_id="group-123", add_member_user_ids=["user-new-1", "user-new-2"] ) # Remove members from group result = update_hex_group( group_id="group-123", remove_member_user_ids=["user-old-1"] ) # Update name and membership together result = update_hex_group( group_id="group-123", name="Lead Analytics Team", add_member_user_ids=["user-lead"], remove_member_user_ids=["user-junior"] ) ``` #### Delete Groups ```python from hex_mcp.server import delete_hex_group # Delete a group (does not delete the users, only the group) result = delete_hex_group(group_id="group-old-team") print(result) # "Group deleted successfully" ``` #### Bulk Group Management Example Create department-based groups and assign users: ```python import json from hex_mcp.server import ( create_hex_group, update_hex_group, update_hex_project_group_sharing ) # Define department structure with user lists departments = { "Engineering": { "leads": ["user-eng-lead-1", "user-eng-lead-2"], "members": ["user-eng-1", "user-eng-2", "user-eng-3"] }, "Data Science": { "leads": ["user-ds-lead"], "members": ["user-ds-1", "user-ds-2", "user-ds-3", "user-ds-4"] }, "Analytics": { "leads": ["user-analytics-lead"], "members": ["user-analyst-1", "user-analyst-2"] } } # Create groups for each department group_ids = {} for dept_name, users in departments.items(): # Create main department group all_members = users["leads"] + users["members"] group = create_hex_group( name=f"{dept_name} Team", member_user_ids=all_members ) data = json.loads(group) group_ids[dept_name] = data["id"] print(f"Created {dept_name} Team: {data['id']} ({len(all_members)} members)") # Create leadership sub-group lead_group = create_hex_group( name=f"{dept_name} Leadership", member_user_ids=users["leads"] ) lead_data = json.loads(lead_group) group_ids[f"{dept_name}_Leadership"] = lead_data["id"] print(f"Created {dept_name} Leadership: {lead_data['id']} ({len(users['leads'])} members)") # Grant group access to relevant projects # Engineering team gets edit access to technical projects update_hex_project_group_sharing( project_id="technical-project-123", group_permissions=[ {"group_id": group_ids["Engineering"], "access": "CAN_EDIT"} ] ) # Analytics team gets view access to all dashboards update_hex_project_group_sharing( project_id="dashboard-project-456", group_permissions=[ {"group_id": group_ids["Analytics"], "access": "CAN_VIEW"} ] ) # Leadership groups get view access to executive dashboards for dept in ["Engineering", "Data Science", "Analytics"]: leadership_group_id = group_ids[f"{dept}_Leadership"] update_hex_project_group_sharing( project_id="executive-dashboard-789", group_permissions=[ {"group_id": leadership_group_id, "access": "CAN_VIEW"} ] ) print("Group-based permission management complete!") ``` #### Team Reorganization Example Handle team changes by updating group memberships: ```python import json from hex_mcp.server import ( list_hex_groups, update_hex_group ) # Get all groups groups = list_hex_groups() groups_data = json.loads(groups) # Find specific groups that need updates engineering_group = None for group in groups_data["values"]: if group["name"] == "Engineering Team": engineering_group = group break if engineering_group: # New hires joining new_engineers = ["user-new-eng-1", "user-new-eng-2"] # Engineers leaving departing_engineers = ["user-old-eng-1"] # Update group membership result = update_hex_group( group_id=engineering_group["id"], add_member_user_ids=new_engineers, remove_member_user_ids=departing_engineers ) print(f"Updated {engineering_group['name']}") print(f" Added: {len(new_engineers)} members") print(f" Removed: {len(departing_engineers)} members") ``` **Group Management Notes**: - Groups simplify permission management by allowing you to grant access to multiple users at once - A user can belong to multiple groups - Maximum 100 users can be added or removed in a single update operation - Deleting a group does not delete the users, only the group itself - Group permissions are inherited by all group members - Use groups with project sharing endpoints to grant team-wide access ### Managing Data Connections Manage database and warehouse connections for Hex projects. #### List Data Connections ```python from hex_mcp.server import list_hex_data_connections import json # List all data connections connections = list_hex_data_connections() data = json.loads(connections) for conn in data["values"]: print(f"{conn['name']} ({conn['type']}): {conn['id']}") if conn.get('description'): print(f" Description: {conn['description']}") # List with pagination and sorting page1 = list_hex_data_connections( limit=10, sort_by="NAME", sort_direction="asc" ) data = json.loads(page1) if data["pagination"]["next"]: page2 = list_hex_data_connections(limit=10, after=data["pagination"]["next"]) ``` #### Get Data Connection Details ```python from hex_mcp.server import get_hex_data_connection import json # Get specific connection connection = get_hex_data_connection(connection_id="conn-123") data = json.loads(connection) print(f"Connection: {data['name']}") print(f"Type: {data['type']}") print(f"Description: {data.get('description', 'N/A')}") print(f"Include Magic: {data.get('includeMagic', False)}") print(f"Allow Writeback: {data.get('allowWritebackCells', False)}") # Check sharing settings if 'sharing' in data: workspace = data['sharing'].get('workspace', {}) print(f"Workspace Access: {workspace.get('members', 'None')}") ``` #### Create Data Connections ```python from hex_mcp.server import create_hex_data_connection import json # Create BigQuery connection bigquery_conn = create_hex_data_connection( name="Production BigQuery", connection_type="bigquery", connection_details={ "bigquery": { "serviceAccountJsonConfig": json.dumps(service_account_config), "projectId": "my-gcp-project", "enableStorageApi": True, "enableDriveAccess": False } }, description="Production data warehouse for analytics", include_magic=True, allow_writeback_cells=False, sharing={ "workspace": { "members": "CAN_USE" } } ) data = json.loads(bigquery_conn) print(f"Created BigQuery connection: {data['id']}") # Create Snowflake connection snowflake_conn = create_hex_data_connection( name="Snowflake Analytics", connection_type="snowflake", connection_details={ "snowflake": { "account": "my-account", "warehouse": "ANALYTICS_WH", "database": "ANALYTICS_DB", "schema": "PUBLIC", "username": "hex_service", "password": "secure_password" } }, description="Snowflake warehouse for analytics", include_magic=True ) data = json.loads(snowflake_conn) print(f"Created Snowflake connection: {data['id']}") # Create Postgres connection postgres_conn = create_hex_data_connection( name="Application Database", connection_type="postgres", connection_details={ "postgres": { "hostname": "db.example.com", "port": 5432, "database": "app_db", "username": "readonly_user", "password": "secure_password", "ssl": True } }, description="Production application database (read-only)", connect_via_ssh=False, include_magic=True, allow_writeback_cells=False ) data = json.loads(postgres_conn) print(f"Created Postgres connection: {data['id']}") ``` #### Update Data Connections ```python from hex_mcp.server import update_hex_data_connection import json # Update connection name and description result = update_hex_data_connection( connection_id="conn-123", name="Updated Production BigQuery", description="Updated production data warehouse for analytics and reporting" ) data = json.loads(result) print(f"Updated connection: {data['name']}") # Update connection settings result = update_hex_data_connection( connection_id="conn-123", include_magic=False, allow_writeback_cells=True ) print("Updated connection settings") # Update connection sharing result = update_hex_data_connection( connection_id="conn-123", sharing={ "workspace": { "members": "CAN_USE", "guests": "NONE" }, "groups": { "upsert": [ {"group": {"id": "analytics-team-group-id"}, "access": "CAN_USE"}, {"group": {"id": "data-eng-group-id"}, "access": "CAN_ADMIN"} ] } } ) print("Updated connection sharing") # Rotate credentials by updating connection details result = update_hex_data_connection( connection_id="conn-123", connection_details={ "bigquery": { "serviceAccountJsonConfig": json.dumps(new_service_account), "projectId": "my-gcp-project", "enableStorageApi": True, "enableDriveAccess": False } } ) print("Rotated connection credentials") ``` #### Bulk Connection Setup Automate connection setup for new workspaces or environments: ```python from hex_mcp.server import create_hex_data_connection import json # Define standard connections for a workspace connection_configs = { "Production BigQuery": { "type": "bigquery", "details": { "bigquery": { "serviceAccountJsonConfig": json.dumps(prod_bq_creds), "projectId": "prod-project", "enableStorageApi": True } }, "description": "Production BigQuery warehouse" }, "Staging BigQuery": { "type": "bigquery", "details": { "bigquery": { "serviceAccountJsonConfig": json.dumps(staging_bq_creds), "projectId": "staging-project", "enableStorageApi": True } }, "description": "Staging BigQuery warehouse" }, "Production Snowflake": { "type": "snowflake", "details": { "snowflake": { "account": "prod-account", "warehouse": "PROD_WH", "database": "PROD_DB", "username": "hex_prod", "password": prod_sf_password } }, "description": "Production Snowflake warehouse" }, "Application DB": { "type": "postgres", "details": { "postgres": { "hostname": "prod-db.example.com", "port": 5432, "database": "app_db", "username": "readonly", "password": postgres_password, "ssl": True } }, "description": "Application database (read-only)" } } # Create all connections created_connections = {} for name, config in connection_configs.items(): connection = create_hex_data_connection( name=name, connection_type=config["type"], connection_details=config["details"], description=config["description"], include_magic=True, allow_writeback_cells=False, sharing={ "workspace": { "members": "CAN_USE" } } ) data = json.loads(connection) created_connections[name] = data["id"] print(f"Created {name}: {data['id']}") print(f"\nCreated {len(created_connections)} data connections") ``` **Data Connection Management Notes**: - Supported connection types: BigQuery, Snowflake, Postgres, Redshift, Athena, Databricks - Each connection type has specific configuration requirements in `connection_details` - Connection credentials are stored securely by Hex - Use sharing settings to control who can use each connection - `CAN_USE` access allows users to query data, `CAN_ADMIN` allows configuration changes - SSH tunneling supported via `connect_via_ssh` parameter for secure connections - Consider using connection-level access control for sensitive data sources ## About This Fork This fork extends the upstream hex-mcp package with bug fixes and new cell operations functionality. ### Bug Fixes (v0.1.10 upstream) - Five tools declared `-> str` return type but returned Python dicts/lists - Caused pydantic validation errors in Claude Code MCP integration - Fixed by adding `json.dumps()` to return statements in `src/hex_mcp/server.py` **Fixed Tools** (lines 74, 172, 187, 206, 229): - `list_hex_projects()` - `get_hex_project()` - `get_hex_run_status()` - `get_hex_project_runs()` - `run_hex_project()` ### New Features **Cell Operations** (Phase 1 of complete Hex API implementation): - `list_hex_cells()` - Read notebook structure and cell source code (SQL/CODE cells) - `update_hex_cell()` - Update SQL/CODE cell source and data connections - Comprehensive test suite with 29 passing tests (all mocked, no credentials required) - Full documentation with usage examples for query migration and code refactoring **Permission Management** (Phase 2 of complete Hex API implementation): - `update_hex_project_user_sharing()` - Grant or revoke user access to projects - `update_hex_project_group_sharing()` - Grant or revoke group access to projects - `update_hex_project_collection_sharing()` - Add or remove projects from collections - `update_hex_project_workspace_sharing()` - Manage workspace-wide and public access - 18 additional passing tests for all sharing scenarios - Complete examples for bulk permission management **Collection Management** (Phase 3 of complete Hex API implementation): - `list_hex_collections()` - List all collections in workspace - `get_hex_collection()` - Get collection details with sharing settings - `create_hex_collection()` - Create collections with optional sharing - `update_hex_collection()` - Update collection metadata and sharing - 18 additional passing tests for collection CRUD operations - Complete examples for workspace organization by department **Group Management** (Phase 4 of complete Hex API implementation): - `list_hex_groups()` - List all groups in workspace - `get_hex_group()` - Get group details - `create_hex_group()` - Create groups with optional initial members - `update_hex_group()` - Update group name and membership (add/remove up to 100 users) - `delete_hex_group()` - Delete groups from workspace - 21 additional passing tests for full group CRUD operations - Complete examples for department-based group management and team reorganization - All functions include comprehensive Google-style docstrings **Data Connection Management** (Phase 5 of complete Hex API implementation): - `list_hex_data_connections()` - List all data connections with pagination and sorting - `get_hex_data_connection()` - Get connection details including credentials and sharing - `create_hex_data_connection()` - Create BigQuery, Snowflake, Postgres, Redshift, Athena, Databricks connections - `update_hex_data_connection()` - Update connection configuration, credentials, and sharing settings - 18 additional passing tests for data connection CRUD operations - Complete examples for connection setup, credential rotation, and bulk deployment - Support for all 6 major database/warehouse connection types - Full Google-style docstrings with detailed connection type specifications **Testing Infrastructure**: - Comprehensive test fixtures with mocked authentication - 105 passing tests, 0 skipped (all mocked, no credentials required) - Test coverage growing with each phase - Security checks to prevent production credentials in tests - pytest, pytest-asyncio, pytest-cov integration - Fixed backoff handler to work in both production and test environments **Documentation**: - Complete OpenAPI spec analysis (see `OPENAPI-VALIDATION.md`) - Detailed implementation plan (see `IMPLEMENTATION-PLAN.md`) - Test strategy guide (see `TEST-STRATEGY.md`) - Usage examples for all new features **Upstream**: https://github.com/franccesco/hex-mcp **Status**: Branch `bugfix/fast-mcp-return-types` includes both bug fixes and new cell operations functionality. Ready for upstream PR submission if desired.