> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hopx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server Integration

> Enable AI assistants to execute code in isolated HopX sandboxes using the Model Context Protocol. Connect Claude, Cursor, and other AI assistants to HopX for secure code execution.

Give your AI assistant **superpowers** with secure, isolated code execution through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io). The HopX MCP server enables Claude, Cursor, and other AI assistants to execute Python, JavaScript, Bash, and Go code in blazing-fast (0.1s startup), isolated cloud containers.

<Info>
  MCP is a protocol that allows AI assistants to interact with external tools and services. The HopX MCP server provides a standardized way for AI assistants to execute code safely in isolated environments.
</Info>

## What You'll Learn

In this guide, you'll learn how to:

* Install the HopX MCP server using `uvx`
* Configure MCP server in Cursor, VS Code, Claude Desktop, and other IDEs
* Enable AI assistants to execute code in isolated sandboxes
* Use different execution modes (isolated, persistent, rich, background)
* Set up multi-step workflows and rich output capture
* Understand security and best practices for MCP integration

## Prerequisites

Before you begin, make sure you have:

* **Python 3.14+** installed (required for `uvx`)
* **`uvx`** installed (get it from [uv's documentation](https://docs.astral.sh/uv/))
* **HopX API key** from [hopx.ai](https://hopx.ai)
* **MCP-compatible IDE** (Cursor, VS Code, Claude Desktop, Windsurf, etc.)
* Basic familiarity with your IDE's configuration files

## Quick Start

The easiest way to get started:

1. Install the MCP server: `uvx HopX-mcp`
2. Get your API key from [hopx.ai](https://hopx.ai)
3. Configure your IDE with the MCP server
4. Your AI assistant can now execute code safely

## Installation

Install the HopX MCP server using `uvx`:

```bash theme={null}
uvx hopx-mcp
```

<Warning>
  You need Python 3.14+ and `uvx` installed. Get `uvx` from [uv's documentation](https://docs.astral.sh/uv/).
</Warning>

## Get Your API key

Sign up at [hopx.ai](https://hopx.ai) to get your free API key. You'll need this to configure the MCP server.

## Configuration

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

<Tabs>
  <Tab title="Cursor">
    Add to `.cursor/mcp.json` in your project or workspace:

    ```json theme={null}
    {
      "mcpServers": {
        "HopX-sandbox": {
          "command": "uvx",
          "args": ["hopx-mcp"],
          "env": {
            "HOPX_API_KEY": "your-API key-here"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="VS Code">
    Add to `.vscode/mcp.json` in your workspace:

    ```json theme={null}
    {
      "mcpServers": {
        "HopX-sandbox": {
          "command": "uvx",
          "args": ["hopx-mcp"],
          "env": {
            "HOPX_API_KEY": "your-API key-here"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Desktop">
    Add to `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS or `%APPDATA%\Claude\claude_desktop_config.json` on Windows:

    ```json theme={null}
    {
      "mcpServers": {
        "HopX-sandbox": {
          "command": "uvx",
          "args": ["hopx-mcp"],
          "env": {
            "HOPX_API_KEY": "your-API key-here"
          }
        }
      }
    }
    ```

    Restart Claude Desktop after making changes.
  </Tab>

  <Tab title="Windsurf">
    Add to `.windsurf/mcp.json` in your project:

    ```json theme={null}
    {
      "mcpServers": {
        "HopX-sandbox": {
          "command": "uvx",
          "args": ["hopx-mcp"],
          "env": {
            "HOPX_API_KEY": "your-API key-here"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Other IDEs">
    For other IDEs (Visual Studio, Cline, Continue.dev, Zed, Codex), use a similar configuration structure. Refer to your IDE's MCP documentation for the exact configuration file location and format.
  </Tab>
</Tabs>

Replace `your-API key-here` with your actual API key from [hopx.ai](https://hopx.ai).

## What This Enables

With the HopX 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.

## Execution Modes

The HopX MCP server provides a unified `execute_code()` function with multiple execution modes:

* **`isolated`** (default) - One-shot execution: Creates a new sandbox, executes code, returns output, and auto-destroys. Perfect for quick scripts and data analysis.
* **`persistent`** - Execute in an existing sandbox: Use for multi-step workflows where you need to maintain state between executions.
* **`rich`** - Execute with rich output capture: Automatically captures matplotlib plots, pandas DataFrames, and other visualizations.
* **`background`** - Non-blocking execution: Starts code execution in the background and returns immediately with a process ID.

<Tip>
  For most use cases, use `mode="isolated"` for quick, one-off code execution. The sandbox is automatically created and destroyed, so you don't need to manage the lifecycle.
</Tip>

## Advanced Usage

### Multi-Step Workflows

For workflows that require multiple steps (e.g., installing packages, then running code), create a persistent sandbox:

**You:** "Install pandas and analyze this data: \[1, 2, 3, 4, 5]"

**Claude:** *Creates a sandbox, then executes multiple commands:*

1. `create_sandbox(template_id="code-interpreter")` - Creates a persistent sandbox
2. `execute_code(sandbox_id="...", code="pip install pandas", mode="persistent")` - Installs package
3. `execute_code(sandbox_id="...", code="import pandas as pd; ...", mode="persistent")` - Runs analysis
4. `delete_sandbox(sandbox_id="...")` - Cleans up

### Rich Output Capture

For data visualization, use `mode="rich"` to automatically capture plots and DataFrames:

**You:** "Create a plot of \[1, 2, 3, 4, 5]"

**Claude:** *Uses rich mode to capture the visualization:*

```python theme={null}
result = execute_code(
    sandbox_id=sandbox_id,
    code="import matplotlib.pyplot as plt; plt.plot([1,2,3,4,5]); plt.savefig('/tmp/plot.png')",
    mode="rich"
)
# result["rich_outputs"] contains the captured plot
```

## Related

* **[LLM Integration](/guides/integrations/llm-integration)** - Integrate OpenAI, Anthropic, and other LLMs
* **[Quickstart Guide](/quickstart)** - Get started with HopX sandboxes
* **[Code Execution](/core-concepts/code-execution/synchronous)** - Learn about code execution concepts
* **[Creating Sandboxes](/core-concepts/sandboxes/creating)** - Understand sandbox creation

## Next Steps

Now that you've set up MCP integration, explore more:

* **Learn about code execution**: [Synchronous Execution](/core-concepts/code-execution/synchronous) and [Background Execution](/core-concepts/code-execution/background)
* **Explore templates**: [Listing Templates](/core-concepts/templates/listing) to find the right environment
* **Try rich output capture**: [Rich Output Capture](/core-concepts/code-execution/rich-output) for data visualization
* **Integrate with LLMs**: [LLM Integration Guide](/guides/integrations/llm-integration) for direct LLM integration
* **Review best practices**: [Cookbooks](/cookbooks/getting-started/first-sandbox) for real-world examples