HOPX MCP Server

Give your AI assistant superpowers with secure, isolated code execution.

The official Model Context Protocol (MCP) server for HOPX. Enable Claude and other AI assistants to execute code in blazing-fast (0.1s startup), isolated cloud containers.

License

Installation

uvx hopx-mcp

Get your API key at hopx.ai and configure your IDE below.

What This Enables

With this 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.

Configuration

Get Your API Key

Configure Your IDE

After installing with uvx hopx-mcp, configure your IDE by adding the MCP server configuration:

Choose your IDE below for detailed configuration instructions:

Cursor

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.

VS Code

Add to .vscode/mcp.json in your 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.

Visual Studio

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "hopx-sandbox": {
      "type": "stdio",
      "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.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows:

{
  "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, then restart Claude Desktop.

Cline (VS Code Extension)

Add to your VS Code settings or Cline configuration:

{
  "cline.mcpServers": {
    "hopx-sandbox": {
      "command": "uvx",
      "args": ["hopx-mcp"],
      "env": {
        "HOPX_API_KEY": "your-api-key-here"
      }
    }
  }
}

Continue.dev

Add to ~/.continue/config.json:

{
  "mcpServers": {
    "hopx-sandbox": {
      "command": "uvx",
      "args": ["hopx-mcp"],
      "env": {
        "HOPX_API_KEY": "your-api-key-here"
      }
    }
  }
}

Windsurf

Add to .windsurf/mcp.json in your project:

{
  "mcpServers": {
    "hopx-sandbox": {
      "command": "uvx",
      "args": ["hopx-mcp"],
      "env": {
        "HOPX_API_KEY": "your-api-key-here"
      }
    }
  }
}

Zed

Add to your Zed settings or MCP configuration:

{
  "mcp": {
    "servers": {
      "hopx-sandbox": {
        "command": "uvx",
        "args": ["hopx-mcp"],
        "env": {
          "HOPX_API_KEY": "your-api-key-here"
        }
      }
    }
  }
}

Codex

Add to your Codex MCP configuration file:

{
  "mcpServers": {
    "hopx-sandbox": {
      "command": "uvx",
      "args": ["hopx-mcp"],
      "env": {
        "HOPX_API_KEY": "your-api-key-here"
      }
    }
  }
}

Usage Examples

Your AI assistant can now execute code directly. Here's what it looks like:

Python Data Analysis

You: "Analyze this sales data: [100, 150, 200, 180, 220]"

Claude: Uses execute_code_isolated() to run:

import pandas as pd
import numpy as np

sales = [100, 150, 200, 180, 220]
df = pd.DataFrame({'sales': sales})

print(f"Mean: ${df['sales'].mean():.2f}")
print(f"Median: ${df['sales'].median():.2f}")
print(f"Growth: {((sales[-1] - sales[0]) / sales[0] * 100):.1f}%")

Output:

Mean: $170.00
Median: $180.00
Growth: 120.0%

JavaScript Computation

You: "Calculate fibonacci numbers up to 100"

Claude: Executes:

function fibonacci(max) {
  const fib = [0, 1];
  while (true) {
    const next = fib[fib.length - 1] + fib[fib.length - 2];
    if (next > max) break;
    fib.push(next);
  }
  return fib;
}

console.log(fibonacci(100));

Output:

[0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]

Bash System Info

You: "What's the system architecture and available disk space?"

Claude: Runs:

echo "System: $(uname -s)"
echo "Architecture: $(uname -m)"
echo "Disk:"
df -h / | tail -1

Output:

System: Linux
Architecture: x86_64
Disk:
/dev/root        20G  1.9G   17G  10% /

Features

🚀 Blazing Fast

Sandbox creation in ~0.1s
Pre-warmed containers ready to execute
Global edge network for low latency

🔒 Secure by Default

Complete isolation per execution
No shared state between runs
JWT-based authentication
Auto-cleanup after timeout

🌐 Multi-Language Support

Python 3.11+ with pandas, numpy, matplotlib, scikit-learn
JavaScript/Node.js 20 with standard libraries
Bash with common Unix utilities
Go with compilation support

⚡ Pre-installed Packages

Python:

Data Science: pandas, numpy, matplotlib, scipy, scikit-learn
Web: requests, httpx, beautifulsoup4
Jupyter: ipykernel, jupyter-client

JavaScript:

Node.js 20.x runtime
iJavaScript kernel for notebooks

System:

git, curl, wget, vim, nano
Build tools: gcc, g++, make
Python package managers: pip, uv

🎯 Smart Defaults

Internet access enabled
600-second auto-destroy (configurable)
Request-specific environment variables
Automatic error handling

API Reference

Primary Tool: `execute_code_isolated()`

The recommended way to execute code. Creates a sandbox, runs your code, returns output, and auto-destroys.

result = execute_code_isolated(
    code='print("Hello, World!")',
    language='python',          # 'python', 'javascript', 'bash', 'go'
    timeout=30,                 # max 300 seconds
    env={'API_KEY': 'secret'},  # optional env vars
    template_name='code-interpreter',  # template to use
    region='us-east'            # optional: 'us-east', 'eu-west'
)

Returns:

{
    'stdout': 'Hello, World!\n',
    'stderr': '',
    'exit_code': 0,
    'execution_time': 0.123,
    'sandbox_id': '1762778786mxaco6r2',
    '_note': 'Sandbox will auto-destroy after 10 minutes'
}

Advanced: Persistent Sandboxes

For multi-step workflows where you need to maintain state:

# 1. Create a long-lived sandbox
sandbox = create_sandbox(
    template_id='20',  # or get ID from get_template('code-interpreter')
    timeout_seconds=3600,
    internet_access=True
)

# 2. Extract connection details
vm_url = sandbox['direct_url']
auth_token = sandbox['auth_token']

# 3. Run multiple commands
execute_code(vm_url, 'import pandas as pd', auth_token=auth_token)
execute_code(vm_url, 'df = pd.read_csv("data.csv")', auth_token=auth_token)
result = execute_code(vm_url, 'print(df.head())', auth_token=auth_token)

# 4. File operations
file_write(vm_url, '/workspace/output.txt', 'results', auth_token=auth_token)
content = file_read(vm_url, '/workspace/output.txt', auth_token=auth_token)

# 5. Clean up when done
delete_sandbox(sandbox['id'])

All Available Tools

The MCP server exposes 30+ tools for complete control:

Sandbox Management:

create_sandbox() - Create a new sandbox
list_sandboxes() - List all your sandboxes
get_sandbox() - Get sandbox details
delete_sandbox() - Terminate a sandbox
update_sandbox_timeout() - Extend runtime

Code Execution:

execute_code_isolated() - ⭐ Primary method (one-shot)
execute_code() - Execute in existing sandbox
execute_code_rich() - Capture matplotlib plots, DataFrames
execute_code_background() - Long-running tasks (5-30 min)
execute_code_async() - Very long tasks with webhooks (30+ min)

File Operations:

file_read(), file_write(), file_list()
file_exists(), file_remove(), file_mkdir()

Process Management:

list_processes() - All system processes
execute_list_processes() - Background executions
execute_kill_process() - Terminate process

Environment & System:

env_set(), env_get(), env_clear() - Manage env vars
get_system_metrics() - CPU, memory, disk usage
run_command() - Execute shell commands

Templates:

list_templates() - Browse available templates
get_template() - Get template details

Architecture

┌─────────────┐
│   Claude    │  Your AI Assistant
│  (MCP Host) │
└──────┬──────┘
       │ MCP Protocol
       │
┌──────▼──────┐
│  HOPX MCP   │  This Server
│   Server    │  (FastMCP)
└──────┬──────┘
       │ HTTPS/REST
       │
┌──────▼──────┐
│ HOPX Cloud  │  Isolated Containers
│  Sandboxes  │  • Python, JS, Bash, Go
└─────────────┘  • Auto-cleanup
                 • Global Edge Network

Environment Variables

Required

HOPX_API_KEY=your-api-key

Get your API key at hopx.ai

Optional

HOPX_BASE_URL=https://api.hopx.dev  # default
HOPX_BEARER_TOKEN=alternative-auth  # if using bearer token

Troubleshooting

"401 Unauthorized" Error

Cause: API key not set or invalid.

Solution:

# Verify your API key is set
echo $HOPX_API_KEY

# Or check your IDE config file
# See Configuration section for your IDE

"Template not found" Error

Cause: Invalid template name.

Solution: Use the default code-interpreter template or list available templates:

templates = list_templates(category='development', language='python')

Slow First Execution

Cause: Cold start - container is being created.

Why it happens: The first execution needs to:

Create the container (~0.1ms)
Wait for VM auth init (~3 seconds)
Execute your code

Solution: Subsequent executions in the same sandbox are instant. For frequently-used environments, consider creating a persistent sandbox.

Execution Timeout

Cause: Code took longer than the timeout limit.

Solution: Increase timeout or use background execution:

# Increase timeout
execute_code_isolated(code='...', timeout=300)  # max 300s

# Or use background for long tasks
proc = execute_code_background(vm_url, code='...', timeout=1800)

Limitations

VM Initialization: ~3 second wait after sandbox creation for auth
Execution Timeout: Maximum 300 seconds per synchronous execution
Sandbox Lifetime: Default 10 minutes (configurable up to hours)
Template-Specific: Some templates optimized for specific languages

Security

What's Protected

✅ Your local system - All code runs in isolated cloud containers✅ Container isolation - Each execution in a separate container✅ Network isolation - Containers can't access each other✅ Automatic cleanup - Resources destroyed after timeout✅ JWT authentication - Secure token-based auth per sandbox

What You Should Know

⚠️ Internet access - Containers can access the internet by default⚠️ Code visibility - Your code is sent to HOPX cloud for execution⚠️ Data handling - Follow your security policies for sensitive data

For sensitive workloads, contact us about private cloud deployments.

Support

Documentation: docs.hopx.ai
API Reference: api.hopx.dev
Issues: GitHub Issues
Email: [email protected]
Discord: Join our community

License

This MCP server is provided under the MIT License. See LICENSE for details.

See the HOPX Terms of Service for API usage terms.

Built With

FastMCP - Python framework for MCP servers
Model Context Protocol - Protocol for AI-tool integration
HOPX Sandbox API - Cloud container platform
uvx - Fast Python package installer and runner

Made with ❤️ by HOPX

Website | Documentation | API Reference | GitHub

HOPX MCP Server

Installation

What This Enables

Configuration

Get Your API Key

Configure Your IDE

Usage Examples

Python Data Analysis

JavaScript Computation

Bash System Info

Features

🚀 Blazing Fast

🔒 Secure by Default

🌐 Multi-Language Support

⚡ Pre-installed Packages

🎯 Smart Defaults

API Reference

Primary Tool: execute_code_isolated()

Advanced: Persistent Sandboxes

All Available Tools

Architecture

Environment Variables

Required

Optional

Troubleshooting

"401 Unauthorized" Error

"Template not found" Error

Slow First Execution

Execution Timeout

Limitations

Security

What's Protected

What You Should Know

Support

License

Built With

MCP Server · Populars

MCP Server · New

Primary Tool: `execute_code_isolated()`