hopx-mcp 0.1.0

MCP tool for executing code in isolated environments using HopX

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.1ms startup), isolated cloud containers.

Quick Installation

Install HOPX MCP Server with one click in your favorite IDE:

Cursor

Click to install in Cursor. You'll need to add your HOPX API key after installation.

VS Code

Click to install in VS Code with MCP support.

Visual Studio

Click to install in Visual Studio with MCP support.

Claude Desktop

For Claude Desktop, download the .mcpb bundle (see Publishing .mcpb Bundle section) or configure manually 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.

---

Installation Methods

Option 1: Direct from GitHub (Recommended)

Use uvx to run directly from the GitHub repository:

uvx --from git+https://github.com/hopx-ai/mcp hopx-mcp

Option 2: After Publishing to PyPI

Once published to PyPI, you can install with:

uvx hopx-mcp

Option 3: Local Development

Clone and install for local development:

git clone https://github.com/hopx-ai/mcp.git
cd mcp
uv sync
export HOPX_API_KEY="your-api-key-here"

---

Configuration

Get Your API Key

Sign up at hopx.ai to get your API key.

Configure Your IDE

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": [
        "--from",
        "git+https://github.com/hopx-ai/mcp",
        "hopx-mcp"
      ],
      "env": {
        "HOPX_API_KEY": "your-api-key-here"
      }
    }
  }
}

After publishing to PyPI, simplify to:

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

Installation Button Config:

• The one-click install button uses this base64-encoded config:

  {"command":"uvx","args":["--from","git+https://github.com/hopx-ai/mcp","hopx-mcp"],"env":{"HOPX_API_KEY":""}}
  

• Base64: eyJjb21tYW5kIjogInV2eCIsICJhcmdzIjogWyItLWZyb20iLCAiZ2l0K2h0dHBzOi8vZ2l0aHViLmNvbS9ob3B4LWFpL21jcCIsICJob3B4LW1jcCJdLCAiZW52IjogeyJIT1BYX0FQSV9LRVkiOiAiIn19

VS Code

Add to .vscode/mcp.json in your workspace:

{
  "mcpServers": {
    "hopx-sandbox": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/hopx-ai/mcp",
        "hopx-mcp"
      ],
      "env": {
        "HOPX_API_KEY": "your-api-key-here"
      }
    }
  }
}

After publishing to PyPI:

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

Installation Button Config:

• The one-click install button uses separate query parameters for name and config:
  • Name: HOPX Sandbox (URL-encoded: HOPX%20Sandbox)
  • Config JSON (without name field):

    {"command":"uvx","args":["--from","git+https://github.com/hopx-ai/mcp","hopx-mcp"]}
    

  • Config URL-encoded: %7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22--from%22%2C%22git%2Bhttps%3A%2F%2Fgithub.com%2Fhopx-ai%2Fmcp%22%2C%22hopx-mcp%22%5D%7D
  • Full URL: vscode:mcp/install?name=HOPX%20Sandbox&config=<encoded-config>

Visual Studio

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "hopx-sandbox": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/hopx-ai/mcp",
        "hopx-mcp"
      ],
      "env": {
        "HOPX_API_KEY": "your-api-key-here"
      }
    }
  }
}

After publishing to PyPI:

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

Installation Button Config:

• The one-click install button uses this URL-encoded config with type and env:

  {"name":"HOPX Sandbox","type":"stdio","command":"uvx","args":["--from","git+https://github.com/hopx-ai/mcp","hopx-mcp"],"env":{"HOPX_API_KEY":""}}
  

• URL Encoded: %7B%22name%22%3A%22HOPX%20Sandbox%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22--from%22%2C%22git%2Bhttps%3A%2F%2Fgithub.com%2Fhopx-ai%2Fmcp%22%2C%22hopx-mcp%22%5D%2C%22env%22%3A%7B%22HOPX_API_KEY%22%3A%22%22%7D%7D

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": [
        "--from",
        "git+https://github.com/hopx-ai/mcp",
        "hopx-mcp"
      ],
      "env": {
        "HOPX_API_KEY": "your-api-key-here"
      }
    }
  }
}

After publishing to PyPI:

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

Restart Claude Desktop after configuration.

Cline (VS Code Extension)

Add to your VS Code settings or Cline configuration:

