hopx-mcp 0.2.0

MCP tool for executing code in isolated environments using HopX

HOPX MCP Server

Model Context Protocol (MCP) server for HOPX. Enables AI assistants to execute code in isolated cloud containers.

MCP Name: io.github.hopx-ai/hopx-mcp

Installation

uvx hopx-mcp

Get your API key at hopx.ai.

---

Capabilities

• Execute Python, JavaScript, Bash, and Go in isolated containers
• Data analysis with pandas, numpy, matplotlib (pre-installed)
• File operations and system commands
• Background processes and long-running tasks

Containers auto-destroy after use.

---

Configuration

Get API Key

Sign up at hopx.ai.

Configure IDE

Add MCP server configuration to your IDE:

Claude Desktop

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

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

Restart Claude Desktop after configuration.

Cursor

Add to .cursor/mcp.json:

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

VS Code

Add to .vscode/mcp.json:

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

Other IDEs

Configuration format varies by IDE. Add these parameters:

• Command: uvx
• Args: ["hopx-mcp"]
• Environment: HOPX_API_KEY=your-api-key-here

---

Usage

Quick Execution

execute_code_isolated(
    code='print("Hello, World!")',
    language='python',
    timeout=30
)

Returns:

{
    'stdout': 'Hello, World!\n',
    'exit_code': 0,
    'execution_time': 0.123,
    'sandbox_id': '1762778786mxaco6r2'
}

Persistent Sandbox

For multiple operations in the same environment:

# Create sandbox
sandbox = create_sandbox(
    template_id='code-interpreter',
    timeout_seconds=3600
)

sandbox_id = sandbox['id']

# Run operations
execute_code(sandbox_id, 'import pandas as pd')
execute_code(sandbox_id, 'df = pd.read_csv("data.csv")')
file_write(sandbox_id, '/workspace/output.txt', 'results')
content = file_read(sandbox_id, '/workspace/output.txt')

# Cleanup
delete_sandbox(sandbox_id)

---

Available Tools

Sandbox Management:

• create_sandbox() - Create sandbox
• list_sandboxes() - List sandboxes
• delete_sandbox() - Terminate sandbox

Code Execution:

• execute_code_isolated() - One-shot execution (recommended)
• execute_code() - Execute in existing sandbox
• execute_code_background() - Long-running tasks
• execute_code_async() - Webhook callbacks for 30+ min tasks

File Operations:

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

Commands:

• run_command() - Execute shell commands
• run_command_background() - Background processes

Environment:

• env_get(), env_set(), env_clear()

---

Supported Languages

• Python 3.11+ - pandas, numpy, matplotlib, scipy, scikit-learn, requests
• JavaScript/Node.js 20 - Standard libraries
• Bash - Unix utilities, git, curl, wget
• Go - Compilation support

---

Features

• Sandbox creation: ~200ms
• Container startup: ~0.1s
• Auto-cleanup: 600s (configurable)
• Internet access: Enabled by default
• Isolation: Complete per execution
• Authentication: JWT-based

---

Environment Variables

Required:

HOPX_API_KEY=your-api-key

Optional:

HOPX_BASE_URL=https://api.hopx.dev  # default

---

Troubleshooting

"401 Unauthorized"

API key not set or invalid.

Solution:

echo $HOPX_API_KEY  # Verify key is set

"Template not found"

Invalid template name.

Solution:

templates = list_templates(limit=20)  # Browse available templates

Slow First Execution

Container initializes in ~3 seconds after creation.

Cause: VM authentication setup Solution: Subsequent operations are immediate

---

Limitations

• Synchronous execution: Max 300 seconds
• Sandbox lifetime: Default 10 minutes (configurable)
• Template-specific language support

---

Security

Protected:

• Local system isolated from container execution
• Containers isolated from each other
• Auto-cleanup prevents resource leaks
• JWT authentication per sandbox

Considerations:

• Containers have internet access by default
• Code executed in HOPX cloud
• Follow your security policies for sensitive data

---

Support

• Documentation: docs.hopx.ai
• Issues: GitHub
• Email: [e-mail]

---

License

MIT License. See LICENSE for details.

HOPX Terms of Service: hopx.ai/terms

---

Technical Details

Built with:

• hopx-ai SDK v0.2.7
• FastMCP framework
• Model Context Protocol

---

Website | Documentation | GitHub