HOPX MCP Server: Sub-150ms Containerized Code Execution

Overview

HOPX MCP Server implements the Model Context Protocol (MCP) to provide fast, containerized code execution environments for AI assistants and developer tooling. It exposes lightweight sandboxes that can run Python, JavaScript, Bash and Go in isolated containers with common data‑science packages preinstalled (pandas, numpy, matplotlib). The server is designed for low-latency interactive use—single-shot execution paths typically complete in under 150ms after warmup—making it suitable for code interpreters, notebook integrations, and assistant workflows that need safe, transient compute.

The server runs as a local MCP server process (CLI: uvx hopx-mcp) and authenticates using an API key. It supports both one-shot isolated execution and longer-lived sandboxes for multi-step work (file IO, background processes, persistent state). Containers are ephemeral and auto-clean up to prevent resource leaks and maintain isolation between tasks.

Features

• Sub-150ms one-shot execution for warmed containers (very low latency)
• Languages: Python, Node.js (JavaScript), Bash, Go
• Data science stack preinstalled: pandas, numpy, matplotlib (plus scipy, scikit-learn)
• One-shot isolated execution and persistent sandbox sessions
• File operations: read/write/list/remove, mkdir, existence checks
• Shell commands and background process support
• Webhook/async execution for long-running jobs
• JWT-based authentication and per-sandbox isolation
• Configurable sandbox lifetime and auto-cleanup
• Internet access enabled by default (configurable)

Installation / Configuration

Prerequisites: Python 3.14+ runtime for the MCP server process (packaged as a CLI tool).

Install and run:

# install and expose the MCP server command
uvx hopx-mcp

# set your API key (Linux / macOS)
export HOPX_API_KEY="your-api-key"

# optional: override base API URL
export HOPX_BASE_URL="https://api.hopx.dev"

Quick check: run the server and verify it starts. Client integrations (IDE, assistant) call the uvx hopx-mcp command and provide HOPX_API_KEY in the environment.

IDE configuration (example JSON, VS Code / other MCP-aware tools):

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

Replace the config file target (e.g., .vscode/mcp.json, ~/.config/your-ide/mcp.json) according to your tool.

Available Tools / API Surface

High-level operations exposed by the MCP server:

• Sandbox management
  • create_sandbox(template_id, timeout_seconds)
  • list_sandboxes()
  • delete_sandbox(sandbox_id)
• Code execution
  • execute_code_isolated(code, language, timeout) — recommended for short, single-run tasks
  • execute_code(sandbox_id, code) — runs in an existing sandbox
  • execute_code_background(…) / execute_code_async(…) — for long-running tasks or webhook callbacks
• File operations
  • file_read(), file_write(), file_list(), file_remove(), file_mkdir(), file_exists()
• Shell / environment
  • run_command(), run_command_background()
  • env_get(), env_set(), env_clear()

Typical one-shot response shape:

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

Supported Languages (summary)

Use Cases

• Interactive code evaluation for assistant responses
  • Run small Python snippets (data parsing, quick transforms) and return results in conversational flows.
• Data analysis and visualization
  • Load datasets in pandas and produce plots via matplotlib; read/write temporary files and return image artifacts.
• Tooling and automation
  • Run shell commands or small Go programs to inspect remote resources or perform reproducible tasks.
• Multi-step computations
  • Create a persistent sandbox to maintain state across multiple steps (load data, run transformations, save outputs).
• Background jobs
  • Launch long-running processing tasks with background execution and webhook callbacks for completion.

Concrete examples:

One-shot execution (Python):

execute_code_isolated(
    code='import sys\nprint("Hello, World!")',
    language='python',
    timeout=30
)

Persistent sandbox example:

# create persistent environment
sandbox = create_sandbox(template_id='code-interpreter', timeout_seconds=3600)
sid = sandbox['id']

# run multiple operations
execute_code(sid, 'import pandas as pd')
execute_code(sid, 'df = pd.DataFrame({"x":[1,2,3]})\ndf.to_csv("/workspace/data.csv", index=False)')
content = file_read(sid, '/workspace/data.csv')

# cleanup
delete_sandbox(sid)

Performance, Limits & Security

• Typical sandbox creation: ~200ms; container cold-start ~0.1–3s depending on first-auth flows.
• One-shot executions for warmed sandboxes often complete under 150ms.
• Default sandbox lifetime / auto-cleanup: 600s (configurable).
• Max synchronous execution: ~300 seconds (longer jobs via async/webhook).
• Security: containers are isolated from the host and from each other; JWT auth is used. Internet access is enabled by default—treat sensitive data accordingly and adjust configuration per policy.

Troubleshooting & Resources

Common issues:

• 401 Unauthorized: verify HOPX_API_KEY is set and valid.
• Template not found: list_templates() to discover available templates.
• Slow first-run: cold-start overhead; subsequent runs are faster.

Learn more:

• GitHub: https://github.com/hopx-ai/mcp
• Docs and support: https://docs.hopx.ai
• License: MIT (see repository LICENSE)

This server is intended as a developer-facing MCP endpoint for integrating fast, isolated code execution into assistant workflows and developer tools.