{
  "cline.mcpServers": {
    "hopx-sandbox": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/hopx-ai/mcp",
        "hopx-mcp"
      ],
      "env": {
        "HOPX_API_KEY": "your-api-key-here"
      }
    }
  }
}

Continue.dev

Add to ~/.continue/config.json:

{
  "mcpServers": {
    "hopx-sandbox": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/hopx-ai/mcp",
        "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": [
        "--from",
        "git+https://github.com/hopx-ai/mcp",
        "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": [
          "--from",
          "git+https://github.com/hopx-ai/mcp",
          "hopx-mcp"
        ],
        "env": {
          "HOPX_API_KEY": "your-api-key-here"
        }
      }
    }
  }
}

Codex

Add to your Codex MCP configuration file:

{
  "mcpServers": {
    "hopx-sandbox": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/hopx-ai/mcp",
        "hopx-mcp"
      ],
      "env": {
        "HOPX_API_KEY": "your-api-key-here"
      }
    }
  }
}

---

Publishing .mcpb Bundle

The .mcpb (MCP Bundle) format allows one-click installation in Claude Desktop and other MCP clients. To create and publish your bundle:

Creating the Bundle

1. Create the bundle structure:

   mkdir hopx-mcp-bundle
   cd hopx-mcp-bundle
   

2. Create manifest.json:

   {
     "name": "HOPX Sandbox",
     "version": "0.1.0",
     "description": "Execute code in isolated cloud containers",
     "author": "HOPX",
     "homepage": "https://hopx.ai",
     "repository": "https://github.com/hopx-ai/mcp",
     "license": "MIT",
     "config": {
       "command": "uvx",
       "args": ["--from", "git+https://github.com/hopx-ai/mcp", "hopx-mcp"],
       "env": {
         "HOPX_API_KEY": ""
       }
     },
     "requiredEnv": ["HOPX_API_KEY"]
   }
   

3. Create the bundle:

   zip -r hopx-mcp.mcpb manifest.json
   

Publishing the Bundle

1. Upload to GitHub Releases:

   • Create a new release on your GitHub repository
   • Attach the hopx-mcp.mcpb file
   • Users can download and double-click to install

2. Direct download link:

   [Download HOPX MCP Bundle](https://github.com/hopx-ai/mcp/releases/latest/download/hopx-mcp.mcpb)
   

3. Installation instructions for users:

   • Download the .mcpb file
   • Double-click the file (on supported platforms)
   • Or: Open Claude Desktop → Settings → MCP Servers → Install from Bundle
   • Enter your HOPX API key when prompted

After Publishing to PyPI

Update the bundle to use the simpler PyPI installation:

{
  "config": {
    "command": "uvx",
    "args": ["hopx-mcp"],
    "env": {
      "HOPX_API_KEY": ""
    }
  }
}

---

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.1ms
• 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

---

Testing

We've included a comprehensive test suite:

export HOPX_API_KEY="your-api-key"
cd bns-mcp
uv run python test_execute_isolated.py

Tests include:

• ✅ Python data analysis (pandas + numpy)
• ✅ JavaScript array processing
• ✅ Bash system commands
• ✅ Environment variable injection

---

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:

1. Create the container (~0.1ms)
2. Wait for VM auth init (~3 seconds)
3. 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)

Installation Button Not Working

Cause: IDE doesn't support deep link protocol or MCP not installed.

Solution:

1. Ensure your IDE supports MCP (see modelcontextprotocol.io)
2. Install MCP support if needed
3. Use manual configuration instead (see Configuration section)

---

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: [e-mail]
• Discord: Join our community

---

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Setup

# Clone the repository
git clone https://github.com/hopx-ai/mcp.git
cd mcp

# Install dependencies
uv sync

# Set up environment
export HOPX_API_KEY="your-api-key"

# Run tests
uv run python test_execute_isolated.py

# Run the server locally
uv run python hopx_mcp/server.py

---

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

---

Changelog

See CHANGELOG.md for version history and release notes.

---

Acknowledgments

Special thanks to:

• The Anthropic team for creating the Model Context Protocol
• The FastMCP community for their excellent framework
• All our contributors and early adopters

---

Made with ❤️ by HOPX

Website | Documentation | API Reference | GitHub