Content
# HOPX MCP Server
Model Context Protocol (MCP) server for [HOPX](https://hopx.ai). Enables AI assistants to execute code in isolated cloud containers.
**MCP Name:** `io.github.hopx-ai/hopx-mcp`
[](LICENSE)
[](https://python.org)
[](https://modelcontextprotocol.io)
## Installation
```bash
uvx hopx-mcp
```
Get your API key at [hopx.ai](https://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](https://hopx.ai).
### Configure IDE
Add MCP server configuration to your IDE:
<details>
<summary><b>Claude Desktop</b></summary>
Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
```json
{
"mcpServers": {
"hopx-sandbox": {
"command": "uvx",
"args": ["hopx-mcp"],
"env": {
"HOPX_API_KEY": "your-api-key-here"
}
}
}
}
```
Restart Claude Desktop after configuration.
</details>
<details>
<summary><b>Cursor</b></summary>
Add to `.cursor/mcp.json`:
```json
{
"mcpServers": {
"hopx-sandbox": {
"command": "uvx",
"args": ["hopx-mcp"],
"env": {
"HOPX_API_KEY": "your-api-key-here"
}
}
}
}
```
</details>
<details>
<summary><b>VS Code</b></summary>
Add to `.vscode/mcp.json`:
```json
{
"mcpServers": {
"hopx-sandbox": {
"command": "uvx",
"args": ["hopx-mcp"],
"env": {
"HOPX_API_KEY": "your-api-key-here"
}
}
}
}
```
</details>
<details>
<summary><b>Other IDEs</b></summary>
Configuration format varies by IDE. Add these parameters:
- Command: `uvx`
- Args: `["hopx-mcp"]`
- Environment: `HOPX_API_KEY=your-api-key-here`
</details>
---
## Usage
### Quick Execution
```python
execute_code_isolated(
code='print("Hello, World!")',
language='python',
timeout=30
)
```
**Returns:**
```python
{
'stdout': 'Hello, World!\n',
'exit_code': 0,
'execution_time': 0.123,
'sandbox_id': '1762778786mxaco6r2'
}
```
### Persistent Sandbox
For multiple operations in the same environment:
```python
# 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:**
```bash
HOPX_API_KEY=your-api-key
```
**Optional:**
```bash
HOPX_BASE_URL=https://api.hopx.dev # default
```
---
## Troubleshooting
### "401 Unauthorized"
API key not set or invalid.
**Solution:**
```bash
echo $HOPX_API_KEY # Verify key is set
```
### "Template not found"
Invalid template name.
**Solution:**
```python
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](https://docs.hopx.ai)
- Issues: [GitHub](https://github.com/hopx-ai/mcp/issues)
- Email: support@hopx.ai
---
## License
MIT License. See [LICENSE](LICENSE) for details.
HOPX Terms of Service: [hopx.ai/terms](https://hopx.ai/terms)
---
## Technical Details
Built with:
- [hopx-ai SDK](https://github.com/hopx-ai/hopx-python-sdk) v0.2.7
- [FastMCP](https://github.com/jlowin/fastmcp) framework
- [Model Context Protocol](https://modelcontextprotocol.io)
---
[Website](https://hopx.ai) | [Documentation](https://docs.hopx.ai) | [GitHub](https://github.com/hopx-ai/mcp)
MCP Store
