Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.hopx.ai/llms.txt

Use this file to discover all available pages before exploring further.

Give your AI assistant superpowers with secure, isolated code execution through the Model Context Protocol (MCP). The HopX MCP server enables Claude, Cursor, and other AI assistants to execute Python, JavaScript, Bash, and Go code in blazing-fast (0.1s startup), isolated cloud containers.
MCP is a protocol that allows AI assistants to interact with external tools and services. The HopX MCP server provides a standardized way for AI assistants to execute code safely in isolated environments.

​
What You’ll Learn

In this guide, you’ll learn how to:
  • Install the HopX MCP server using uvx
  • Configure MCP server in Cursor, VS Code, Claude Desktop, and other IDEs
  • Enable AI assistants to execute code in isolated sandboxes
  • Use different execution modes (isolated, persistent, rich, background)
  • Set up multi-step workflows and rich output capture
  • Understand security and best practices for MCP integration

​
Prerequisites

Before you begin, make sure you have:
  • Python 3.14+ installed (required for uvx)
  • uvx installed (get it from uv’s documentation)
  • HopX API key from hopx.ai
  • MCP-compatible IDE (Cursor, VS Code, Claude Desktop, Windsurf, etc.)
  • Basic familiarity with your IDE’s configuration files

​
Quick Start

The easiest way to get started:
  1. Install the MCP server: uvx HopX-mcp
  2. Get your API key from hopx.ai
  3. Configure your IDE with the MCP server
  4. Your AI assistant can now execute code safely

​
Installation

Install the HopX MCP server using uvx: 
uvx hopx-mcp
You need Python 3.14+ and uvx installed. Get uvx from uv’s documentation.

​
Get Your API key

Sign up at hopx.ai to get your free API key. You’ll need this to configure the MCP server.

​
Configuration

After installing with uvx hopx-mcp, configure your IDE by adding the MCP server configuration:
Add to .cursor/mcp.json in your project or workspace:
{
  "mcpServers": {
    "HopX-sandbox": {
      "command": "uvx",
      "args": ["hopx-mcp"],
      "env": {
        "HOPX_API_KEY": "your-API key-here"
      }
    }
  }
}
Replace your-API key-here with your actual API key from hopx.ai.

​
What This Enables

With the HopX MCP server, your AI assistant can:
  • ✅ Execute Python, JavaScript, Bash, and Go in isolated containers
  • ✅ Analyze data with pandas, numpy, matplotlib (pre-installed)
  • ✅ Test code snippets before you use them in production
  • ✅ Process data securely without touching your local system
  • ✅ Run system commands safely in isolated environments
  • ✅ Install packages and test integrations on-the-fly
All executions happen in secure, ephemeral cloud containers that auto-destroy after use. Your local system stays clean and protected.

​
Execution Modes

The HopX MCP server provides a unified execute_code() function with multiple execution modes:
  • isolated (default) - One-shot execution: Creates a new sandbox, executes code, returns output, and auto-destroys. Perfect for quick scripts and data analysis.
  • persistent - Execute in an existing sandbox: Use for multi-step workflows where you need to maintain state between executions.
  • rich - Execute with rich output capture: Automatically captures matplotlib plots, pandas DataFrames, and other visualizations.
  • background - Non-blocking execution: Starts code execution in the background and returns immediately with a process ID.
For most use cases, use mode="isolated" for quick, one-off code execution. The sandbox is automatically created and destroyed, so you don’t need to manage the lifecycle.

​
Advanced Usage

​
Multi-Step Workflows

For workflows that require multiple steps (e.g., installing packages, then running code), create a persistent sandbox: You: “Install pandas and analyze this data: [1, 2, 3, 4, 5]” Claude: Creates a sandbox, then executes multiple commands:
  1. create_sandbox(template_id="code-interpreter") - Creates a persistent sandbox
  2. execute_code(sandbox_id="...", code="pip install pandas", mode="persistent") - Installs package
  3. execute_code(sandbox_id="...", code="import pandas as pd; ...", mode="persistent") - Runs analysis
  4. delete_sandbox(sandbox_id="...") - Cleans up

​
Rich Output Capture

For data visualization, use mode="rich" to automatically capture plots and DataFrames: You: “Create a plot of [1, 2, 3, 4, 5]” Claude: Uses rich mode to capture the visualization: 
result = execute_code(
    sandbox_id=sandbox_id,
    code="import matplotlib.pyplot as plt; plt.plot([1,2,3,4,5]); plt.savefig('/tmp/plot.png')",
    mode="rich"
)
# result["rich_outputs"] contains the captured plot

​
Next Steps

Now that you’ve set up MCP integration, explore more: